在 Android TV 上使用 Jetpack Compose

Compose for TV 是构建 Android TV 界面的新方法。Compose for TV 融合了适用于 TV 应用的 Android Jetpack Compose 的所有优势，可让您更轻松地为应用构建功能强大且美观出众的界面。

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

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

如果您不熟悉如何使用 Jetpack Compose 工具包，请查看 Compose 开发者在线课程。Compose 移动设备的许多开发原则也适用于 TV。如需详细了解声明式界面框架的一般优势，请参阅为什么采用 Compose。如需了解详情，还请参阅 GitHub 上的 Compose for TV 示例代码库。

兼容性

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

设置

在 Android TV 上使用 Jetpack Compose 与将 Jetpack Compose 用于任何其他 Android 项目相似。主要区别在于，Compose for TV 添加了一些库，这些库提供针对 TV 进行了优化的组件，可让您更轻松地创建为 TV 量身定制的界面。在某些情况下，这些组件与对应的非 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.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")
}

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

不同之处

TV Material 组件专为客厅设计，具有清晰的焦点指示器和适合遥控器的输入行为。如需详细了解如何使用这些特定组件，请参阅电视界面设计指南。

请尽可能使用TV 版本的 API，以便获享这些功能。

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

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

其他资源

• TV 设计指南
  简要介绍了用于构建界面的专用 TV 组件，并提供了指向相关开发者资源的链接。

• TV Material 目录示例
  此目录应用演示了如何使用 Compose for TV 实现 Material Design 原则。

• JetStream 示例
  一款媒体在线播放应用，演示了如何将 TV Compose 与典型的 Material 应用和实际架构搭配使用。

• Compose for TV 简介
  此 Codelab 将逐步引导您构建一个包含目录浏览器界面和详情界面的视频播放器应用。

深入阅读

请探索以下指南，了解如何针对以下设备打造针对 TV 优化的出色体验：

• 目录浏览屏幕
• 详情页面