Erste Schritte mit Widgets

Voraussetzungen und Einrichtung

Bevor Sie beginnen, müssen Sie sicherstellen, dass Ihre Umgebung die folgenden Anforderungen erfüllt.

Laufzeitanforderungen

Für Wear-Widgets ist auf dem Zielgerät Version 1.6.1 oder höher des APK com.google.android.wearable.protolayout.renderer 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

Achten Sie darauf, dass compileSdk und targetSdk auf 37 oder höher festgelegt sind.

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 und einer Widget-Klasse erweitert GlanceWearWidget. Sie definieren die Benutzeroberfläche mit @RemoteComposable-Funktionen.

Dienst definieren

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

Erstellen Sie einen Dienst, der GlanceWearWidgetService erweitert, um Ihr Widget zu definieren.

@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 sich Ihre Widget-Layouts direkt im Bereich Design von Android Studio mit androidx.glance.wear:wear-tooling-preview ansehen.

Vordefinierte Vorschau-Suites

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

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

Verwenden Sie @WearWidgetPreview, um sich eine Vorschau Ihres Widgets in Android Studio anzusehen:

@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 Tag <wearwidget-provider> 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 Widget-Auswahl des Systems angezeigt wird. Verwenden Sie Android Studio-Vorschauen mit RectangularAllWidgetPreviewParams, um Vorschaubilder mit den richtigen Begrenzungen und der richtigen Dichte zu generieren. Dadurch werden Vorschauvarianten für kleine und große Container generiert. Geben Sie außerdem 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 Design-Oberfläche für die zusammensetzbare Vorschau.
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 die CLI-Tools oder automatisierte Skripts verwenden, um Compose-Vorschauen zu extrahieren.
3. Speichern Sie die kleinen und großen Bilddateien im res/drawable-nodpi/ Verzeichnis 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-Datei 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 in der Vorschau ansehen

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

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

1. Widget dem Karussell hinzufügen :

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