בניית מארח ווידג'טים

מסך הבית של Android, הזמין ברוב המכשירים מבוססי Android, מאפשר משתמשים מטמיעים ווידג'טים של אפליקציות (או ווידג'טים) עבור גישה מהירה לתוכן. אם אתם מפתחים אפליקציה שתחלף את מסך הבית או אפליקציה דומה, תוכלו גם לאפשר למשתמשים להטמיע ווידג'טים על ידי הטמעת AppWidgetHost. רוב האפליקציות לא צריכות לעשות זאת, אבל אם אתם יוצרים מארח משלכם, חשוב להבין את ההתחייבויות החוזיות שהמארח מסכים להן באופן משתמע.

הדף הזה מתמקד בתחומי האחריות הכרוכים בהטמעה של תבנית מותאמת אישית AppWidgetHost לדוגמה ספציפית להטמעת AppWidgetHost, אפשר לעיין בקוד המקור של מסך הבית של Android‏ LauncherAppWidgetHost.

לפניכם סקירה של רמות ומושגים מרכזיים הקשורים להטמעת AppWidgetHost בהתאמה אישית:

• המארח של ווידג'ט האפליקציה: ה-AppWidgetHost מספק את האינטראקציה עם שירות AppWidget לאפליקציות שמטמיעות ווידג'טים בממשק המשתמש שלהן. AppWidgetHost חייב להיות מזהה ייחודי בחבילה של המארח עצמו. המזהה הזה נשמר בכל השימושים במארח. המזהה הוא בדרך כלל ערך מקודד מראש שמקצים באפליקציה.

• מזהה הווידג'ט של האפליקציה: לכל מופע של ווידג'ט מוקצה מזהה ייחודי בזמן הקישור. אפשר לעיין במאמר bindAppWidgetIdIfAllowed(), ולקבל מידע נוסף בקטע קישור ווידג'טים שבהמשך. המארח מקבל את המזהה הייחודי באמצעות allocateAppWidgetId() המזהה הזה נשמר בכל משך החיים של הווידג'ט עד שהוא נמחק מארח. כל מצב ספציפי למארח - כגון הגודל והמיקום של ווידג'ט — חייב להישאר על ידי חבילת האירוח ולהיות משויך המזהה של הווידג'ט של האפליקציה.

• תצוגת המארח של הווידג'ט של האפליקציה: AppWidgetHostView כמסגרת שהווידג'ט קשור אליו בכל פעם שצריך להציג אותו. ווידג'ט הוא המשויך ל-AppWidgetHostView בכל פעם שהווידג'ט מנופח מארח.

  • כברירת מחדל, המערכת יוצרת AppWidgetHostView, אבל המארח יכול ליצור מחלקה משנית משלו של AppWidgetHostView על ידי הרחבה שלה.
  • החל מ-Android 12 (רמת API 31), ב-AppWidgetHostView מופיעים השיטות setColorResources() ו-resetColorResources() לטיפול בצבע שעבר עומס דינמי. המארח/ת הוא האחראים על אספקת הצבעים לשיטות האלה.

• חבילת אפשרויות: ה-AppWidgetHost משתמש בחבילת האפשרויות כדי להעביר מידע ל-AppWidgetProvider לגבי אופן הצגת הווידג'ט – לדוגמה, רשימת טווחי הגדלים – ואם הווידג'ט מוצג במסך הנעילה או במסך הבית. המידע הזה מאפשר AppWidgetProvider יתאים את התוכן והמראה של הווידג'ט על סמך האופן שבו שבה הוא מוצג. אפשר להשתמש updateAppWidgetOptions() וגם updateAppWidgetSize() כדי לשנות חבילה של ווידג'ט. שתי השיטות האלה גורמות onAppWidgetOptionsChanged() קריאה חוזרת ל-AppWidgetProvider.

קישור ווידג'טים

כשמשתמש מוסיף ווידג'ט למארח, מתרחש תהליך שנקרא קישור. קישור מתייחס לשיוך של מזהה ווידג'ט מסוים של אפליקציה למארח ספציפי ול-AppWidgetProvider ספציפי.

קישור ממשקי API גם מאפשר למארח לספק ממשק משתמש מותאם אישית מחייבת. כדי להשתמש בתהליך הזה, האפליקציה צריכה להצהיר על ההרשאה BIND_APPWIDGET במניפסט של המארח:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

אבל זה רק השלב הראשון. בזמן הריצה, המשתמש צריך להעניק לאפליקציה הרשאה מפורשת להוסיף ווידג'ט למארח. כדי לבדוק אם לאפליקציה יש הרשאה להוסיף את הווידג'ט, משתמשים בשיטה bindAppWidgetIdIfAllowed(). אם הפונקציה bindAppWidgetIdIfAllowed() מחזירה את הערך false, האפליקציה צריכה להציג תיבת דו-שיח שבה המשתמש יתבקש להעניק הרשאה: 'אישור' להוספת הווידג'ט הנוכחי, או 'אישור תמיד' כדי לכסות את כל ההוספות העתידיות של ווידג'טים.

קטע הקוד הזה מציג דוגמה להצגת תיבת הדו-שיח:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

המארח צריך לבדוק אם הווידג'ט שהמשתמש הוסיף צריך הגדרה. למידע נוסף, ראו איך מאפשרים למשתמשים להגדיר ווידג'טים של אפליקציות.

תחומי האחריות של המארחים

ניתן לציין כמה הגדרות תצורה לווידג'טים באמצעות מטא-נתונים של AppWidgetProviderInfo. אפשר לאחזר את אפשרויות התצורה האלה, שמפורטות בהרחבה בקטעים הבאים, מהאובייקט AppWidgetProviderInfo שמשויך לספק הווידג'ט.

ללא קשר לגרסה של Android שאליה אתם מטרגטים, כל המארחים צריכים לבצע את הפעולות הבאות:

• כשמוסיפים ווידג'ט, מקצים לו מזהה ווידג'ט כפי שמתואר למעלה. כאשר הווידג'ט מוסר מהמארח, ניתן להתקשר deleteAppWidgetId() כדי להקצות את מזהה הווידג'ט.

• כשמוסיפים ווידג'ט, צריך לבדוק אם צריך להפעיל את פעילות ההגדרה. בדרך כלל, המארח צריך להפעיל את פעילות ההגדרה של הווידג'ט אם היא קיימת ולא מסומנת כאופציונלית, על ידי ציון הדגלים configuration_optional ו-reconfigurable. צפייה עדכון הווידג'ט מהפעילות של ההגדרה אפשר לקבל פרטים נוספים. זהו שלב הכרחי עבור ווידג'טים רבים לפני שהם יכולים להופיע.

  הערה: יש לטפל במקרים לא רגילים שבהם פעילות ההגדרה לא מחזירה נתונים או מסתיימת עם שגיאות.

• בווידג'טים מצוינים רוחב וגובה ברירת מחדל במטא-נתונים של AppWidgetProviderInfo. הערכים האלו מוגדרים בתאים, החל Android 12, אם targetCellWidth ו-targetCellHeight הם מוגדר, או dps אם צוינו רק minWidth ו-minHeight. מאפייני התאמת הגודל של ווידג'טים

  חשוב לוודא שהווידג'ט מוצג עם לפחות 100 דפים לדקה. עבור לדוגמה, מארחים רבים מיישרים סמלים וווידג'טים ברשת. בתרחיש הזה, ברירת המחדל, המארח מוסיף ווידג'ט באמצעות מספר התאים המינימלי לעמוד במגבלות של minWidth ו-minHeight.

בנוסף לדרישות המפורטות בקטע הקודם, גרסאות חדשות של הפלטפורמה מארח.

איך קובעים את הגישה בהתאם לגרסה של Android שמוגדרת לטירגוט

Android 12

ב-Android 12 (רמת API 31) יש List<SizeF> נוסף בחבילה שמכיל את רשימת הגדלים האפשריים ב-dps שיכולים להיות למכונה של הווידג'ט בחבילת האפשרויות. מספר הגדלים שאפשר לספק תלוי ביישום המארח. מארחים בדרך כלל לספק מכשירי טלפון בשתי גדלים - לאורך ולרוחב - ובארבעה גדלים למכשירים מתקפלים.

יש מגבלה של MAX_INIT_VIEW_COUNT (16) על מספר הערכים השונים של RemoteViews ש-AppWidgetProvider יכול לספק ל-RemoteViews. מאחר שאובייקטים מסוג AppWidgetProvider ממפים אובייקט RemoteViews לכל מידה ב-List<SizeF>, אין לספק יותר מ-MAX_INIT_VIEW_COUNT מידות.

Android 12 כולל גם את maxResizeWidth וגם maxResizeHeight ב-dps. מומלץ שווידג'ט שמשתמש לפחות באחד מהמאפיינים האלה לא יחרוג מהגודל שצוין במאפיינים.

מקורות מידע נוספים

• מידע נוסף זמין במסמכי העזרה של Glance.