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 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 automatycznie otrzymuje aktualizacje ze Sklepu Google Play, lub urządzenia deweloperskiego zalogowanego w Sklepie Google Play.

Aby sprawdzić, jaką wersję masz zainstalowaną 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-alpha16"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha16"
    implementation "androidx.glance.wear:wear:1.0.0-alpha15"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha15"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha08"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha16"
    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-alpha16")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha16")
    implementation("androidx.glance.wear:wear:1.0.0-alpha15")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha15")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha08")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha16")
    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")
}

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 definiujesz za pomocą funkcji @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.

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

Definiowanie widżetu

Klasa widżetu zawiera 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()
        }
    }
}
GetStarted.kt

Definiowanie treści

Treść jest tworzona 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,
        )
    }
}
GetStarted.kt

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 za pomocą androidx.glance.wear:wear-tooling-preview.

Predefiniowane zestawy podglądu

Biblioteka wear-tooling-preview zawiera predefiniowane zestawy PreviewParameterProvider do testowania układów w różnych kształtach kontenerów i konfiguracjach urządzeń:

• Zestaw zaokrąglonego kwadratu (SquircleAllWidgetPreviewParams): kontenery w kształcie zaokrąglonego prostokąta.
• Zestaw okrągły (RoundAllWidgetPreviewParams): kontenery w kształcie pigułki.
• Zestaw prostokątny (RectangularAllWidgetPreviewParams): nieprzycięte kontenery prostokątne z bezpiecznym dopełnieniem. Obrazy wygenerowane za pomocą tej konfiguracji podglądu można używać jako obrazów podglądu osadzonych w 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,
    )
}
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

Generowanie komponentów z obrazem podglądu

Atrybut previewImage elementu <container> odwołuje się do komponentu rysowalnego wyświetlanego w selektorze widżetów systemu. Aby wygenerować komponenty podglądu z prawidłowymi granicami i gęstością, użyj podglądów Android Studio z RectangularAllWidgetPreviewParams (który generuje warianty podglądu zarówno dla małych, jak i dużych kontenerów) i określ gęstość wyświetlacza smartwatcha 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,
    )
}
GetStarted.kt

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

1. W Android Studio otwórz powierzchnię Projekt dla kompozycji podglądu.
2. W oknie podglądu kliknij prawym przyciskiem myszy renderowany 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łe i duże pliki obrazów w katalogu res/drawable-nodpi/ aplikacji, np. res/drawable-nodpi/widget_preview_small.png i res/drawable-nodpi/widget_preview_large.png.

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