在 Android TV 上使用 Jetpack Compose

Compose for TV 是建構 Android TV 使用者介面的新型方法。Compose for TV 可享有適用於 TV 應用程式的 Android Jetpack Compose 所有優勢，更輕鬆地為應用程式建構美觀且實用的使用者介面。

使用 Compose for TV 的一些特定優點如下：

• 彈性：Compose 可用於建立任何類型的 UI，從簡單的版面配置到複雜的動畫都沒問題。元件可立即使用，但也可以配合應用程式需求自訂及設定樣式。
• 簡化開發程序，加快開發速度：Compose 與現有程式碼相容，可讓開發人員用較少的程式碼建構應用程式，提高開發效率。
• 操作直覺：Compose 採用宣告式語法，讓您以符合直覺的方式變更使用者介面，以及偵錯、解讀和檢查程式碼。

如果您對 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 版本時，必須使用 1.3.0 版的 androidx.compose 程式庫和 Kotlin 1.7.10。

設定

在 Android TV 上使用 Jetpack Compose 的方法和其他 Android 專案使用 Jetpack Compose 的方式非常類似。主要差異在於 Compose for 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'
}

差異

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

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

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

下表列出 TV 和 Mobile 依附元件的不同點：

其他資源

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

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

• JetStream 範例
  媒體串流應用程式，可展示如何搭配典型的 Material 應用程式和實際架構使用 TV Compose。

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

其他資訊

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

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