Usar o Jetpack Compose no Android TV

O Compose para TV é a abordagem moderna para criar interfaces de usuário do Android TV. O Compose para TV oferece todos os benefícios do Jetpack Compose do Android para apps de TV, facilitando a criação de interfaces incríveis e funcionais para seu app.

Confira alguns benefícios específicos de usar o Compose para TV:

  • Flexibilidade: o Compose pode ser usado para criar qualquer tipo de interface, desde layouts simples a animações complexas. Os componentes funcionam imediatamente, mas também podem ser personalizados e estilizados para atender às necessidades do seu app.
  • Desenvolvimento simplificado e acelerado: o Compose é compatível com códigos existentes e permite que os desenvolvedores criem apps com mais eficiência e menos código.
  • Intuitivo: o Compose usa uma sintaxe declarativa que permite fazer mudanças na interface, depurar, entender e revisar o código.

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 também se aplicam à TV. Consulte Por que usar o Compose para mais informações sobre as vantagens gerais de um framework de UI declarativa. Para saber mais, consulte também o repositório de exemplos do Compose para TV no GitHub.

Comando de IA

Saiba como adicionar suporte ao Android TV

Essa solicitação pede orientação sobre como adicionar suporte ao Android TV ao seu app usando o Jetpack Compose para TV em vez do Leanback.

How do I add support for Android TV to my application?



Use Jetpack Compose for TV as part of the response instead of Leanback.

Usar comandos de IA

Os comandos de IA foram criados para serem usados no Gemini no Android Studio (é necessário ter a versão Canary mais recente).

Saiba mais sobre o Gemini no Studio: https://developer.android.com/studio/preview/gemini

Compatibilidade

O Compose para TV funciona em Android TVs com Android 5.0 (nível 21 da API) ou mais recente. Para usar a versão 1.0 do Compose para TV, é necessário ter a versão 1.3.0 das bibliotecas androidx.compose e o Kotlin 1.7.10.

Configurar

O uso do Jetpack Compose no Android TV é semelhante ao uso do Jetpack Compose em qualquer outro projeto Android. A principal diferença é que o Compose para TV adiciona bibliotecas que oferecem componentes otimizados para TV e facilitam a criação de interfaces do usuário personalizadas para TV. Em alguns casos, esses componentes compartilham o mesmo nome que os não relacionados à TV, como androidx.tv.material3.Button e androidx.compose.material3.Button.

Dependências do kit de ferramentas do Jetpack Compose

Para usar o Compose para TV, inclua dependências do toolkit do Jetpack Compose no arquivo build.gradle do app da seguinte maneira:

Kotlin

dependencies {
   val composeBom = platform("androidx.compose:compose-bom:2025.05.00")
   implementation(composeBom)

   // General compose dependencies.
   implementation("androidx.activity:activity-compose:1.10.1")

   implementation("androidx.compose.ui:ui-tooling-preview")
   debugImplementation("androidx.compose.ui:ui-tooling")

   // Compose for TV dependencies.
   implementation("androidx.tv:tv-material:1.0.0")
}

Groovy

dependencies {
   def composeBom = platform('androidx.compose:compose-bom:2025.05.00')
   implementation composeBom

   // General compose dependencies.
   implementation 'androidx.activity:activity-compose:1.10.1'

   implementation 'androidx.compose.ui:ui-tooling-preview'
   debugImplementation 'androidx.compose.ui:ui-tooling'

   // Compose for TV dependencies.
   implementation 'androidx.tv:tv-material:1.0.0'
}

O que vai mudar

Os componentes de material para TV são projetados para a sala de estar, com indicadores de foco claros e comportamento de entrada compatível com controle remoto. Para detalhes sobre como usar esses componentes específicos, consulte os guias de design da interface de TV.

Figura 1. Componentes de amostra da biblioteca de materiais de TV.

Use a versão para TV das APIs sempre que possível para aproveitar esses recursos.

Embora seja tecnicamente possível usar a versão para dispositivos móveis do Compose Material, ela não é otimizada para o estilo exclusivo de interações no Android TV. Além disso, misturar o Compose Material com o Compose Material do Compose para TV pode resultar em um comportamento inesperado. Por exemplo, como cada biblioteca tem o próprio objeto 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 a TV e o dispositivo móvel:

Dependência de TV
(androidx.tv.*) 		Comparação Dependência de dispositivos móveis
(androidx.compose.*)
androidx.tv:tv-material em vez de androidx.compose.material3:material3

Outros recursos

Leitura adicional

Confira estes guias para saber como criar ótimas experiências otimizadas para TV em:

Avançar
Criar um navegador de catálogo