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 do Wear exigem a versão 1.6.1 ou mais recente do APK com.google.android.wearable.protolayout.renderer no dispositivo de destino.

Receba 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 Google Maven.

1. Configurar a versão do SDK

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

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-alpha19"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear:1.0.0-alpha18"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha18"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha11"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19"
    implementation "androidx.wear.compose:compose-ui-tooling:1.6.2"
    implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2"
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"
}

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha19")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha19")
    implementation("androidx.glance.wear:wear:1.0.0-alpha18")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha18")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha11")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19")
    implementation("androidx.wear.compose:compose-ui-tooling:1.6.2")
    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. Você define a interface 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.

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

Definir o widget

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

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.

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

Visualizar o widget no Android Studio

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

Suítes de visualização predefinidas

A biblioteca wear-tooling-preview fornece suítes PreviewParameterProvider predefinidas para testar seus layouts em diferentes formas de contêiner e configurações de dispositivo:

• Suíte quadrada arredondada (SquircleAllWidgetPreviewParams) : contêineres retangulares arredondados.
• Suíte redonda (RoundAllWidgetPreviewParams) : contêineres em formato de pílula.
• Suíte retangular (RectangularAllWidgetPreviewParams) : contêineres retangulares não cortados com preenchimento seguro. As imagens geradas com essa configuração de visualização são adequadas para uso como imagens de visualização incorporadas ao APK usadas pelo seletor de widgets. Consulte Gerar recursos de imagem de visualização.

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

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

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 WearWidgetProviderInfo documentação.

<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

Gerar recursos de imagem de visualização

O atributo previewImage do elemento <container> faz referência a um recurso drawable mostrado no seletor de widgets do sistema. Para gerar recursos de visualização com os limites e a densidade corretos, use as visualizações do Android Studio com RectangularAllWidgetPreviewParams (que gera variantes de 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,
    )
}
GetStarted.kt

Para extrair as imagens de visualização renderizadas, siga estas etapas:

1. No Android Studio, abra a superfície Design para o combinável de visualizaçã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 Copiar imagem ou salvar a imagem. Como alternativa, use ferramentas de CLI ou scripts automatizados para extrair visualizações do Compose.
3. Salve os arquivos de imagem pequenos e grandes no res/drawable-nodpi/ diretório 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 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, você pode criar o projeto e implantá-lo 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 de maneira programática e mostrá-lo na tela.

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

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