Começar a usar widgets

Pré-requisitos e configuração

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

Requisitos do ambiente de execução

Os widgets do 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. As versões anteriores à 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 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 Maven do Google.

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:

Groovy

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

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.

Definir o serviço

O serviço é o ponto de entrada ao qual o sistema se vincula.

Para definir o widget, crie um serviço que estenda GlanceWearWidgetService e o anote com @AssociateWithGlanceWearWidget para associar o serviço à classe GlanceWearWidget adequada.

@AssociateWithGlanceWearWidget(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}

Definir o widget

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

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

Definir o conteúdo

O conteúdo é criado usando componentes do Remote Compose.

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

Visualizar o widget no Android Studio

É possível conferir os layouts de widget diretamente no painel Design do Android Studio usando androidx.glance.wear:wear-tooling-preview.

Conjuntos de pré-lançamento predefinidos

A biblioteca wear-tooling-preview oferece pacotes de PreviewParameterProvider predefinidos para testar seus layouts em diferentes formatos de contêiner e Configurador do dispositivo:

  • Squircle Suite (SquircleAllWidgetPreviewParams): contêineres de retângulo arredondado.
  • Round Suite (RoundAllWidgetPreviewParams): contêineres em formato de pílula.
  • Conjunto retangular (RectangularAllWidgetPreviewParams): contêineres retangulares não cortados com preenchimento seguro. As imagens geradas com essa configuração de prévia são adequadas para uso como as imagens de prévia incorporadas ao APK usadas pelo seletor de widgets (consulte Gerar recursos de imagem de prévia).

Para visualizar o widget no Android Studio, use @WearWidgetPreview:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}

Criar o XML de configuração do widget

Crie um novo 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 de 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>

Gerar recursos de imagem de prévia

O atributo previewImage do elemento <container> faz referência a um recurso drawable mostrado no seletor de widgets do sistema. Para gerar recursos de pré-visualização com os limites e a densidade corretos, use as prévias do Android Studio com RectangularAllWidgetPreviewParams (que gera variantes de pré-visualização para contêineres pequenos e grandes) e especifique uma densidade de tela de smartwatch de 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,
    )
}

Para extrair as imagens de pré-lançamento renderizadas, siga estas etapas:

  1. No Android Studio, abra a superfície de Design para a prévia de composição.
  2. Na janela de visualização, clique com o botão direito do mouse na visualização renderizada ou use a barra de ferramentas de visualização para selecionar Copy Image ou salvar a imagem. Como alternativa, use ferramentas da CLI ou scripts automatizados para extrair prévias do Compose.
  3. Salve os arquivos de imagem pequenos e grandes no diretório res/drawable-nodpi/ do app, como res/drawable-nodpi/widget_preview_small.png e res/drawable-nodpi/widget_preview_large.png.

Registrar no AndroidManifest.xml

Registre o serviço no AndroidManifest.xml com os filtros de intent e os 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>

Criar e implantar

Depois de definir o serviço e o widget, crie o projeto e implante-o 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 de forma programática ao carrossel e mostrá-lo na tela.

Observação:os widgets do Wear usam a infraestrutura de blocos 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

Atualizar o conteúdo do widget de forma programática

Quando os dados do app mudarem (por exemplo, ao receber uma sincronização de dados, uma notificação push ou uma ação do usuário), notifique o sistema para atualizar o conteúdo do widget.

Para solicitar uma atualização para todas as instâncias ativas do widget, chame triggerUpdateAll na classe do widget:

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

Para atualizar uma instância de widget específica sem atualizar todas as instâncias ativas, chame triggerUpdate com o ID da instância de destino.