Umiejętności związane z Androidem
Wyświetl na GitHubieWidżety na Wear OS
android skills add wear-widgetsWymagania 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:
- W Android Studio otwórz obszar Design (Projekt) dla funkcji kompozycyjnej podglądu.
- 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.
- Zapisz mały i duży plik graficzny w katalogu
res/drawable-nodpi/aplikacji, np.res/drawable-nodpi/widget_preview_small.pngires/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.