המשתמשים יכולים להגדיר ווידג'טים של אפליקציות

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

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

הצהרה על פעילות ההגדרה

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

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

מצהירים על הפעילות בקובץ AppWidgetProviderInfo.xml באמצעות המאפיין android:configure. מידע נוסף על הצהרה על הקובץ הזה דוגמה להצהרה על פעילות ההגדרה:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

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

זה כל מה שצריך כדי להתחיל פעילות הגדרה. לאחר מכן, צריך להטמיע את הפעילות בפועל.

הטמעה של פעילות ההגדרה

יש שני דברים חשובים שצריך לזכור כשמטמיעים את הפעילות:

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

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

עדכון הווידג'ט מפעילות ההגדרה

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

סיכום של התהליך לעדכון תקין של הווידג'ט ולסגירה של פעילות ההגדרה:

1. קבלת מזהה הווידג'ט של האפליקציה מה-Intent שהפעיל את הפעילות:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. מגדירים את תוצאת הפעילות ל-RESULT_CANCELED.

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

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. הגדרת הווידג'ט בהתאם להעדפות המשתמש, למשל כתיבת הבחירות ל-DataStore קבוע או למסד נתונים מקומי.

4. בסיום ההגדרה, מאחזרים את GlanceId שמתאים למזהה הווידג'ט של הפלטפורמה:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. כדי לעדכן את תוכן הווידג'ט, צריך להפעיל את הפונקציה update suspend במופע GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. יוצרים את כוונת החזרה, מגדירים אותה עם תוצאת הפעילות ומסיימים את הפעילות:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

אפשרויות להגדרת הווידג'ט

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

המשתמשים יכולים להגדיר מחדש ווידג'טים שהוצבו

כדי לאפשר למשתמשים להגדיר מחדש ווידג'טים קיימים, צריך לציין את הדגל reconfigurable במאפיין widgetFeatures של appwidget-provider. לדוגמה:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

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

שימוש בהגדרת ברירת המחדל של הווידג'ט

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

דוגמה לאופן שבו מסמנים את פעילות ההגדרה כפעילות שניתן להגדיר מחדש וכפעילות אופציונלית:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>