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

מסך הבית של 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. צפייה מאפייני גודל הווידג'ט.

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