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 pliku APK com.google.android.wearable.protolayout.renderer na urządzeniu docelowym.

Uzyskaj zgodną wersję renderera w 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 na Wear OS są dostępne w Google Maven.

1. Skonfiguruj wersję pakietu SDK

Upewnij się, że wartości compileSdk i targetSdk są ustawione na 37 lub wyższe.

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

2. Dodawanie 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-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"
}

Kotlin

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

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 użytkownika definiujesz za pomocą funkcji @RemoteComposable.

Określanie 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, 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()
}

Określanie 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()
        }
    }
}

Określ treść

Treści są tworzone przy użyciu 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świetlić w panelu Projekt w Androidzie Studio, korzystając z androidx.glance.wear:wear-tooling-preview.

Wstępnie zdefiniowane zestawy podglądu

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

  • Squircle Suite (SquircleAllWidgetPreviewParams): zaokrąglone prostokątne kontenery.
  • Round Suite (RoundAllWidgetPreviewParams): pojemniki w kształcie pigułki.
  • Prostokątny pakiet (RectangularAllWidgetPreviewParams): nieprzycięte prostokątne kontenery z bezpiecznym wypełnieniem. Obrazy wygenerowane w tej konfiguracji wersji testowej 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 plików obrazów 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ć komponenty podglądu o odpowiednich granicach 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 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 powierzchnię projektu, aby wyświetlić podgląd funkcji kompozycyjnej.
  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ł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 pliku AndroidManifest.xml

Zarejestruj usługę w AndroidManifest.xml z wymaganymi filtrami intencji i metadanymi.

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

Kompilacja i wdrożenie

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

Kompilowanie i instalowanie

Utwórz projekt i zainstaluj plik APK do debugowania na podłączonym urządzeniu lub 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 na zegarek korzystają z 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

Programowe aktualizowanie treści widżetu

Gdy zmienią się dane bazowe aplikacji (np. w wyniku synchronizacji danych, powiadomienia push lub działania użytkownika), powiadom system o konieczności odświeżenia zawartości widżetu.

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

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

Aby zaktualizować konkretne wystąpienie widżetu bez odświeżania wszystkich aktywnych wystąpień, wywołaj funkcję triggerUpdate z identyfikatorem docelowego wystąpienia.