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-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"
}

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

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

Dienst definieren

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

Um Ihr Widget zu definieren, erstellen Sie einen Dienst, der GlanceWearWidgetService erweitert. Da diese Bibliothek aktiv weiterentwickelt wird, sind bestimmte APIs eingeschränkt, während ihre endgültigen Namen und Strukturen optimiert werden. Mit der Annotation @SuppressLint("RestrictedApi") teilen Sie dem Compiler mit, dass Sie diese neuen, sich entwickelnden Funktionen bewusst verwenden. Diese Anforderung ist vorübergehend und wird entfernt, sobald die APIs in einer zukünftigen stabilen Version fertiggestellt sind.

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

@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

Inhalte definieren

Die Inhalte werden mit Remote Compose-Komponenten erstellt.

@SuppressLint("RestrictedApi")
@RemoteComposable @Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World",
            color = Color.White.rc
        )
    }
}
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

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

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

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

2. Widget anzeigen:

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

Mit den Android Studio-Vorschauen können Sie Ihre Layouts auf verschiedenen Bildschirmgrößen testen.