איך מתחילים להשתמש בווידג'טים

דרישות מוקדמות והגדרה

לפני שמתחילים, צריך לוודא שהסביבה עומדת בדרישות הבאות.

דרישות זמן ריצה

כדי להשתמש בווידג'טים ל-Wear, צריך להתקין במכשיר היעד את קובץ ה-APK של com.google.android.wearable.protolayout.renderer בגרסה 1.6.1 ומעלה.

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

• אמולטור Wear OS 7: משתמשים בתמונת האמולטור של Wear OS 7. גרסאות נמוכות מ-7 לא מתאימות. הוראות להגדרה מופיעות במאמר הגדרת האמולטור של Wear OS 7.
• מכשיר פיזי: משתמשים במכשיר Wear OS פיזי שמקבל עדכונים אוטומטיים מחנות Google Play, או במכשיר למפתחים שמחובר לחנות Google Play.

כדי לבדוק איזו גרסה מותקנת במכשיר, משתמשים בפקודה הבאה:

adb shell dumpsys package com.google.android.wearable.protolayout.renderer | \
  grep -m 1 versionName | \
  awk -F= '{print $2}'

הגדרת Gradle

ספריות הווידג'טים של Wear זמינות ב-Google Maven.

1. הגדרת גרסת SDK

מוודאים שהגרסאות של compileSdk ושל targetSdk מוגדרות ל-37 ומעלה.

android {
    compileSdk = 37
    // ...
    defaultConfig {
        targetSdk = 37
        // ...
    }
}

2. הוספת יחסי תלות

מוסיפים את יחסי התלות הבאים לקובץ build.gradle.kts של האפליקציה:

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation "androidx.compose.remote:remote-creation-compose:1.0.0-alpha19"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear:1.0.0-alpha18"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha18"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha11"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19"
    implementation "androidx.wear.compose:compose-ui-tooling:1.6.2"
    implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2"
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"
}

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha19")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha19")
    implementation("androidx.glance.wear:wear:1.0.0-alpha18")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha18")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha11")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19")
    implementation("androidx.wear.compose:compose-ui-tooling:1.6.2")
    implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2")
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")
}

יצירת ווידג'ט Hello World

ווידג'ט של Wear מורכב משירות שמרחיב את GlanceWearWidgetService וממחלקת ווידג'ט שמרחיבה את GlanceWearWidget. אתם מגדירים את ממשק המשתמש באמצעות פונקציות @RemoteComposable.

הגדרת השירות

השירות הוא נקודת הכניסה שהמערכת מקשרת אליה.

כדי להגדיר את הווידג'ט, יוצרים שירות שמרחיב את GlanceWearWidgetService ומציינים אותו באמצעות @AssociateWithGlanceWearWidget כדי לשייך את השירות למחלקה המתאימה GlanceWearWidget.

@AssociateWithGlanceWearWidget(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}
GetStarted.kt

הגדרת הווידג'ט

מחלקת הווידג'ט מספקת את הנתונים ואת הפריסה של הווידג'ט.

class HelloWidget : GlanceWearWidget() {
    override suspend fun provideWidgetData(
        context: Context,
        params: WearWidgetParams,
    ): WearWidgetData {
        return WearWidgetDocument(
            background = WearWidgetBrush.color(Color.Blue.rc),
        ) {
            HelloWidgetContent()
        }
    }
}
GetStarted.kt

הגדרת התוכן

התוכן נוצר באמצעות רכיבי Remote Compose.

@RemoteComposable
@Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World".rs,
            color = Color.White.rc,
        )
    }
}
GetStarted.kt

תצוגה מקדימה של הווידג'ט ב-Android Studio

אפשר לראות תצוגה מקדימה של פריסות הווידג'טים ישירות בחלונית Design ב-Android Studio באמצעות androidx.glance.wear:wear-tooling-preview.

חבילות מוגדרות מראש של תצוגה מקדימה

ספריית wear-tooling-preview מספקת חבילות PreviewParameterProvider מוגדרות מראש לבדיקת פריסות במגוון צורות של קונטיינרים ותצורות מכשירים:

• Squircle Suite (SquircleAllWidgetPreviewParams): Rounded rectangle containers.
• Round Suite (RoundAllWidgetPreviewParams): קונטיינרים בצורת גלולה.
• חבילת מלבנים (RectangularAllWidgetPreviewParams): קונטיינרים מלבניים לא חתוכים עם שוליים בטוחים. התמונות שנוצרות באמצעות הגדרת התצוגה המקדימה הזו מתאימות לשימוש כתמונות תצוגה מקדימה שמוטמעות ב-APK ומשמשות את כלי בחירת הווידג'טים (ראו יצירת נכסי תמונות לתצוגה מקדימה).

כדי לראות תצוגה מקדימה של הווידג'ט ב-Android Studio, משתמשים ב-@WearWidgetPreview:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

יצירת קובץ ה-XML של הגדרות הווידג'ט

יוצרים קובץ חדש res/xml/hello_widget_info.xml כדי להגדיר את המאפיינים של הווידג'ט ואת הגדלים הנתמכים. רשימה מלאה של מאפייני ה-XML הנתמכים בתג <wearwidget-provider> זמינה במאמרי העזרה בנושא WearWidgetProviderInfo.

<wearwidget-provider
    description="@string/hello_widget_description"
    icon="@mipmap/ic_launcher"
    label="@string/hello_widget_label"
    preferredType="SMALL">

    <container
        type="SMALL"
        previewImage="@drawable/widget_preview_small" />
    <container
        type="LARGE"
        previewImage="@drawable/widget_preview_large" />
</wearwidget-provider>
hello_widget_info.xml

יצירת נכסי תמונות לתצוגה מקדימה

המאפיין previewImage של האלמנט <container> מפנה לנכס drawable שמוצג בכלי לבחירת ווידג'טים במערכת. כדי ליצור נכסי תצוגה מקדימה עם הגבולות והצפיפות הנכונים, משתמשים בתצוגות מקדימות של Android Studio עם RectangularAllWidgetPreviewParams (שיוצרת וריאציות של תצוגה מקדימה גם עבור מאגרי נתונים קטנים וגם עבור מאגרי נתונים גדולים) ומציינים צפיפות של 320 DPI לתצוגה של שעון חכם:

@Preview(
    name = "Widget Preview Asset",
    device = "spec:width=1000dp,height=1000dp,dpi=320",
)
@Composable
fun HelloWidgetCatalogPreview(
    @PreviewParameter(RectangularAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

כדי לחלץ את תמונות התצוגה המקדימה שעברו רינדור:

1. ב-Android Studio, פותחים את האזור Design (עיצוב) כדי לראות את התצוגה המקדימה של פונקציית ה-Composable.
2. בחלון התצוגה המקדימה, לוחצים לחיצה ימנית על התצוגה המקדימה שעברה רינדור או משתמשים בסרגל הכלים של התצוגה המקדימה כדי לבחור באפשרות העתקת תמונה או לשמור את התמונה. אפשר גם להשתמש בכלים של CLI או בסקריפטים אוטומטיים כדי לחלץ תצוגות מקדימות של Compose.
3. שומרים את קובצי התמונות הקטנים והגדולים בספרייה res/drawable-nodpi/ של האפליקציה, כמו res/drawable-nodpi/widget_preview_small.png ו-res/drawable-nodpi/widget_preview_large.png.

הרשמה בקובץ AndroidManifest.xml

רושמים את השירות ב-AndroidManifest.xml עם מסנני הכוונות והמטא-נתונים הנדרשים.

<service
    android:name=".snippets.widget.HelloWidgetService"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/hello_widget_label"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">

    <intent-filter>
        <action android:name="androidx.glance.wear.action.BIND_WIDGET_PROVIDER" />
        <!-- If you already have a Tile, omit the following line. -->
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data
        android:name="androidx.glance.wear.widget.provider"
        android:resource="@xml/hello_widget_info" />

    <meta-data
        android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

בנייה ופריסה

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

יצירה והתקנה

מבצעים Build לפרויקט ומתקינים את ה-APK של הניפוי באגים במכשיר המחובר או באמולטור:

./gradlew :app:installDebug

הוספה של הווידג'ט ותצוגה מקדימה שלו

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

הערה: ווידג'טים של Wear משתמשים בתשתית הבסיסית של הריבועים למטרות ניפוי באגים. לכן, הפקודות של adb דורשות את הפעולות add-tile ו-show-tile.

1. מוסיפים את הווידג'ט לקרוסלה:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component <your_package_name>/.HelloWidgetService

2. הצגת הווידג'ט:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SYSUI \
  --es operation show-tile \
  --ei index 0

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

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

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

// Request a content update for all active HelloWidget instances
HelloWidget().triggerUpdateAll(context)

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