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

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

אם רוצים לאפשר למשתמשים לקבוע את הגדרות הווידג'ט, צריך ליצור ווידג'ט הגדרה 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. מידע נוסף על להצהיר על הקובץ הזה כאן יש דוגמה איך להצהיר (declare) על פעילות ההגדרות האישיות:

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

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

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

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

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

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

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

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

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

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

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

   Kotlin

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

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }
   

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

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

   Kotlin

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

   Java

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);
   

3. מגדירים את הווידג'ט בהתאם להעדפות של המשתמש.

4. בסיום ההגדרה, מקבלים מופע AppWidgetManager בהתקשרות אל getInstance(Context):

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. לעדכן את הווידג'ט באמצעות הפריסה של RemoteViews באמצעות התקשרות updateAppWidget(int,RemoteViews):

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)
   

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);
   

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

   Kotlin

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

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();
   

לצפייה ListWidgetConfigureActivity.kt למשל, ב-GitHub.

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

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

הערה: האפשרויות האלה זמינות רק החל מ-Android 12 (רמת API 31). שלך יכולים לציין אותן בגרסאות קודמות של Android, אבל המערכת מתעלם מהן ופועלים לפי התנהגות ברירת המחדל.

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

כדי לאפשר למשתמשים להגדיר מחדש ווידג'טים קיימים, צריך לציין את reconfigurable לסמן ב- widgetFeatures של appwidget-provider. מומלץ לעיין במדריך להצהרה על קובץ אחד (AppWidgetProviderInfo.xml) לפרטים נוספים מידע. לדוגמה:

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

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

איור 1. הלחצן הגדרה מחדש לווידג'ט.

הערה: הדגל reconfigurable נוסף ל-Android 9 (רמת API 28), אבל היא לא הייתה נתמכת באופן נרחב עד Android 12.

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

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

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

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