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

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

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

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

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

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

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

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

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

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

כשמשתמש מוסיף ווידג'ט למארח, מתרחש תהליך שנקרא קישור. ‫Binding מתייחס לשיוך של מזהה ספציפי של ווידג'ט של אפליקציה למארח ספציפי ול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. מאפייני גודל הווידג'ט

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

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

קובעים את הגישה בהתאם לגרסת Android שאליה מכוונים

‫Android 12

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

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

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

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

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