Cómo usar Jetpack Compose en Android TV

Compose para TV es el enfoque moderno para compilar interfaces de usuario de Android TV. Compose para TV desbloquea todos los beneficios de Jetpack Compose de Android para tus apps para TV, lo que facilita mucho la compilación de IU atractivas y funcionales para tu app.

Estos son algunos de los beneficios específicos de usar Compose para TV:

  • Flexibilidad: Compose se puede usar para crear cualquier tipo de IU, desde diseños simples hasta animaciones complejas. Los componentes funcionan de inmediato, pero también se pueden personalizar y adaptar a las necesidades de tu app.
  • Desarrollo simplificado y acelerado: Compose es compatible con el código existente y permite que los desarrolladores compilen apps de forma más eficiente con menos código.
  • Intuitivo: Compose usa una sintaxis declarativa que te permite realizar cambios en tu IU, depurar, comprender y revisar tu código.

Si nunca usaste el kit de herramientas de Jetpack Compose, consulta la ruta de aprendizaje de Compose. Muchos de los principios de desarrollo de Compose para dispositivos móviles también se aplican a las TVs. Consulta Por qué Compose para obtener más información sobre las ventajas generales de un framework de IU declarativo. Para obtener más información, consulta también el repositorio de muestras de Compose para TV en GitHub.

Instrucción de IA

Obtén información para agregar compatibilidad con Android TV

Esta instrucción solicita orientación para agregar compatibilidad con Android TV a tu app con Jetpack Compose para TV en lugar de 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.

Cómo usar instrucciones de IA

Las instrucciones basadas en IA están diseñadas para usarse en Gemini en Android Studio (se requiere la versión Canary más reciente).

Obtén más información sobre Gemini en Studio aquí: https://developer.android.com/studio/preview/gemini

Compatibilidad

Compose para TV funciona en Android TVs con Android 5.0 (nivel de API 21) o versiones posteriores. El uso de la versión 1.0 de Compose para TV requiere la versión 1.3.0 de las bibliotecas androidx.compose y Kotlin 1.7.10.

Configuración

Usar Jetpack Compose en Android TV es similar a usar Jetpack Compose para cualquier otro proyecto de Android. La diferencia principal es que Compose para TV agrega bibliotecas que ofrecen componentes optimizados para TV y facilitan la creación de interfaces de usuario personalizadas para TV. En algunos casos, esos componentes comparten el mismo nombre que aquellos que no son para TVs, como androidx.tv.material3.Button y androidx.compose.material3.Button.

Dependencias del kit de herramientas de Jetpack Compose

Para usar Compose para TV, incluye las dependencias del kit de herramientas de Jetpack Compose en el archivo build.gradle de tu app de la siguiente manera:

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'
}

Qué cambió

Los componentes de Material para TV están diseñados para la sala de estar, con indicadores de enfoque claros y un comportamiento de entrada compatible con el control remoto. Para obtener detalles sobre cómo usar estos componentes específicos, consulta las guías de diseño de la IU para TVs.

Figura 1: Componentes de ejemplo de la biblioteca de material para TV.

Usa la versión para TVs de las APIs siempre que sea posible para aprovechar estas funciones.

Si bien es técnicamente posible usar la versión de Compose Material para dispositivos móviles, no está optimizada para el estilo único de interacciones en Android TV. Además, combinar Compose Material con Compose Material de Compose para TV puede generar un comportamiento inesperado. Por ejemplo, como cada biblioteca tiene su propio objeto MaterialTheme, existe la posibilidad de que los colores, la tipografía o las formas sean inconsistentes si se usan ambas versiones.

En la siguiente tabla, se describen las diferencias de dependencia entre la versión para TVs y para dispositivos móviles:

Dependencia de TV
(androidx.tv.*) 		Comparación Dependencia de dispositivos móviles
(androidx.compose.*)
androidx.tv:tv-material en lugar de androidx.compose.material3:material3

Recursos adicionales

  • Guías de diseño para TVs
    Una descripción general de los componentes dedicados para TVs para crear interfaces de usuario con vínculos a recursos relevantes para desarrolladores

  • Ejemplo del catálogo de Material para TVs
    Una app de catálogo que muestra cómo implementar los principios de Material Design con Compose para TVs.

  • Ejemplo de JetStream
    Una app de transmisión de contenido multimedia que demuestra el uso de TV Compose con una app de Material típica y una arquitectura del mundo real.

  • Introducción a Compose para TV
    En este codelab, se explica cómo compilar una app de reproductor de video con una pantalla de navegador de catálogo y una pantalla de detalles.

Lecturas adicionales

Explora estas guías para obtener información sobre cómo crear experiencias optimizadas para la TV:

Siguiente
Cómo crear un navegador de catálogos