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

מסך הבית של 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() כדי לשנות חבילה של ווידג'ט. שתי השיטות האלה מפעילות את הקריאה החוזרת (callback) 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.