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

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

נקודה חשובה: התכונה 'בקצרה' מספקת גישה מודרנית לבניית ווידג'טים של אפליקציות באמצעות 'כתיבה', אבל הוא מוגבל על ידי המגבלות של AppWidgets ו-RemoteViews. לכן, ב-Glance נעשה שימוש בתוכן קומפוזבילי שונה מממשק המשתמש של Jetpack Compose.

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

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

1. צריך לרשום את ספק הווידג'ט של האפליקציה בקובץ 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

1. הרחבת המקלט AppWidget מ-GlanceAppWidgetReceiver:

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

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

בשלב הבא, מבצעים את השלב הזה כדי להוסיף את המטא-נתונים של AppWidgetProviderInfo:

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

   ההבדל היחיד בתכונה 'בקצרה' הוא שאין 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

הגדרה של GlanceAppWidget

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

   הערה: provideGlance פועל בשרשור הראשי. כדי לבצע ריצה ארוכה פעולות ב-provideGlance, מעבר לשרשור אחר באמצעות withContext. למידע נוסף, ראו שימוש בקורוטינים לבטיחות עיקרית איך מריצים מחוץ ל-thread הראשי.

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

1. ליצור אותו ב-glanceAppWidget ב-GlanceAppWidgetReceiver:

class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {

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

הגדרת עכשיו AppWidget באמצעות התכונה 'בקצרה'.

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

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

/* 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
            GlanceTheme {
                MyContent()
            }
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize()
                .background(GlanceTheme.colors.background),
            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). התצוגה הסופית תלויה במקום הזמין. התמונה הבאה היא דוגמה לאופן שבו זה עשוי להיראות:

איור 1. דוגמה לממשק משתמש.

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