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

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

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

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

כדי להשתמש ב-Wear Widgets, צריך להתקין במכשיר היעד את קובץ ה-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-alpha11"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha11"
    implementation "androidx.glance.wear:wear:1.0.0-alpha10"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha10"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha04"

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

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

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

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

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

הגדרת השירות

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

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

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

יצירת קובץ ה-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

הרשמה בקובץ 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 Widgets משתמשים בתשתית הבסיסית של ה-Tile למטרות ניפוי באגים. כתוצאה מכך, הפקודות 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

יש גם תצוגות מקדימות ב-Android Studio שיעזרו לכם לבדוק את הפריסות במסכים בגדלים שונים.