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

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

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

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

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

<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>