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 na Wear wymagają wersji 1.6.1 lub nowszej pakietu APK com.google.android.wearable.protolayout.renderer na urządzeniu docelowym.

Zgodną wersję mechanizmu renderowania możesz uzyskać 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 otrzymuje automatyczne aktualizacje ze Sklepu Google Play, lub urządzenia deweloperskiego zalogowanego w Sklepie Google Play.

Aby sprawdzić, jaka 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 na Wear są dostępne w Google Maven.

1. Skonfiguruj wersję pakietu SDK

Upewnij się, że parametry compileSdk i targetSdk są ustawione na 37 lub więcej.

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

2. Dodaj zależności

W pliku build.gradle.kts aplikacji uwzględnij te zależności:

Dynamiczny

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

Tworzenie widżetu Hello World

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

Zdefiniuj usługę

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

Aby zdefiniować widżet, utwórz usługę, która rozszerza GlanceWearWidgetService, i dodaj do niej adnotację @AssociateWithGlanceWearWidget, aby powiązać usługę z odpowiednią klasą GlanceWearWidget.

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

Definiowanie widżetu

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

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

Zdefiniuj treść

Treści są tworzone za pomocą komponentów Remote Compose.

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

Wyświetlanie podglądu widżetu w Android Studio

Układy widżetów możesz wyświetlać bezpośrednio w panelu Projekt w Android Studio, używając androidx.glance.wear:wear-tooling-preview.

Wstępnie zdefiniowane pakiety podglądu

Biblioteka wear-tooling-preview udostępnia gotowe pakiety PreviewParameterProvider do testowania układów w różnych kształtach kontenerów i konfiguracjach urządzeń:

  • Squircle Suite (SquircleAllWidgetPreviewParams): zaokrąglone prostokątne kontenery.
  • Round Suite (RoundAllWidgetPreviewParams): kontenery w kształcie pigułki.
  • Rectangular Suite (RectangularAllWidgetPreviewParams): nieprzycięte prostokątne kontenery z bezpiecznym dopełnieniem. Obrazy wygenerowane za pomocą tej konfiguracji podglądu nadają się do użycia jako obrazy podglądu umieszczone w pliku APK, które są używane przez selektor widżetów (patrz Generowanie komponentów z obrazem podglądu).

Aby wyświetlić podgląd widżetu w Android Studio, użyj @WearWidgetPreview:

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

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łną listę obsługiwanych atrybutów XML w tagu <wearwidget-provider> znajdziesz w dokumentacji 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>

Generowanie komponentów z obrazem do podglądu

Atrybut previewImage elementu <container> odwołuje się do zasobu rysowalnego wyświetlanego w selektorze widżetów systemowych. Aby wygenerować zasoby do podglądu o prawidłowych granicach i gęstości, użyj podglądu w Android Studio z RectangularAllWidgetPreviewParams (co spowoduje wygenerowanie wariantów podglądu zarówno dla małych, jak i dużych kontenerów) i określ gęstość wyświetlacza zegarka na 320 DPI:

@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,
    )
}

Aby wyodrębnić wyrenderowane obrazy podglądu, wykonaj te czynności:

  1. W Android Studio otwórz obszar Design (Projekt) dla funkcji kompozycyjnej podglądu.
  2. W oknie podglądu kliknij prawym przyciskiem myszy wyrenderowany podgląd lub użyj paska narzędzi podglądu, aby wybrać Kopiuj obraz lub zapisać obraz. Możesz też użyć narzędzi CLI lub automatycznych skryptów, aby wyodrębnić podglądy Compose.
  3. Zapisz mały i duży plik graficzny w katalogu res/drawable-nodpi/ aplikacji, np. res/drawable-nodpi/widget_preview_small.png i res/drawable-nodpi/widget_preview_large.png.

Rejestrowanie w pliku AndroidManifest.xml

Zarejestruj usługę w pliku AndroidManifest.xml, podając wymagane filtry intencji i metadane.

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

Tworzenie i wdrażanie

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

Tworzenie i instalowanie

Skompiluj projekt i zainstaluj pakiet APK do debugowania na połączonym urządzeniu lub emulatorze:

./gradlew :app:installDebug

Dodawanie i wyświetlanie podglądu widżetu

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

Uwaga: widżety na 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świetlanie widżetu:

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

Aktualizowanie treści widżetu automatycznie

Gdy zmienią się dane aplikacji (np. po otrzymaniu synchronizacji danych, powiadomienia push lub działania użytkownika), powiadom system, aby odświeżył zawartość widżetu.

Aby poprosić o aktualizację wszystkich aktywnych instancji widżetu, wywołaj metodę triggerUpdateAll w klasie widżetu:

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

Aby zaktualizować konkretną instancję widżetu bez odświeżania wszystkich aktywnych instancji, wywołaj triggerUpdate z identyfikatorem instancji docelowej.