在 Android TV 上使用 Jetpack Compose

建議您使用 Compose for TV 建構 Android 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 適用於 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 新增了程式庫,提供電視最佳化元件,讓您更輕鬆地建立電視專屬的使用者介面。在某些情況下,這些元件會與其非電視相關元件的名稱相同,例如 androidx.tv.material3.Buttonandroidx.compose.material3.Button

Jetpack Compose 工具包依附元件

如要使用 Compose for TV,您必須在應用程式的 build.gradle 檔案中加入 Jetpack Compose 工具包依附元件,如下所示:

Kotlin

dependencies {
   val composeBom = platform("androidx.compose:compose-bom:2024.06.00")
   implementation(composeBom)

   // General compose dependencies
   implementation("androidx.activity:activity-compose:1.9.0")

   implementation("androidx.compose.ui:ui-tooling-preview")
   debugImplementation("androidx.compose.ui:ui-tooling")

   // Compose for TV dependencies
   implementation("androidx.tv:tv-foundation:1.0.0-alpha10")
   implementation("androidx.tv:tv-material:1.0.0-beta01")
}

Groovy

dependencies {
   def composeBom = platform('androidx.compose:compose-bom:2024.06.00')
   implementation composeBom

   // General compose dependencies
   implementation 'androidx.activity:activity-compose:1.9.0'

   implementation 'androidx.compose.ui:ui-tooling-preview'
   debugImplementation 'androidx.compose.ui:ui-tooling'

   // Compose for TV dependencies
   implementation 'androidx.tv:tv-foundation:1.0.0-alpha10'
   implementation 'androidx.tv:tv-material:1.0.0-beta01'
}

不同點

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

下表列出電視和行動裝置的依附元件差異:

TV 依附元件
(androidx.tv.*)
比較 Mobile 依附元件
(androidx.compose.*)
androidx.tv:tv-material 而非 androidx.compose.material3:material3
androidx.tv:tv-foundation 搭配使用 androidx.compose.foundation:foundation

其他資源

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

  • JetStream 範例
    這個媒體串流應用程式示範如何將 TV Compose 與一般 Material Design 應用程式和實際架構搭配使用。

  • Compose for TV 簡介
    本程式碼研究室中的步驟,是透過目錄瀏覽器畫面和詳細資料畫面建構影片播放器應用程式。

其他資訊

歡迎瀏覽這些指南,瞭解如何為以下使用者打造優質的電視體驗: