Pierwsze kroki z widżetami

Wymagania wstępne i konfiguracja

Zanim zaczniesz, upewnij się, że Twoje środowisko spełnia te wymagania.

Wymagania dotyczące środowiska wykonawczego

Widżety Wear wymagają wersji 1.6.1 lub nowszej pliku APK com.google.android.wearable.protolayout.renderer na urządzeniu docelowym.

Zgodną wersję renderera możesz pobrać na jeden z tych sposobów:

• Emulator Wear OS 7: użyj obrazu emulatora Wear OS 7. Wersje starsze niż 7 nie są odpowiednie. Instrukcje konfiguracji znajdziesz w artykule Konfigurowanie emulatora Wear OS 7.
• Urządzenie fizyczne: użyj fizycznego urządzenia z Wear OS, które automatycznie otrzymuje aktualizacje ze Sklepu Google Play, lub urządzenia deweloperskiego zalogowanego w Sklepie Google Play.

Aby sprawdzić, która wersja jest zainstalowana na urządzeniu, użyj tego polecenia:

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

Konfiguracja Gradle

Biblioteki widżetów Wear są dostępne w Google Maven.

1. Skonfiguruj wersję pakietu SDK

Upewnij się, że compileSdk i targetSdk są ustawione na 37 lub nowszą wersję.

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

2. Dodaj zależności

Dodaj te zależności do pliku build.gradle.kts aplikacji:

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

Tworzenie widżetu Hello World

Widżet Wear składa się z usługi rozszerzającej GlanceWearWidgetService i klasy widżetu rozszerzającej GlanceWearWidget. Interfejs jest definiowany za pomocą funkcji @RemoteComposable. Funkcje @RemoteComposable.

Definiowanie usługi

Usługa jest punktem wejścia, z którym wiąże się system.

Aby zdefiniować widżet, utwórz usługę, która rozszerza GlanceWearWidgetService. Ponieważ ta biblioteka jest w trakcie aktywnego rozwoju, niektóre interfejsy API są ograniczone, a ich ostateczne nazwy i struktury są dopracowywane. Użycie adnotacji @SuppressLint("RestrictedApi") informuje kompilator, że celowo używasz tych nowych, rozwijających się funkcji. To wymaganie jest tymczasowe i zostanie usunięte, gdy interfejsy API zostaną sfinalizowane w przyszłej stabilnej wersji.

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

Definiowanie widżetu

Klasa widżetu zawiera dane i układ widżetu.

@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

Definiowanie treści

Treść jest tworzona za pomocą komponentów Remote Compose.

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

Tworzenie pliku XML konfiguracji widżetu

Utwórz nowy plik res/xml/hello_widget_info.xml, aby zdefiniować właściwości widżetu i obsługiwane rozmiary. Pełne informacje o obsługiwanych atrybutach XML w tagu <wearwidget-provider>znajdziesz w WearWidgetProviderInfo dokumentacji.

<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

Rejestracja w AndroidManifest.xml

Zarejestruj usługę w pliku AndroidManifest.xml za pomocą wymaganych filtrów intencji i metadanych.

<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

Kompilowanie i wdrażanie

Po zdefiniowaniu usługi i widżetu możesz skompilować projekt i wdrożyć go na urządzeniu lub w emulatorze.

Kompilowanie i instalowanie

Skompiluj projekt i zainstaluj debugową wersję APK na podłączonym urządzeniu lub w emulatorze:

./gradlew :app:installDebug

Dodawanie widżetu i wyświetlanie jego podglądu

Po zainstalowaniu aplikacji użyj adb, aby programowo dodać widżet do karuzeli i wyświetlić go na ekranie.

Uwaga: widżety Wear używają podstawowej infrastruktury kafelków do debugowania. W związku z tym polecenia adb wymagają operacji add-tile i show-tile.

1. Dodaj widżet do karuzeli:

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

2. Wyświetl widżet:

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

Dostępne są też podglądy w Android Studio, które pomagają testować układy na ekranach o różnych rozmiarach.