תצוגות מקדימות של ווידג'טים שנוצרו מאפשרות לכם ליצור תצוגות מקדימות דינמיות ומותאמות אישית לווידג'טים שלכם, שמשקפות בצורה מדויקת איך הם יופיעו במסך הבית של המשתמש. API של הודעות בדחיפה מספק את התצוגות המקדימות, כלומר האפליקציה מספקת את התצוגה המקדימה בכל נקודה במהלך מחזור החיים שלה, בלי לקבל בקשה מפורשת ממארח הווידג'ט.
במדריך הזה מוסבר איך לספק תצוגות מקדימות לווידג'טים שמבוססים על Glance. אם הווידג'ט שלכם מיושם באמצעות RemoteViews, כדאי לעיין במאמר הוספת תצוגות מקדימות לכלי לבחירת הווידג'טים.
כדי לשפר את חוויית השימוש בכלי לבחירת הווידג'טים באפליקציה עבור ווידג'טים של Glance, כדאי לספק תצוגה מקדימה של הווידג'ט שנוצר באמצעות GlanceAppWidget.providePreview במכשירי Android מגרסה 15 ואילך, ולציין previewImage בגרסאות קודמות, וגם כגיבוי ב-Android מגרסה 15 ואילך אם תצוגה מקדימה שנוצרה לא זמינה.
יש מידע נוסף במאמר Enrich your app with live updates and widgets (הוספת ווידג'טים ועדכונים בזמן אמת לאפליקציה) ב-YouTube.
הגדרת האפליקציה לתצוגות מקדימות של ווידג'טים שנוצרו
כדי להציג תצוגות מקדימות של ווידג'טים שנוצרו במכשיר Android מגרסה 15 ואילך, קודם צריך להגדיר את הערך compileSdk ל-35 ומעלה בקובץ build.gradle של המודול כדי לספק RemoteViews לכלי לבחירת הווידג'טים.
אחר כך, אפליקציות יכולות להשתמש ב-setWidgetPreview ב-GlanceAppWidgetManager. כדי למנוע ניצול לרעה ולצמצם את הסיכונים לבריאות המערכת, setWidgetPreview הוא API עם הגבלת קצב של יצירת בקשות. מגבלת ברירת המחדל היא בערך שתי שיחות בשעה.
יצירת תצוגה מקדימה מעודכנת באמצעות Jetpack Glance
לגבי ווידג'טים שנוצרו באמצעות Jetpack Glance, צריך לבצע את הפעולות הבאות:
מבטלים את ההגדרה של הפונקציה
GlanceAppWidget.providePreviewכדי לספק את התוכן שניתן להגדיר לתצוגה המקדימה. כמו ב-provideGlance, טוענים את הנתונים של האפליקציה ומעבירים אותם לרכיב הניתן להגדרה של תוכן הווידג'ט, כדי שהנתונים בתצוגה המקדימה יהיו מדויקים. בניגוד ל-provideGlance, זוהי הגדרה יחידה ללא הגדרה מחדש או אפקטים.מבקשים להפעיל את
GlanceAppWidgetManager.setWidgetPreviewsכדי ליצור ולפרסם את התצוגה המקדימה.
אין קריאה חוזרת (callback) מהמערכת לספק תצוגות מקדימות, ולכן האפליקציה צריכה להחליט מתי לבקש להפעיל אל setWidgetPreviews. אסטרטגיית העדכון תלויה בתרחיש לדוגמה של הווידג'ט:
- אם הווידג'ט מכיל מידע סטטי או שהוא פעולה מהירה, צריך להגדיר את התצוגה המקדימה כשפותחים את האפליקציה בפעם הראשונה.
- אפשר להגדיר את התצוגה המקדימה אחרי שיש נתונים באפליקציה, למשל אחרי שהמשתמש נכנס לחשבון או אחרי ההגדרה הראשונית.
- אפשר להגדיר משימה תקופתית לעדכון התצוגות המקדימות בקצב שתבחרו.
פתרון בעיות שקשורות לתצוגות מקדימות שנוצרו
בעיה נפוצה היא שאחרי שיוצרים תצוגה מקדימה, יכול להיות שחסרים בתמונה המקדימה תמונות, סמלים או רכיבים אחרים בהשוואה לגודל של הווידג'ט. גודל החלון הנפתח מוגדר על ידי targetCellWidth ו-targetCellHeight אם הם צוינו, או על ידי minWidth ו-minHeight בקובץ המידע של ספק הווידג'ט של האפליקציה.
הסיבה לכך היא שב-Android, כברירת מחדל, מוצגים רק רכיבי שניתנים להגדרה שגלויים בגודל המינימלי של הווידג'ט. במילים אחרות, מערכת Android מגדירה כברירת מחדל את previewSizeMode כ-SizeMode.Single. הוא משתמש ב-android:minHeight וב-android:minWidth בקובץ ה-XML של ספק הווידג'ט של האפליקציה כדי לקבוע אילו רכיבים שניתן להגדיר אפשר לשלוף.
כדי לפתור את הבעיה, צריך לבטל את ההגדרה של previewSizeMode ב-GlanceAppWidget ולהגדיר אותה ל-SizeMode.Responsive, ולציין קבוצה של ערכי DpSize. כך מערכת Android יודעת את כל גודלי הפריסה שהיא צריכה לעבד לתצוגה המקדימה, ומוודאת שכל הרכיבים יוצגו בצורה נכונה.
אופטימיזציה לגורמי צורה ספציפיים. צריך לציין גודל אחד או שניים החל מהגודל המינימלי, בהתאם לנקודות העצירה של הווידג'ט. צריך לציין לפחות תמונה אחת לצורך תאימות לדורות קודמים.previewImage בהנחיות לעיצוב ווידג'טים מפורטים ערכי ה-DP המינימליים המתאימים לגדלים שונים של רשתות.
תאימות לדורות קודמים עם תצוגות מקדימות של ווידג'טים
כדי לאפשר לכלי לבחירת ווידג'טים במכשירים עם גרסאות Android שקדמו לגרסה 15 להציג תצוגות מקדימות של הווידג'ט שלכם, או כגיבוי לתצוגות מקדימות שנוצרו ב-Android מגרסה 15 ואילך, צריך לציין את המאפיין previewImage.
אם משנים את המראה של הווידג'ט, צריך לעדכן את תמונת התצוגה המקדימה.