Usar o Jetpack Compose no Wear OS

O Compose para Wear OS é semelhante ao Compose para dispositivos móveis. No entanto, existem algumas diferenças importantes. Este guia explica as semelhanças e diferenças.

O Compose para Wear OS faz parte do Android Jetpack e, assim como as outras bibliotecas Wear Jetpack usadas, ele ajuda a programar códigos melhores com mais rapidez. O Compose é nossa abordagem recomendada para criar interfaces do usuário para apps Wear OS.

Se você não sabe usar o kit de ferramentas do Jetpack Compose, confira o Programa de treinamentos do Compose. Muitos dos princípios de desenvolvimento do Compose para dispositivos móveis se aplicam ao Compose para Wear OS. Consulte Por que usar o Compose para ter mais informações sobre as vantagens gerais de usar um framework de UI declarativa. Para saber mais sobre o Compose para Wear OS, consulte o Programa de treinamentos do Compose para Wear OS e o Repositório de exemplos do Wear OS (link em inglês) no GitHub.

Observação: o Compose para Wear OS está disponível em uma versão estável (link em inglês) e é a abordagem recomendada para criar interfaces do usuário para Wear OS.

Material Design no Jetpack Compose no Wear OS

O Jetpack Compose no Wear OS oferece uma implementação do Material 2.5, que ajuda a criar experiências de app mais envolventes. Os componentes do Material Design no Wear OS são criados com base nos Temas do Material Design para Wear. Essa aplicação de temas é uma maneira sistemática de personalizar o Material Design e refletir melhor a marca do seu produto.

Compatibilidade

O Compose para Wear OS funciona em smartwatches com suporte ao Wear OS 3.0 (nível 30 da API) e que usam o 2.0 (nível 25 da API e versões mais recentes). Para usar a versão 1.4 do Compose para Wear OS, é necessário utilizar a versão 1.7 das bibliotecas androidx.compose e o Kotlin 1.9.0. É possível usar o mapeamento de BOM e o mapa de compatibilidade do Compose com o Kotlin para verificar a compatibilidade do Compose.

Plataformas

Com o Compose para Wear OS, fica mais fácil criar apps no Wear OS. Para mais informações, consulte Apps. Use nossos componentes integrados para criar experiências do usuário que obedecem às diretrizes do Wear OS. Para mais informações sobre componentes, consulte nossas orientações de design.

Como configurar

O uso do Jetpack Compose com o Wear OS é semelhante ao uso do Jetpack Compose para qualquer outro projeto Android. A principal diferença é que o Jetpack Compose para Wear adiciona bibliotecas específicas do Wear que facilitam a criação de interfaces do usuário personalizadas para smartwatches. Em alguns casos, esses componentes compartilham o mesmo nome que os não relacionados ao Wear, como androidx.wear.compose.material.Button e androidx.compose.material.Button.

Criar um novo app no Android Studio

Para criar um novo projeto que inclua o Jetpack Compose, faça o seguinte:

1. Se estiver na janela Welcome to Android Studio, clique em Start a new Android Studio project. Caso você já tenha um projeto aberto no Android Studio, selecione File > New > Import Sample na barra de menus.
2. Pesquise Compose for Wear e selecione Compose for Wear OS Starter.
3. Na janela Configure your project, faça o seguinte:
   1. Defina o Application name (o nome do app).
   2. Escolha a Project location (a localização do projeto) para o exemplo.
4. Clique em Finish.
5. Verifique se o arquivo build.gradle do projeto está configurado corretamente, conforme descrito em Arquivos de propriedade do Gradle.

Agora está tudo pronto para você começar a desenvolver um app usando o Compose para Wear OS.

Dependências do kit de ferramentas do Jetpack Compose

Para usar o Jetpack Compose com o Wear OS, é necessário incluir dependências do kit de ferramentas do Jetpack Compose no arquivo build.gradle do app. A maioria das mudanças de dependência relacionadas ao Wear OS estão nas camadas de arquitetura principais, cercadas por uma caixa vermelha na imagem a seguir.

<img 'foundation',="" 'material',="" 'runtime'.="" 'ui',="" 2="" 4="" a="" alt="" and="" are="" bottom,="" box""="" by="" contain="" from="" rectangles="" rectangles.="" red="" src="/static/wear/images/components/ComposeDependencies.png" surrounded="" the="" to="" top="" />

Isso significa que muitas das dependências que você já usa com o Jetpack Compose não mudam ao criar um app para Wear OS. Por exemplo, as dependências de interface, ambiente de execução, compilador e animação permanecem as mesmas.

No entanto, o Wear OS tem as próprias versões das bibliotecas material, foundation e navigation. Verifique se você está usando as bibliotecas corretas.

Use a versão WearComposeMaterial das APIs sempre que possível. Embora seja tecnicamente possível usar a versão para dispositivos móveis do Compose Material, ela não é otimizada para os requisitos exclusivos do Wear OS. Além disso, misturar o Compose Material com o Compose Material para Wear OS pode resultar em um comportamento inesperado. Por exemplo, como cada biblioteca tem a própria classe MaterialTheme, é possível que cores, tipografias ou formas sejam inconsistentes se as duas versões forem usadas.

A tabela abaixo descreve as diferenças de dependência entre o Wear OS e o dispositivo móvel:

Dependência do Wear OS (androidx.wear.*)	Comparação	Dependência de dispositivos móveis (androidx.*)
androidx.wear.compose:compose-material	em vez de	androidx.compose.material:material
androidx.wear.compose:compose-navigation	em vez de	androidx.navigation:navigation-compose
androidx.wear.compose:compose-foundation	além de	androidx.compose.foundation:foundation

Observação: outras dependências de materiais não móveis podem ser usadas, como ondulação e ícones estendidos do Material Design.

O snippet a seguir mostra um exemplo de arquivo build.gradle que inclui essas dependências:

Kotlin

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2024.10.01")

    // General compose dependencies
    implementation(composeBom)
    implementation("androidx.activity:activity-compose:1.9.3")
    implementation("androidx.compose.ui:ui-tooling-preview:1.7.5")
    // Other compose dependencies

    // Compose for Wear OS Dependencies
    implementation("androidx.wear.compose:compose-material:1.4.0")

    // Foundation is additive, so you can use the mobile version in your Wear OS app.
    implementation("androidx.wear.compose:compose-foundation:1.4.0")

    // Wear OS preview annotations
    implementation("androidx.wear.compose:compose-ui-tooling:1.4.0")

    // If you are using Compose Navigation, use the Wear OS version (NOT THE MOBILE VERSION).
    // Uncomment the line below and update the version number.
    // implementation("androidx.wear.compose:compose-navigation:1.4.0")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.3")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
    androidTestImplementation("androidx.compose.ui:ui-test-junit4:1.0.3")
    debugImplementation("androidx.compose.ui:ui-tooling:1.0.3")
}

Feedback

Teste o Compose para Wear OS e use o Issue Tracker para dar sugestões e feedback.

Participe do canal #compose-wear (link em inglês) no Kotlin Slack para se conectar à comunidade de desenvolvedores e compartilhar sua experiência.