תצוגות מקדימות של ווידג'טים שנוצרו מאפשרות לכם ליצור תצוגות מקדימות דינמיות ומותאמות אישית לווידג'טים שלכם, שמשקפות בצורה מדויקת איך הם יופיעו במסך הבית של המשתמש. 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 של המודול כדי להפעיל תצוגות מקדימות שנוצרו בכלי לבחירת הווידג'טים.
אחר כך, אפליקציות יכולות להשתמש ב-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 אחד כדי לתמוך בגרסאות Android ישנות יותר. בהנחיות לעיצוב ווידג'טים מפורטים ערכי ה-DP המינימליים המתאימים לגדלים שונים של רשתות.
תמיכה בגרסאות Android ישנות יותר
כדי להציג תצוגות מקדימות של ווידג'טים במכשירים עם Android מגרסה 14 ומטה, או כשאין תצוגה מקדימה שנוצרה ב-Android מגרסה 15 ומעלה, צריך לציין את המאפיין previewImage.
אם משנים את המראה של הווידג'ט, צריך לעדכן את תמונת התצוגה המקדימה.