Usar o Jetpack Compose no Android TV

O Compose para TV é a abordagem moderna para criar interfaces do 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 do uso do 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 já existentes e permite que os desenvolvedores criem apps com mais eficiência com 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 usar um framework de IU declarativa. Para saber mais, consulte o repositório de exemplos do Compose para TV no GitHub.

Compatibilidade

O Compose para TV funciona em TVs Android com o 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 para 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 as dependências do kit de ferramentas do Jetpack Compose no arquivo build.gradle do app da seguinte maneira:

Kotlin

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

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

   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:2024.10.01')
   implementation composeBom

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

   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 há de diferente

Os componentes do Material Design para TV são projetados para a sala de estar, com indicadores de foco claros e comportamento de entrada amigável ao controle remoto. Para saber como usar esses componentes específicos, consulte os guias de design da interface de TV.

Figura 1. Exemplos de componentes da biblioteca de materiais para 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 está 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 a seguir 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 inglês) em vez de androidx.compose.material3:material3

Outros recursos

Leia mais

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

Próxima
Criar um navegador de catálogo