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