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

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

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

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

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

כדי להשתמש בווידג'טים ל-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 של האפליקציה:

Groovy

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

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

Kotlin

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

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha010")
    implementation("androidx.wear.compose:compose-ui-tooling:1.6.1")
    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. הספרייה הזו נמצאת בפיתוח, לכן יש הגבלות על ממשקי API מסוימים בזמן שאנחנו משפרים את השמות והמבנים הסופיים שלהם. השימוש בהערה @SuppressLint("RestrictedApi") מאפשר לקומפיילר לדעת שאתם משתמשים בתכונות החדשות האלה, שנמצאות בפיתוח, באופן מכוון. הדרישה הזו היא זמנית ותוסר אחרי שממשקי ה-API יסיימו את שלב הפיתוח בגרסה יציבה עתידית.

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

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

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

@SuppressLint("RestrictedApi")
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.

@SuppressLint("RestrictedApi")
@RemoteComposable @Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World",
            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 משתמשים בתשתית הבסיסית של הריבועים למטרות ניפוי באגים. לכן, הפקודות 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

הערה: הפקודה הקודמת מוסיפה כברירת מחדל משבצת במסך מלא. אפשר גם לציין גדלים LARGE ו-SMALL על ידי העברת --ei type [0|1|2] לפקודה (כאשר סוג 0 הוא FULLSCREEN).

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

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

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