יצירת ווידג'ט לאפליקציה באמצעות התכונה 'בקצרה'

בקטעים הבאים מוסבר איך ליצור ווידג'ט בסיסי לאפליקציה באמצעות Glance.

הצהרה על AppWidget בקובץ המניפסט

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

1. הארכת המינוי של מקלט AppWidget מ-GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. רושמים את הספק של הווידג'ט של האפליקציה בקובץ AndroidManifest.xml ובקובץ המטא-נתונים המשויך:

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

הוספת המטא-נתונים AppWidgetProviderInfo

לאחר מכן, פועלים לפי ההוראות במדריך יצירת ווידג'ט כדי ליצור ולהגדיר את פרטי הווידג'ט של האפליקציה בקובץ @xml/my_app_widget_info.

ההבדל היחיד ב-Glance הוא שאין קובץ initialLayout XML, אבל אתם חייבים להגדיר אחד. אתם יכולים להשתמש בפריסת הטעינה המוגדרת מראש שמופיעה בספרייה:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

הצהרה על קובץ ה-XML של AppWidgetProviderInfo

אובייקט AppWidgetProviderInfo מגדיר את התכונות החיוניות של הווידג'ט. מגדירים את AppWidgetProviderInfo בקובץ משאבי המטא-נתונים בפורמט XML (res/xml/my_app_widget_info.xml) בתוך רכיב <appwidget-provider>:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

מאפייני גודל הווידג'ט

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

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

בטבלה הבאה מפורטים מאפייני <appwidget-provider> שקשורים לגודל הווידג'ט:

דוגמה

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

• הרוחב של תא ברשת הוא 30dp והגובה הוא 50dp.
• מפרט המאפיינים הבא מסופק:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

החל מ-Android 12:

משתמשים במאפיינים targetCellWidth ו-targetCellHeight כמידת ברירת המחדל של הווידג'ט.

גודל הווידג'ט הוא 2x2 כברירת מחדל. אפשר לשנות את הגודל של הווידג'ט ל-2x1 או ל-4x3.

Android מגרסה 11 ומטה:

כדי לחשב את גודל ברירת המחדל של הווידג'ט, משתמשים במאפיינים minWidth ו-minHeight.

רוחב ברירת המחדל = Math.ceil(80 / 30) = 3

גובה ברירת המחדל = Math.ceil(80 / 50) = 2

גודל הווידג'ט הוא 3x2 כברירת מחדל. אפשר לשנות את הגודל של הווידג'ט ל-2x1 או למסך מלא.

מאפיינים נוספים של ווידג'טים

בטבלה הבאה מתוארים מאפייני <appwidget-provider> שקשורים לתכונות אחרות מלבד גודל הווידג'ט.

הגדרה של GlanceAppWidget

1. יוצרים מחלקה חדשה שמתרחבת מ-GlanceAppWidget ומבטלת את השיטה provideGlance. זו השיטה שבה אפשר לטעון נתונים שנדרשים לעיבוד הווידג'ט:

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. יוצרים מופע שלו ב-glanceAppWidget ב-GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

הגדרתם עכשיו AppWidget באמצעות Glance.

שימוש במחלקה GlanceAppWidgetReceiver לטיפול בשידורי ווידג'טים

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

הצהרה על ווידג'ט במניפסט

מצהירים על מחלקת המשנה של המחלקה GlanceAppWidgetReceiver כ-broadcast receiver בקובץ AndroidManifest.xml:

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

רכיב <receiver> דורש את המאפיין android:name, שמציין את מחלקת המקבל. המקבל צריך לאשר את פעולת השידור ACTION_APPWIDGET_UPDATE בתוך <intent-filter>.

ברכיב <meta-data> צריך לציין את השם שלו כ-android.appwidget.provider, ובמאפיין android:resource צריך להפנות למשאב המטא-נתונים של XML של AppWidgetProviderInfo (@xml/my_app_widget_info).

הטמעה של המחלקה GlanceAppWidgetReceiver

ב-Glance, מרחיבים את GlanceAppWidgetReceiver במקום את AppWidgetProvider ישירות. כדי להטמיע אותו, מקשרים את המקלט למופע GlanceAppWidget. הקריאות החוזרות העיקריות שזמינות ב-GlanceAppWidgetReceiver פועלות באופן הבא:

• ‫onUpdate(): המערכת מחליפה את הערך הזה באופן אוטומטי ב-Glance כדי לבצע עדכונים של קומפוזיציה. אם מבטלים את ברירת המחדל של onUpdate באופן ידני, צריך להפעיל את super.onUpdate כדי לאפשר ל-Glance להפעיל בהצלחה את שרשורי ההרכבה.
• ‫onAppWidgetOptionsChanged(): מופעל כשממקמים את הווידג'ט בפעם הראשונה או כשמשנים את הגודל שלו. האפשרויות של קריאה מהירה מאגדות פריטים מתחת לפני השטח, כך שהפריסה מותאמת בצורה חלקה על סמך המאפיינים בזמן הריצה.
• ‫onDeleted(Context, IntArray): מופעל בכל פעם שמשתמש מוחק מופע ספציפי של ווידג'ט.
• ‫onEnabled(Context): מופעל כשמופע הווידג'ט הראשון נוצר בהצלחה. מצוין להפעלת העברות גלובליות.
• ‫onDisabled(Context): מופעלת כשמסירים את המופע הפעיל האחרון של הספק.
• ‫onReceive(Context, Intent): חוסם כל שידור של פלטפורמה לפני שיטות ספציפיות של קריאה חוזרת (callback). צריך לוודא שכל לוגיקה של מקלט מותאם אישית שכותבים קוראת ל-super.onReceive(context, intent) ולעולם לא קוראת ל-goAsync בעצמכם, כי Glance מעביר עבודה באופן אוטומטי ואסינכרוני.

קבלת כוונות שידור של ווידג'טים

מתחת לפני השטח, GlanceAppWidgetReceiver מסנן את כוונות השידור של הווידג'טים הבסיסיים של הפלטפורמה ומטפל בהן:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

יצירת ממשק משתמש

בקטע הקוד הבא אפשר לראות איך יוצרים את ממשק המשתמש:

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

דוגמת הקוד שלמעלה מבצעת את הפעולות הבאות:

• ברמה העליונה Column, הפריטים מוצבים אחד אחרי השני בצורה אנכית.
• הגודל של Column מתרחב כדי להתאים לשטח הזמין (באמצעות GlanceModifier), והתוכן שלו מיושר לחלק העליון (verticalAlignment) ומומרכז אופקית (horizontalAlignment).
• התוכן של Column מוגדר באמצעות ה-lambda. הסדר חשוב.
  • הפריט הראשון ב-Column הוא רכיב Text עם 12.dp של ריווח פנימי.
  • הפריט השני הוא Row, שבו הפריטים מוצבים אופקית זה אחרי זה, עם שני Buttons במרכז אופקית (horizontalAlignment). התצוגה הסופית תלויה במקום הפנוי. התמונה הבאה היא דוגמה לאופן שבו היא עשויה להיראות:

אתם יכולים לשנות את ערכי היישור או להחיל ערכי שינוי שונים (כמו ריווח פנימי) כדי לשנות את המיקום והגודל של הרכיבים. רשימה מלאה של הרכיבים, הפרמטרים והמשנים הזמינים לכל מחלקה מופיעה במסמכי העזר.

הטמעה של פינות מעוגלות

ב-Android 12 נוספו פרמטרים של המערכת שמאפשרים להתאים אישית באופן דינמי את רדיוס הפינות של הווידג'טים של האפליקציה:

• ‫system_app_widget_background_radius: מציין את רדיוס הפינות של קונטיינר הרקע של הווידג'ט (לעולם לא גדול מ-28dp).
• רדיוס פנימי: כדי למנוע חיתוך של התוכן, צריך לחשב רדיוס יחסי לתוכן הפנימי על סמך המתאר של הרקע במערכת: systemRadiusValue - widgetPadding

ב-Glance, אפשר להחיל מאפייני גודל של רדיוסים של פינות באופן דינמי בקומפוזיציה באמצעות GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius).

כדי לשמור על תאימות לדורות קודמים במכשירים עם Android 11 (רמת API‏ 30) ומטה, צריך להטמיע מאפיינים מותאמים אישית ומשאבי עיצוב מותאמים אישית כגיבוי:

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>