Erste Schritte mit Widgets

Hinweis: In dieser Anleitung wird davon ausgegangen, dass Sie ein neues Widget erstellen und noch keine Kachel haben. Wenn du eine App aktualisierst, die bereits eine Kachel hat, lies den Leitfaden Von Kacheln zu Widgets migrieren, um deine Dienste zu konfigurieren.

Android-Fähigkeiten

Auf GitHub ansehen

Wear OS-Widgets

Verwenden Sie einen Android-Skill, um Wear OS-Widgets mit Glance, RemoteViews und ProtoLayout zu erstellen.

Führen Sie den folgenden Befehl aus, um den Skill über die Android-Befehlszeile zu installieren:

android skills add wear-widgets

Voraussetzungen und Einrichtung

Bevor Sie beginnen, sollten Sie prüfen, ob Ihre Umgebung die folgenden Anforderungen erfüllt.

Laufzeitanforderungen

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

Sie können eine kompatible Version des Renderers auf eine der folgenden Arten abrufen:

• Wear OS 7-Emulator: Verwenden Sie das Wear OS 7-Emulator-Image. Versionen vor 7 sind nicht geeignet. Eine Anleitung zur Einrichtung findest du unter Wear OS 7-Emulator einrichten.
• Physisches Gerät: Verwende ein physisches Wear OS-Gerät, das automatische Updates aus dem Google Play Store erhält, oder ein Entwicklergerät, das im Google Play Store angemeldet ist.

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 festgelegt 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:

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“-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.

Wenn Sie Ihr Widget definieren möchten, erstellen Sie einen Dienst, der GlanceWearWidgetService erweitert, und annotieren Sie ihn mit @AssociateWithGlanceWearWidget, um den Dienst mit der entsprechenden GlanceWearWidget-Klasse zu verknüpfen.

@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

Warnung: Geben Sie den Hintergrundpinsel Ihres Widgets immer direkt an WearWidgetDocument(background = ...) weiter, damit das Hostsystem den Hintergrund in der nativen OEM-Containerform zeichnen und maskieren kann. Wenn du einen transparenten oder schwarzen Canvas festlegst und einen benutzerdefinierten abgerundeten Container im Layout zeichnest, kann dies auf einigen Geräten zu Floating-Box- und Letterboxing-Fehlern führen.

Inhalt definieren

Der Inhalt wird 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

Warnung: Achten Sie darauf, dass das Root-Container-Composable RemoteModifier.fillMaxSize() verwendet. Da die DP-Abmessungen und sicheren Abstände von Containern je nach Smartwatch-Modell variieren, kann das Hardcodieren fester Abmessungen oder äußerer Abstände zu abgeschnittenen oder falsch ausgerichteten Layouts führen.

Widget in Android Studio als Vorschau ansehen

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

Vordefinierte Vorschau-Suites

Die wear-tooling-preview-Bibliothek bietet vordefinierte PreviewParameterProvider-Suites, mit denen Sie Ihre Layouts in verschiedenen Containerformen und Gerätekonfigurationen testen können:

• Superkreis-Suite (SquircleAllWidgetPreviewParams): Abgerundete rechteckige Container.
• Round Suite (RoundAllWidgetPreviewParams): Pillenförmige Container.
• Rechteckige Suite (RectangularAllWidgetPreviewParams): Nicht zugeschnittene rechteckige Container mit sicherem Padding. Mit dieser Vorschaukonfiguration generierte Bilder eignen sich für die Verwendung als in das APK eingebettete Vorschaubilder, die von der Widget-Auswahl verwendet werden (siehe Vorschaubild-Assets generieren).

Wenn Sie sich eine Vorschau Ihres Widgets in Android Studio ansehen möchten, verwenden Sie @WearWidgetPreview:

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

Tipp: Du kannst dir auch eine Vorschau von @RemoteComposable-Layouts direkt ansehen, ohne die Widget-Klasse zu instanziieren. Übergib dazu ein Inhalts-Lambda und einen Hintergrund-Brush an WearWidgetPreview.

Widget-Konfigurations-XML 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 Dokumentation zu 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

Vorschaubild-Assets generieren

Das Attribut previewImage des Elements <container> verweist auf ein Drawable-Asset, das in der Widget-Auswahl des Systems angezeigt wird. Wenn Sie Vorschaubilder mit den richtigen Grenzen und der richtigen Dichte generieren möchten, verwenden Sie Android Studio-Vorschauen mit RectangularAllWidgetPreviewParams (wodurch Vorschauvarianten für kleine und große Container generiert werden) und geben Sie eine Smartwatch-Anzeigedichte 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 Designoberfläche für die Vorschau-Composable.
2. Klicken Sie im Vorschaufenster mit der rechten Maustaste auf die gerenderte Vorschau oder wählen Sie in der Vorschau-Symbolleiste Bild kopieren aus oder speichern Sie das Bild. Alternativ können Sie CLI-Tools oder automatisierte Skripts verwenden, um Compose-Vorschauen zu extrahieren.
3. Speichern Sie die kleine und die große Bilddatei im Verzeichnis res/drawable-nodpi/ Ihrer App, z. B. 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 das Debug-APK auf Ihrem verbundenen Gerät oder Emulator:

./gradlew :app:installDebug

Widget hinzufügen und Vorschau ansehen

Nachdem die App installiert wurde, kannst du das Widget mit adb programmatisch dem Karussell hinzufügen und auf dem Bildschirm anzeigen lassen.

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

1. 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

Hinweis: Mit dem vorherigen Befehl wird standardmäßig eine FULLSCREEN-Kachel hinzugefügt. Sie können auch die Größen LARGE und SMALL angeben, indem Sie --ei type [0|1|2] an den Befehl übergeben (wobei Typ 0 FULLSCREEN ist). Je nach Gerätestatus können von der App ausgelöste Inhaltsaktualisierungen mit triggerUpdate() für Nicht-Vollbildtypen fehlschlagen, wenn Wear Widget-Bibliotheksversionen bis 1.0.0-alpha10 verwendet werden. Dies wurde ab 1.0.0-alpha11 behoben.

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 du eine Aktualisierung für alle aktiven Instanzen deines Widgets anfordern möchtest, rufe triggerUpdateAll für deine 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.