Premiers pas avec les widgets

Prérequis et préparation

Avant de commencer, assurez-vous que votre environnement répond aux exigences suivantes.

Exigences d'exécution

Les widgets Wear nécessitent la version 1.6.1 ou ultérieure de l'APK com.google.android.wearable.protolayout.renderer sur l'appareil cible.

Obtenez une version compatible du moteur de rendu de l'une des manières suivantes :

  • Émulateur Wear OS 7 : utilisez l'image de l'émulateur Wear OS 7. Les versions inférieures à 7 ne conviennent pas. Pour obtenir des instructions de configuration, consultez Configurer l'émulateur Wear OS 7.
  • Appareil physique : utilisez un appareil Wear OS physique qui reçoit des mises à jour automatiques du Google Play Store ou un appareil de développement connecté au Google Play Store.

Pour vérifier la version installée sur votre appareil, utilisez la commande suivante :

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

Configuration de Gradle

Les bibliothèques de widgets Wear sont disponibles sur Google Maven.

1. Configurer la version du SDK

Assurez-vous que compileSdk et targetSdk sont définis sur 37 ou une version ultérieure.

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

2. Ajouter des dépendances

Incluez les dépendances suivantes dans le fichier build.gradle.kts de votre application :

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

Créer un widget Hello World

Un widget Wear se compose d'un service étendant GlanceWearWidgetService et d'une classe de widget étendant GlanceWearWidget. L'interface utilisateur est définie à l'aide de fonctions @RemoteComposable. Fonctions @RemoteComposable.

Définir le service

Le service est le point d'entrée auquel le système se lie.

Pour définir votre widget, créez un service qui étend GlanceWearWidgetService. Comme cette bibliothèque est en cours de développement, certaines API sont limitées pendant que leurs noms et structures finaux sont en cours de finalisation. L'annotation @SuppressLint("RestrictedApi") indique à votre compilateur que vous utilisez intentionnellement ces nouvelles fonctionnalités en cours d'évolution. Cette exigence est temporaire et sera supprimée une fois les API finalisées dans une future version stable.

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

Définir le widget

La classe de widget fournit les données et la mise en page du widget.

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

Définir le contenu

Le contenu est créé à l'aide de composants Remote Compose.

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

Créer le fichier XML de configuration du widget

Créez un fichier res/xml/hello_widget_info.xml pour définir les propriétés et les tailles compatibles du widget. Pour obtenir une référence complète des attributs XML compatibles dans le tag <wearwidget-provider>, consultez la WearWidgetProviderInfo documentation.

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

S'inscrire dans AndroidManifest.xml

Enregistrez le service dans votre fichier AndroidManifest.xml avec les filtres d'intent et les métadonnées requis.

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

Compiler et déployer

Après avoir défini votre service et votre widget, vous pouvez compiler votre projet et le déployer sur un appareil ou un émulateur.

Compiler et installer

Compilez le projet et installez l'APK de débogage sur votre appareil connecté ou votre émulateur :

./gradlew :app:installDebug

Ajouter un aperçu de votre widget

Une fois l'application installée, utilisez adb pour ajouter le widget au carrousel par programmation et l'afficher à l'écran.

Remarque : Les widgets Wear utilisent l'infrastructure de vignette sous-jacente à des fins de débogage. Par conséquent, les adb commandes nécessitent les add-tile et show-tile opérations.

1. Ajoutez le widget au carrousel :

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

2. Affichez le widget :

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

Des aperçus Android Studio sont également disponibles pour vous aider à tester vos mises en page sur différentes tailles d'écran.