Inizia a utilizzare i widget

Nota: questo tutorial presuppone che tu stia creando un nuovo widget e che non ne esista già uno. Se stai aggiornando un'app che ha già un widget, leggi la guida Eseguire la migrazione dai widget per configurare i tuoi servizi.

Prerequisiti e configurazione

Prima di iniziare, assicurati che il tuo ambiente soddisfi i seguenti requisiti.

Requisiti di runtime

I widget Wear richiedono la versione 1.6.1 o successive dell'APK com.google.android.wearable.protolayout.renderer sul dispositivo di destinazione.

Scarica una versione compatibile del renderer in uno dei seguenti modi:

• Emulatore Wear OS 7: utilizza l'immagine dell'emulatore Wear OS 7. Le versioni precedenti alla 7 non sono adatte. Per istruzioni per la configurazione, consulta Configurare l'emulatore Wear OS 7.
• Dispositivo fisico: utilizza un dispositivo Wear OS fisico che riceve aggiornamenti automatici dal Google Play Store o un dispositivo per sviluppatori su cui è stato eseguito l'accesso al Google Play Store.

Per controllare la versione installata sul dispositivo, utilizza il seguente comando:

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

Configurazione di Gradle

Le librerie dei widget Wear sono disponibili su Google Maven.

1. Configura la versione dell'SDK

Assicurati che compileSdk e targetSdk siano impostati su 37 o versioni successive.

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

2. Aggiungi dipendenze

Includi le seguenti dipendenze nel file build.gradle.kts dell'app:

Groovy

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

Kotlin

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

Crea un widget Hello World

Un widget Wear è costituito da un servizio che estende GlanceWearWidgetService e da una classe di widget che estende GlanceWearWidget. L'UI è definita utilizzando le funzioni @RemoteComposable. funzioni @RemoteComposable.

Definisci il servizio

Il servizio è il punto di ingresso a cui si associa il sistema.

Per definire il widget, crea un servizio che estenda GlanceWearWidgetService. Poiché questa libreria è in fase di sviluppo attivo, alcune API sono limitate mentre i nomi e le strutture finali vengono perfezionati. L'utilizzo dell' @SuppressLint("RestrictedApi") annotazione indica al compilatore che stai utilizzando intenzionalmente queste nuove funzionalità in evoluzione. Questo requisito è temporaneo e verrà rimosso una volta che le API saranno finalizzate in una futura release stabile.

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

Definisci il widget

La classe di widget fornisce i dati e il layout per il widget.

@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

Definisci i contenuti

I contenuti vengono creati utilizzando i componenti di 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

Crea il file XML di configurazione del widget

Crea un nuovo file res/xml/hello_widget_info.xml per definire le proprietà e le dimensioni supportate del widget. Per un riferimento completo degli attributi XML supportati nel tag <wearwidget-provider>, consulta la WearWidgetProviderInfo documentazione.

<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

Registra in AndroidManifest.xml

Registra il servizio in AndroidManifest.xml con i filtri di intent e i metadati richiesti.

<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

Creazione e deployment

Dopo aver definito il servizio e il widget, puoi creare il progetto ed eseguirne il deployment su un dispositivo o un emulatore.

Crea e installa

Crea il progetto e installa l'APK di debug sul dispositivo o sull'emulatore connesso:

./gradlew :app:installDebug

Aggiungi e visualizza l'anteprima del widget

Dopo aver installato l'app, utilizza adb per aggiungere il widget al carosello in modo programmatico e visualizzarlo sullo schermo.

Nota: i widget Wear utilizzano l'infrastruttura dei widget sottostante a scopo di debug. Di conseguenza, i adb comandi richiedono le add-tile e show-tile operazioni.

1. Aggiungi il widget al carosello:

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

Nota: il comando precedente aggiunge un widget a schermo intero per impostazione predefinita. Puoi anche specificare le dimensioni LARGE e SMALL passando --ei type [0|1|2] al comando (dove il tipo 0 è a schermo intero).

2. Mostra il widget:

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

Sono disponibili anche le anteprime di Android Studio per aiutarti a testare i layout su schermi di dimensioni diverse.