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

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

מיומנויות ב-Android

הצגת הקוד ב-GitHub

ווידג'טים של Wear OS

אתם יכולים להשתמש במיומנות Android כדי ליצור ווידג'טים ל-Wear OS באמצעות Glance,‏ RemoteViews ו-ProtoLayout.

כדי להתקין את המיומנות מ-Android CLI, מריצים את הפקודה:

android skills add wear-widgets

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

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

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

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

כדי לקבל גרסה תואמת של הכלי לעיבוד, אפשר לבחור באחת מהאפשרויות הבאות:

• אמולטור 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-alpha21"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha21"
    implementation "androidx.glance.wear:wear:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha20"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha13"

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

Kotlin

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

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

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

ווידג'ט ל-Wear OS מורכב משירות שמרחיב את 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

אזהרה: תמיד צריך לספק את מברשת הרקע של הווידג'ט ישירות ל-WearWidgetDocument(background = ...) כדי שהמערכת המארחת תוכל לצבוע את הרקע ולהוסיף לו מסכה לצורת מאגר ה-OEM המקורי. אם מגדירים אזור ציור שקוף או שחור ומציירים קונטיינר מעוגל בהתאמה אישית בתוך הפריסה, זה עלול לגרום לפגמים של תיבה צפה ופסים שחורים במכשירים מסוימים.

הגדרת התוכן

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

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

אזהרה: חשוב לוודא שהקוד הקומפזבילי של מאגר הבסיס (root) משתמש ב-RemoteModifier.fillMaxSize(). מכיוון שמידות ה-DP של מאגר התגים וההוספות הבטוחות משתנות בין דגמי השעונים, קידוד קשיח של מידות קבועות או ריפוד חיצוני עלול לגרום לחיתוך או לפריסות לא מיושרות.

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

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

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

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

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

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

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

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

יצירת קובץ 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> מפנה לנכס שניתן להצגה, שמופיע בכלי לבחירת ווידג'טים של המערכת. כדי ליצור תצוגה מקדימה של הנכס הדיגיטלי עם הגבולות והצפיפות הנכונים, משתמשים בתצוגות המקדימות של 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 (עיצוב) של הפונקציה הקומפוזבילית לתצוגה מקדימה.
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 עם מסנני ה-Intent והמטא-נתונים הנדרשים.

<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

פיתוח ופריסה

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

בנייה והתקנה

מפתחים את הפרויקט ומתקינים את ה-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

הערה: הפקודה הקודמת מוסיפה משבצת FULLSCREEN כברירת מחדל. אפשר גם לציין גדלים מסוג LARGE ו-SMALL על ידי העברת --ei type [0|1|2] לפקודה (כאשר סוג 0 הוא FULLSCREEN). בהתאם למצב המכשיר, עדכוני תוכן שמופעלים על ידי האפליקציה באמצעות triggerUpdate() עלולים להיכשל בסוגים שאינם במסך מלא כשמשתמשים בגרסאות של ספריית הווידג'טים של Wear עד 1.0.0-alpha10 (הבעיה הזו תוקנה החל מגרסה 1.0.0-alpha11).

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 עם מזהה המופע הרצוי.