Começar a usar widgets

Pré-requisitos e configuração

Antes de começar, verifique se o ambiente atende aos seguintes requisitos.

Requisitos de execução

Os widgets para Wear exigem a versão 1.6.1 ou mais recente do APK com.google.android.wearable.protolayout.renderer no dispositivo de destino.

Consiga uma versão compatível do renderizador de uma das seguintes maneiras:

• Emulador do Wear OS 7: use a imagem do emulador do Wear OS 7. Versões inferiores a 7 não são adequadas. Para instruções de configuração, consulte Configurar o emulador do Wear OS 7.
• Dispositivo físico: use um dispositivo Wear OS físico que receba atualizações automáticas da Google Play Store ou um dispositivo de desenvolvedor conectado à Google Play Store.

Para verificar qual versão está instalada no seu dispositivo, use o seguinte comando:

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

Configuração do Gradle

As bibliotecas de widgets do Wear estão disponíveis no Google Maven.

1. Configurar a versão do SDK

Verifique se compileSdk e targetSdk estão definidos como 37 ou mais recente.

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

2. Adicionar dependências

Inclua as seguintes dependências no arquivo build.gradle.kts do app:

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

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

Criar um widget Hello World

Um widget do Wear consiste em um serviço que estende GlanceWearWidgetService e uma classe de widget que estende GlanceWearWidget. A interface é definida usando funções @RemoteComposable. Funções @RemoteComposable.

Definir o serviço

O serviço é o ponto de entrada a que o sistema se vincula.

Para definir o widget, crie um serviço que estenda GlanceWearWidgetService. Como essa biblioteca está em desenvolvimento ativo, algumas APIs são restritas enquanto os nomes e as estruturas finais são refinados. Usar a anotação @SuppressLint("RestrictedApi") informa ao compilador que você está usando intencionalmente esses recursos novos e em evolução. Esse requisito é temporário e será removido quando as APIs forem finalizadas em uma versão estável futura.

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

Definir o widget

A classe do widget fornece os dados e o layout dele.

@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

Definir o conteúdo

O conteúdo é criado usando componentes do 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

Criar o XML de configuração do widget

Crie um arquivo res/xml/hello_widget_info.xml para definir as propriedades e os tamanhos compatíveis do widget. Para uma referência completa dos atributos XML compatíveis na tag <wearwidget-provider>, consulte a documentação do 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>
hello_widget_info.xml

Registrar no AndroidManifest.xml

Registre o serviço no seu AndroidManifest.xml com os filtros de intent e metadados necessários.

<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

Criar e implantar

Depois de definir o serviço e o widget, é possível criar e implantar o projeto em um dispositivo ou emulador.

Criar e instalar

Crie o projeto e instale o APK de depuração no dispositivo conectado ou emulador:

./gradlew :app:installDebug

Adicionar e visualizar o widget

Depois que o app for instalado, use adb para adicionar o widget ao carrossel e mostrá-lo na tela de forma programática.

Observação:os widgets do Wear usam a infraestrutura de blocos subjacente para fins de depuração. Como resultado, os comandos adb exigem as operações add-tile e show-tile.

1. Adicione o widget ao carrossel:

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

2. Mostrar o widget:

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

As prévias do Android Studio também estão disponíveis para ajudar você a testar seus layouts em diferentes tamanhos de tela.