在 Android TV 上使用 Jetpack Compose

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

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

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

如果您不熟悉使用 Jetpack Compose 工具包，请查看 Compose 指南。移动版 Compose 的许多开发原则也适用于电视。有关声明式 UI 框架的一般优势的更多信息，请参阅 为什么选择 Compose。要了解更多信息，还可以查看 GitHub 上的 Compose for TV 示例存储库。

兼容性

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 添加了库，这些库提供针对电视优化的组件，并使创建针对电视的用户界面变得更加容易。在某些情况下，这些组件与它们非电视端的对应组件具有相同的名称，例如 androidx.tv.material3.Button 和 androidx.compose.material3.Button。

Jetpack Compose 工具包依赖项

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

dependencies {
   val composeBom = platform("androidx.compose:compose-bom:2024.09.00")
   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")
}

dependencies {
   def composeBom = platform('androidx.compose:compose-bom:2024.09.00')
   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'
}

有什么不同

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

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

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

下表概述了 TV 和 Mobile 之间的依赖项差异

其他资源

• TV 设计指南
  使用链接到相关开发人员资源的专用 TV 组件构建用户界面的概述。

• TV Material Catalog 示例
  一个演示如何使用 Compose for TV 实现 Material Design 原则的目录应用程序。

• JetStream 示例
  一个媒体流应用程序，演示了将 TV Compose 与典型的 Material 应用程序和现实世界架构一起使用。

• Compose for TV 入门
  此代码实验室逐步介绍了如何使用目录浏览器屏幕和详细信息屏幕构建视频播放器应用程序。

进一步阅读

探索这些指南，了解如何为以下内容构建出色的针对电视优化的体验

• 目录浏览屏幕
• 详细信息屏幕