在 Android TV 上使用 Jetpack Compose

Compose for TV 是建構 Android TV 使用者介面的新型方法。Compose for TV 可讓您在 TV 應用程式中充分發揮 Android 的 Jetpack Compose 所有優點，輕鬆為應用程式建構精美且實用的使用者介面。

使用 Compose for TV 的一些具體優點包括：

• 靈活性：Compose 可用於建立任何類型的 UI，從簡單的版面配置到複雜的動畫皆可。元件可立即使用，但也可以自訂及設定樣式，以符合應用程式的需求。
• 簡化及加速開發作業：Compose 與現有程式碼相容，可讓開發人員以更少的程式碼更有效率地建構應用程式。
• 直覺式：Compose 採用宣告式語法，可讓您變更 UI、偵錯、瞭解及查看程式碼。

如果您對 Jetpack Compose 工具包的使用方式不太熟悉，請參閱 Compose 課程。行動版 Compose 的許多開發原則也適用於 TV。如要進一步瞭解宣告式 UI 架構的一般優點，請參閱「為什麼要選擇使用 Compose」。如需更多資訊，請參閱 GitHub 上的 Compose for 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.

相容性

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

異同之處

電視 Material 元件專為客廳設計，提供明確的焦點指標和方便使用遙控器的輸入行為。如要進一步瞭解如何使用這些特定元件，請參閱 電視 UI 設計指南。

盡可能使用 API 的TV 版本，以便運用這些功能。

雖然從技術層面來說，您可以使用行動版 Compose Material，但這並未針對 Android TV 上獨特的互動樣式進行最佳化。此外，將 Compose 材質與 Compose for TV 的 Compose 材質混合，可能會導致未預期的行為。舉例來說，每個程式庫都有自己的 MaterialTheme 物件，如果您同時使用兩種版本，顏色、字體排版和形狀可能會不一致。

下表概略說明 TV 和行動裝置之間的依附元件差異：

其他資源

• 電視設計指南
  概略說明專用電視元件，可用於建構使用者介面，並提供相關開發人員資源的連結。

• TV Material Catalog 範例
  此目錄應用程式可示範如何使用 Compose for TV 實作 Material Design 原則。

• JetStream 範例
  這款媒體串流應用程式可讓您瞭解如何搭配典型的 Material 應用程式和實際架構使用 TV Compose。

• Compose for TV 簡介
  本程式碼研究室將逐步說明如何建構具有目錄瀏覽器畫面和詳細資料畫面的影片播放器應用程式。

其他資訊

請參閱下列指南，瞭解如何為下列裝置打造優質的電視最佳化體驗：

• 目錄瀏覽畫面
• 詳細資料畫面