Erste Schritte mit Widgets

Voraussetzungen und Einrichtung

Prüfen Sie vorab, ob Ihre Umgebung die folgenden Anforderungen erfüllt.

Laufzeitanforderungen

Für Wear-Widgets ist Version 1.6.1 oder höher des com.google.android.wearable.protolayout.renderer-APK auf dem Zielgerät erforderlich.

So erhalten Sie eine kompatible Version des Renderers:

• Wear OS 7-Emulator: Verwenden Sie das Wear OS 7-Emulator-Image. Versionen unter 7 sind nicht geeignet. Eine Anleitung zum Einrichten finden Sie unter Wear OS 7-Emulator einrichten.
• Physisches Gerät: Verwenden Sie ein physisches Wear OS-Gerät, das automatische Updates aus dem Google Play Store erhält, oder ein Entwicklergerät, auf dem Sie im Google Play Store angemeldet sind.

Mit dem folgenden Befehl können Sie prüfen, welche Version auf Ihrem Gerät installiert ist:

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

Gradle-Konfiguration

Wear-Widget-Bibliotheken sind auf Google Maven verfügbar.

1. SDK-Version konfigurieren

compileSdk und targetSdk müssen auf 37 oder höher eingestellt sein.

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

2. Abhängigkeiten hinzufügen

Fügen Sie der Datei build.gradle.kts Ihrer App die folgenden Abhängigkeiten hinzu:

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-Widget erstellen

Ein Wear-Widget besteht aus einem Dienst, der GlanceWearWidgetService erweitert, und einer Widget-Klasse, die GlanceWearWidget erweitert. Sie definieren die Benutzeroberfläche mit @RemoteComposable-Funktionen.

Dienst definieren

Der Dienst ist der Einstiegspunkt, an den das System gebunden wird.

Erstellen Sie einen Dienst, der GlanceWearWidgetService erweitert, und versehen Sie ihn mit der Annotation @AssociateWithGlanceWearWidget, um das Widget zu definieren und den Dienst der entsprechenden GlanceWearWidget-Klasse zuzuordnen.

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

Widget definieren

Die Widget-Klasse stellt die Daten und das Layout für das Widget bereit.

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

Inhalte definieren

Die Inhalte werden mit Remote Compose-Komponenten erstellt.

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

Widget in Android Studio in der Vorschau ansehen

Sie können eine Vorschau Ihrer Widget-Layouts direkt in Android Studio im Bereich Design mit androidx.glance.wear:wear-tooling-preview ansehen.

Vordefinierte Vorschau-Suites

Die wear-tooling-preview-Bibliothek bietet vordefinierte PreviewParameterProvider-Suites zum Testen Ihrer Layouts auf verschiedenen Containerformen und Gerätekonfigurationen:

• Squircle Suite (SquircleAllWidgetPreviewParams): Container in Form eines abgerundeten Rechtecks.
• Round Suite (RoundAllWidgetPreviewParams): Pillenförmige Container.
• Rechteckige Suite (RectangularAllWidgetPreviewParams): Unbeschnittene rechteckige Container mit sicherem Padding. Mit dieser Vorschaukonfiguration generierte Bilder eignen sich als APK-eingebettete Vorschaubilder, die von der Widget-Auswahl verwendet werden (siehe Vorschaubild-Assets generieren).

So können Sie eine Vorschau Ihres Widgets in Android Studio aufrufen@WearWidgetPreview:

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

XML-Datei für die Widget-Konfiguration erstellen

Erstellen Sie eine neue Datei res/xml/hello_widget_info.xml, um die Eigenschaften und unterstützten Größen des Widgets zu definieren. Eine vollständige Referenz der unterstützten XML-Attribute im <wearwidget-provider>-Tag finden Sie in der WearWidgetProviderInfo-Dokumentation.

<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

Vorschaubild-Assets generieren

Das Attribut previewImage des Elements <container> verweist auf ein Drawable-Asset, das in der System-Widget-Auswahl angezeigt wird. Wenn Sie Vorschau-Assets mit den richtigen Grenzen und der richtigen Dichte generieren möchten, verwenden Sie Android Studio Previews mit RectangularAllWidgetPreviewParams (damit werden Vorschauvarianten für kleine und große Container generiert) und geben Sie eine Smartwatch-Displaydichte von 320 DPI an:

@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

So extrahieren Sie die gerenderten Vorschaubilder:

1. Öffnen Sie in Android Studio die Design-Oberfläche für die Vorschau-Composable.
2. Klicken Sie im Vorschaufenster mit der rechten Maustaste auf die gerenderte Vorschau oder verwenden Sie die Vorschau-Symbolleiste, um Bild kopieren auszuwählen oder das Bild zu speichern. Alternativ können Sie CLI-Tools oder automatisierte Scripts verwenden, um Compose-Vorschauen zu extrahieren.
3. Speichern Sie die kleinen und großen Bilddateien im res/drawable-nodpi/-Verzeichnis Ihrer App, z. B. als res/drawable-nodpi/widget_preview_small.png und res/drawable-nodpi/widget_preview_large.png.

In AndroidManifest.xml registrieren

Registrieren Sie den Dienst in Ihrer AndroidManifest.xml mit den erforderlichen Intent-Filtern und Metadaten.

<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

Erstellen und bereitstellen

Nachdem Sie Ihren Dienst und Ihr Widget definiert haben, können Sie Ihr Projekt erstellen und auf einem Gerät oder Emulator bereitstellen.

Erstellen und installieren

Erstellen Sie das Projekt und installieren Sie die Debug-APK auf Ihrem verbundenen Gerät oder Emulator:

./gradlew :app:installDebug

Widget hinzufügen und in der Vorschau ansehen

Nachdem die App installiert wurde, können Sie das Widget mit adb programmatisch dem Karussell hinzufügen und auf dem Bildschirm anzeigen.

Hinweis:Wear-Widgets verwenden die zugrunde liegende Kachel-Infrastruktur zu Debugging-Zwecken. Daher sind für die adb-Befehle die Vorgänge add-tile und show-tile erforderlich.

1. So fügen Sie das Widget dem Karussell hinzu:

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

2. Widget anzeigen:

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

Widget-Inhalte programmatisch aktualisieren

Wenn sich die zugrunde liegenden Daten Ihrer App ändern (z. B. durch eine Datensynchronisierung, eine Push-Benachrichtigung oder eine Nutzeraktion), benachrichtigen Sie das System, damit der Widget-Inhalt aktualisiert wird.

Wenn Sie ein Update für alle aktiven Instanzen Ihres Widgets anfordern möchten, rufen Sie triggerUpdateAll in Ihrer Widget-Klasse auf:

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

Wenn Sie eine bestimmte Widget-Instanz aktualisieren möchten, ohne alle aktiven Instanzen zu aktualisieren, rufen Sie triggerUpdate mit der Zielinstanz-ID auf.