‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

בקטע הקוד הבא אפשר לראות דוגמה לאופן הצגת תיבת הדו-שיח:

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

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

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

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

כל המארחים אחראים ל:

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

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

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

טיפים לגישה שלכם

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

חבילת האפשרויות יכולה להכיל את List<SizeF> שמכיל את רשימת הגדלים האפשריים ב-dps שמופע של ווידג'ט יכול לקבל. מספר המידות שמוצגות תלוי באופן ההטמעה של המארח. בדרך כלל המארחים מספקים שני גדלים לטלפונים – לאורך ולרוחב – וארבעה גדלים לטלפונים מתקפלים.

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

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

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

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