在 Android TV 上使用 Jetpack Compose

Compose for TV 是构建 Android TV 用户界面的现代方法。Compose for TV 为您的 TV 应用解锁了 Android Jetpack Compose 的所有优势，使为您的应用构建美观且功能丰富的 UI 变得更加容易。

使用 Compose for TV 的一些具体优势包括：

灵活性：Compose 可用于创建任何类型的 UI，从简单的布局到复杂的动画。组件开箱即用，但也可以根据您的应用需求进行自定义和样式化。
简化和加速开发：Compose 与现有代码兼容，使开发者能够用更少的代码更高效地构建应用。
直观性：Compose 使用声明式语法，可让您更改 UI、调试、理解和审查代码。

如果您不熟悉 Jetpack Compose 工具包，请查看 Compose 学习路径。许多适用于移动 Compose 的开发原则也适用于 TV。如需了解有关声明式 UI 框架的总体优势的更多信息，请参阅为何采用 Compose。如需了解更多信息，另请参阅 GitHub 上的 Compose for TV 示例代码库。

AI 提示

了解如何添加对 Android TV 的支持

此提示旨在指导您如何使用 Jetpack Compose for TV 而不是 Leanback 为您的应用添加 Android TV 支持。

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

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

使用 AI 提示

AI 提示旨在用于 Android Studio 中的 Gemini（需要最新的 Canary 版本）

在此处了解有关 Studio 中 Gemini 的更多信息：https://developer.android.com/studio/preview/gemini

兼容性

Compose for TV 适用于搭载 Android 5.0 (API 级别 21) 或更高版本的 Android TV。使用 Compose for TV 1.0 版需要 androidx.compose 库的 1.3.0 版和 Kotlin 1.7.10。

设置

在 Android TV 上使用 Jetpack Compose 与在任何其他 Android 项目中使用 Jetpack Compose 类似。主要区别在于 Compose for TV 增加了库，这些库提供 TV 优化的组件，并使创建专为 TV 定制的用户界面变得更容易。在某些情况下，这些组件与非 TV 对应的组件共享相同的名称，例如 androidx.tv.material3.Button 和 androidx.compose.material3.Button。

Jetpack Compose 工具包依赖项

要使用 Compose for TV，请在应用的 build.gradle 文件中包含 Jetpack Compose 工具包依赖项，如下所示：

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

有何不同

TV Material 组件专为客厅设计，具有清晰的焦点指示器和遥控器友好型输入行为。有关如何使用这些特定组件的详细信息，请查看 TV UI 设计指南。

图 1. TV Material 库中的示例组件。

尽可能使用 API 的 TV 版本，以受益于这些功能。

虽然技术上可以使用 Compose Material 的移动版本，但它并未针对 Android TV 上独特的交互样式进行优化。此外，将 Compose Material 与 Compose for TV 中的 Compose Material 混合使用可能会导致意外行为。例如，由于每个库都有自己的 MaterialTheme 对象，如果同时使用这两个版本，颜色、排版或形状可能会不一致。

下表概述了 TV 和移动设备之间的依赖项差异：

TV 依赖项 (androidx.tv.*)	比较	移动设备依赖项 (androidx.compose.*)
androidx.tv:tv-material	*而不是*	androidx.compose.material3:material3

延伸阅读

查阅这些指南，了解如何为以下内容构建出色的 TV 优化体验：

创建目录浏览器

在 Android TV 上使用 Jetpack Compose 使用收藏整理内容 根据您的偏好保存和分类内容。