電視

  
為開發人員提供 Compose 和質感設計功能，以編寫用於電視的應用程式
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 7 月 16 日 1.0.1 - - 1.1.0-alpha01

宣告依附元件

如要為 tv-foundation 和 tv-material 新增依附元件，您必須將 Google Maven 存放區新增至您的專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    implementation "androidx.tv:tv-foundation:1.0.0-alpha12"
    implementation "androidx.tv:tv-material:1.1.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.tv:tv-foundation:1.0.0-alpha12")
    implementation("androidx.tv:tv-material:1.1.0-alpha01")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

這個構件沒有任何版本資訊。

Tv-Material 1.1 版

1.1.0-alpha01 版本

2025 年 1 月 15 日

發布 androidx.tv:tv-material:1.1.0-alpha01。1.1.0-alpha01 版包含這些修訂版本。

API 變更

  • 將 FocusEnterExitScope.cancelFocus() 變更為 cancelFocusChange()(I89959)
  • FocusProperties.enter 和 FocusProperties.exit 已分別替換為 onEnter 和 onExit，並使用接收器範圍而非 FocusDirection 參數。(I6e667)

修正錯誤

  • 將 CompositingStrategy.OffScreen 從 Surface 移至 Text，修正縮放時文字抖動的問題。(I92b15f17)
  • 修正輪轉介面中失效的焦點管理功能 (Ie508b721375)
  • 相較於互動式 Surface，非互動式 Surface 的導入程序較為簡化。(I7ea545150)

Tv-Material 1.0 版

1.0.1 版

2025 年 7 月 16 日

發布 androidx.tv:tv-material:1.0.1。1.0.1 版包含這些修訂項目。

修正錯誤

  • 已更新 NavigationDrawerItem 的高度，以符合規格。(cf9a3ce)
  • 將合成策略設定從 Surface 可組合函式移至 Text 可組合函式。修正錯誤：在較低的 Android API 版本中，Exoplayer 無法在 Surface 可組合函式上算繪。(9858ffb)

1.0.0 版本

2024 年 8 月 21 日

發布 androidx.tv:tv-material:1.0.0。1.0.0 版是 androidx.tv:tv-material 的第一個穩定版。

1.0.0-rc02 版

2024 年 8 月 7 日

發布 androidx.tv:tv-material:1.0.0-rc02。1.0.0-rc02 版包含這些修訂項目。

修正錯誤

  • 修正 Surface 可組合函式中文字動畫抖動的問題。(3163319)

1.0.0-rc01 版

2024 年 7 月 10 日

發布 androidx.tv:tv-material:1.0.0-rc01。1.0.0-rc01 版包含這些修訂項目。

1.0.0-beta01 版

2024 年 5 月 1 日

發布 androidx.tv:tv-material:1.0.0-beta01。1.0.0-beta01 版包含這些修訂項目。

API 變更

  • ColorScheme 及其公用程式函式現已穩定。(If34fa)
  • LocalContentColor 現在是穩定版 (I60ee2)
  • Typography API 現在是穩定版 (I088d6)
  • Shapes API 現已穩定運作 (I0f5f4)
  • Border API 現在是穩定版 (I69281)
  • Glow API 現在是穩定版 (Iea5f1)
  • 圖示元件現已穩定 (I62c2d)
  • LocalTextStyles API 現在是穩定版 (Iaded8)
  • MaterialTheme API 現在是穩定版 (I2f541)
  • 文字元件現已推出穩定版 (Ib9e31)
  • RadioButton 元件現已穩定 (Ia03c8)
  • Switch 元件現已穩定 (I6cea3)
  • Checkbox 元件現已穩定 (I7eafc)
  • 介面元件現已穩定 (I58758、I04aca)
  • 已將 NonInteractiveSurfaceDefaults 重新命名為 SurfaceDefaults，並將 NonInteractiveSurfaceColors 重新命名為 SurfaceColors (I0812e)
  • Selectable Surface 現在使用「select」一詞，而非「check」，因為兩者語意不同 (I5a206)
  • NavigationDrawer 和 NavigationDrawerScope 現已穩定 (I249c1)
  • NavigationDrawerItem 元件現在為穩定版 (Id6986)
  • 「分頁」和 TabRow 元件現已穩定 (I92d92)
  • Button、OutlinedButton、IconButton、OutlinedIconButton 和 WideButton 元件現已改為穩定版 (Ib4de8)
  • Card、ClassicCard、CompactCard、WideClassicCard、StandardCardContainer 和 WideCardContainer 元件現已穩定 (I34390)
  • 已將 StandardCardLayout 重新命名為 StandardCardContainer，並將 WideCardLayout 重新命名為 WideCardContainer (I08883)
  • 移除 CardContainerDefaults.ImageCard，並將 CardDefaults.ContainerGradient 重新命名為 CardDefaults.ScrimBrush (I6adfe)。您可以在資訊卡容器中使用 Card 取代 CardContainerDefaults.ImageCard。
  • ListItem 和 DenseListItem 現已穩定 (Idebd9)
  • ListItemDefaults.ListItemShape、ListItemDefaults.FocusedDisabledBorder和 ListItemDefaults.SelectedContainerColorOpacity 現在為私人內容 (I5d533)
  • 重新排列 ListItem 的參數，並將 ListItemDefaults.ListItemElevation 重新命名為 ListItemDefaults.TonalElevation (Id6841)。headlineContent 參數已移至可組合函式的頂端。先前，您可以利用 Kotlin 的結尾 lambda 語法傳遞 headlineContent。現在，您必須使用具名參數語法提供 headlineContent。
  • LocalAbsoluteTonalElevation 現在是內部版本 (Ibfc65)
  • 已移除 ImmersiveList 元件。如要瞭解如何自行建構，請參閱這個範例。(Id48da)
  • tv-material 元件已更新，現在會公開可為空值的 MutableInteractionSource，預設為空值。MutableInteractionSource這裡沒有語意變更：傳遞空值表示您不希望提升 MutableInteractionSource，且系統會在元件內建立 MutableInteractionSource (如有需要)。變更為空值可讓某些元件永遠不會分配 MutableInteractionSource，其他元件則只會在需要時延遲建立執行個體，進而提升這些元件的效能。如果您未使用傳遞至這些元件的 MutableInteractionSource，建議改為傳遞空值。建議您在自己的元件中進行類似變更。(I309b4、b/298048146)
  • TV Text 元件的 TextAlign 參數現在為非空值 (Ib73b1、b/299490814)
  • 為 ParagraphTextStyle 的 TextAlign、TextDirection、Hyphens 和 LineBreak 欄位導入特殊的 Unspecified 值，以取代 (I4197e、b/299490814)

行為變更

  • 非互動式 Surface 的 shape 參數預設值已變更為 RectangleShape (I1b859cb)
  • 由於必要 API 屬於實驗性質，因此在 Beta 版發布時，部分輪播功能已遭捨棄 (I0e755d4)
  • 變更 Surface 中的 contentColor 時，不再會顯示狀態之間的動畫效果 (I436e794f)

1.0.0 版本

1.0.0-alpha12 版

2025 年 1 月 15 日

發布 androidx.tv:tv-foundation:1.0.0-alpha12。1.0.0-alpha12 版包含這些修訂項目。

API 變更

  • 從 tv-foundation 清理延遲載入的版面配置。請參閱 1.0.0-alpha11 版本資訊，瞭解如何從 tv-foundation 延遲版面配置遷移。(I2fdd3、b/358913893)

1.0.0-alpha11 版本

2024 年 7 月 10 日

發布 androidx.tv:tv-foundation:1.0.0-alpha11。1.0.0-alpha11 版包含這些修訂項目。

API 變更

  • Tv Lazy Layouts 已從 tv-foundation 程式庫中淘汰。如要瞭解如何從電視延遲版面配置遷移，請參閱這張單據。(I0855f、b/332674072)
  • PlatformImeOptions 現在是具體類別，而不是介面。(If40a4)

1.0.0-alpha10 版本

2023 年 10 月 4 日

發布 androidx.tv:tv-foundation:1.0.0-alpha10 和 androidx.tv:tv-material:1.0.0-alpha10。查看 1.0.0-alpha10 版的修訂項。

新功能

  • 導入 NavigationDrawerItem，可在 NavigationDrawer 和 ModalNavigationDrawer 中使用。(I4b491)
  • 將基準設定檔新增至 tv-foundation 程式庫。(2b57fd7)
  • 將基準設定檔新增至 tv-material 程式庫。(1711ff5)

API 變更

  • NavigationDrawerScope.doesTabRowHaveFocus 已重新命名為 NavigationDrawerScope.hasFocus。(I8286b)
  • TabRowScope.isActivated 已重新命名為 TabRowScope.hasFocus。(Ic4273)

修正錯誤

  • 修正輪播與使用焦點還原工具 API 的相鄰項目之間的相容性。(7b2a7a4)
  • 針對 API_LEVEL 低於 28 的版本停用發光指示，因為作業系統不支援這項功能。(6d3616f)
  • 修正在反向快速捲動時，因項目在延遲容器中放置不當而導致 ANR 當機的問題。(642d65c)
  • 移除了「模式導覽匣」的背景邊框間距。(69965b2)
  • 修正導覽匣中的 Scrim，使其繪製在背景內容上方，而非後方。(d4bbefb)

1.0.0-alpha09 版本

2023 年 9 月 6 日

發布 androidx.tv:tv-foundation:1.0.0-alpha09 和 androidx.tv:tv-material:1.0.0-alpha09。1.0.0-alpha09 版包含此連結所列的修訂項目。

API 變更

  • 新增 ReusableComposition 介面，用於管理子組合的生命週期和重複使用。(I812d1、b/252846775)
  • 將 tv-foundation 分支與 compose-foundation 同步。(I737c3、b/287011882)
  • 新增 LazyLayout 的多載，現在接受 LazyLayoutItemProvider 的 lambda，而非先前的純物件。先前的多載已淘汰。(I42a5a)
  • 新增 TvKeyboardAlignment，讓開發人員透過 AndroidImeOptions 設定螢幕小鍵盤位置。(Idb772)
  • 新增 rememberCarouselState，即可使用 Saver 記住 CarouselState，以便在 TV Compose Material 中使用。(Id7275)
  • 將 scrimColor: Color 參數變更為 scrimBrush:Brush 參數，讓使用者在半透明遮罩中加入漸層。(I254d4)

1.0.0-alpha08 版本

2023 年 7 月 26 日

發布 androidx.tv:tv-foundation:1.0.0-alpha08 和 androidx.tv:tv-material:1.0.0-alpha08。1.0.0-alpha08 版包含此連結所列的修訂項目。

新功能

  • 推出 Compose for TV 材質的 Chip 元件。(I86da4)
  • 將 ListItem 元件新增至 TV Compose Material。(I3f0b3)
  • 將 DenseListItem 元件新增至 TV Compose Material。(I536bf)

API 變更

  • 將公開的 TV-Material API 標示為實驗性質。(I632e7)
  • 導入 TabRowScope，以便從 TabRow 可組合函式與 Tab 可組合函式共用狀態，並重新命名 TabColors 屬性。(Ief587)

1.0.0-alpha07 版本

2023 年 6 月 7 日

發布 androidx.tv:tv-foundation:1.0.0-alpha07 和 androidx.tv:tv-material:1.0.0-alpha07。1.0.0-alpha07 版包含此連結所列的修訂項目。

API 變更

  • 元件的縮放比例指標現在包含「無」，可停用縮放功能。(I50df5)
  • 為 TV Material Surface、資訊卡和按鈕新增長按支援功能。(Id2b89)
  • 已移除 CarouselItem 和 CarouselScope。如要在投影片中製作前景內容動畫，請使用 AnimatedContentScope 中的 Modifier.animateEnterExit。(Ic038e)
  • 將 color 和 contentColor 參數合併為 colors，適用於 TV Material Surface。(Ie69eb)
  • 在 TV Material 中導入 RadioButton 可組合函式。(I08690)
  • 在 TV Material 中導入 Switch 可組合函式。(I45e29)
  • 在 TV Material 中導入 Checkbox 可組合函式。(I6a45a)
  • 在 TV Material 中導入無法互動的 Surface。(Ic5f85)
  • 將適應症設為內部。(Ibff82)

1.0.0-alpha06 版本

2023 年 4 月 19 日

發布 androidx.tv:tv-foundation:1.0.0-alpha06 和 androidx.tv:tv-material:1.0.0-alpha06。1.0.0-alpha06 版包含此連結所列的修訂項目。

新功能

  • 新增針對 TV 最佳化的 Material 3 資訊卡實作項目。
    • 基本資訊卡 (I5b701)
    • ClassicCard、CompactCard 和 WideClassicCard (I70471)
    • StandardCardLayout 和 WideCardLayout (I33fae)
  • 新增針對電視最佳化的 Material 3 按鈕實作項目。

API 變更

  • 已將 Carousel 中的 CarouselSlide 和 slideCount 重新命名為 CarouselItem 和 itemCount。(Ie554c)
  • 已將 forward 和 backward ContentTransforms 重新命名為 StartToEnd 和 EndToStart。(Ie554c)

修正錯誤

  • 焦點位於 NavigationDrawer 時，處理返回 D-PAD 按鈕。(d654f4)

1.0.0-alpha05 版本

2023 年 3 月 22 日

發布 androidx.tv:tv-foundation:1.0.0-alpha05 和 androidx.tv:tv-material:1.0.0-alpha05。1.0.0-alpha05 版包含此連結所列的修訂項目。

API 變更

  • 在 tv-material 中導入 Side Navigation Drawer 可組合函式。如要瞭解如何使用這個可組合函式，請參閱範例。(I12c08)
  • 在 TV Material 3 中導入 Icon 可組合項 (I72db9)
  • 推出 Surface 可組合函式，其中包含 Border、Glow 和 Scale 等指標，可用於建構元件，在電視畫面上清楚醒目顯示焦點元素。tv-material(I4a6d8)、 (Iceea1)、 (Iee4d4)、 (I79edf)、 (Icb376)
  • 將 CarouselItem 更新為 CarouselSlide，以符合「Carousel」API 中的 slideCount 參數名稱 (Ic4299)

1.0.0-alpha04 版本

2023 年 2 月 8 日

發布 androidx.tv:tv-foundation:1.0.0-alpha04 和 androidx.tv:tv-material:1.0.0-alpha04。1.0.0-alpha04 版包含此連結所列的修訂項目。

新功能

  • 可以視需要覆寫 Lazy 列、欄和格線中的樞紐，確保整個項目呈現在檢視畫面中。(11d7e40)
  • 支援自訂分頁在各種狀態下的顏色。(21b2925)
  • 輪轉介面支援設定手動前後捲動的自訂動畫。(431494a)

API 變更

  • 將 androidx.tv.material 重新命名為 androidx.tv.material3，並簡化 androidx.tv.material3 底下的套件結構。(I6ca52)
  • 輪轉介面指標列中的指標已成為開發人員可以自訂的運算單元。(268af2a)
  • focusableItem 已重新命名為 immersiveListItem。使用者將必須手動新增 focusable() 或 clickable() 修飾符和 immersiveListItem (5dd5078)(b/263061052)
  • 輪轉介面元件中的 timeToDisplayMillis 已重新命名為 autoScrollDurationMillis。(431494a)
  • CarouselItem 只能在 Carousel 中使用。(431494a)
  • 輪轉介面接受 ContentTransforms 做為動畫定義，不接受 EnterTransition 和 ExitTransitions。(431494a)
  • 透過本機組合導入可由 Lazy 清單提供的 PinnableContainer API，藉此固定目前項目。(Ib8881、b/259274257、b/195049010)
  • 在 TvLazyListLayoutInfo 和 TvLazyGridLayoutInfo 中新增 mainAxisItemSpacing 屬性 (I37765)

修正錯誤

  • 更新分頁標籤列，確保能正確處理分頁標籤數為 0 或 1 的情況。(I44009、1c01525、b/264018028)
  • 修正當 TvLazyColumn 含有空白 TvLazyRow 時會導致焦點搜尋異常終止的問題。(e11b4fe)、(b/260299091)
  • clickable 修飾符可與 ImmersiveList 搭配使用。(5dd5078)、(b/263061052)
  • 支援處理返回鍵操作，可使用返回鍵退出精選輪轉介面。(84c138c)
  • 輪轉介面不會因為快速多次按下按鍵而失去焦點。(799489f)
  • 輪轉介面不會因為長按按鍵而失去焦點。(b2cf37e)
  • 修正當輪轉介面滑動次數變更時發生的當機問題。(b261247)

1.0.0-alpha03 版本

2022 年 12 月 7 日

發布 androidx.tv:tv-foundation:1.0.0-alpha03 和 androidx.tv:tv-material:1.0.0-alpha03。1.0.0-alpha03 版包含此連結所列的修訂項目。

新功能

  • TabRow 現已做為實驗性 API 提供，可讓使用者將上方瀏覽列新增至其應用程式。一般而言，當焦點落在分頁標籤列中的分頁標題上，電視裝置應該會載入分頁。
  • 並未直接提供如底線指標和藥丸形狀指標等電視特定指標。您可以在 tv-samples 中找到使用範例

1.0.0-alpha02 版

2022 年 11 月 9 日

發布 androidx.tv:tv-foundation:1.0.0-alpha02 和 androidx.tv:tv-material:1.0.0-alpha02。1.0.0-alpha02 版包含此連結所列的修訂項目。

修正錯誤

  • 縮減聚焦搜尋空間，藉此改善捲動一組 TvLazyRows/TvLazyColumns 時的捲動效能。(I723a3)

1.0.0-alpha01 版

2022 年 10 月 5 日

發布 androidx.tv:tv-foundation:1.0.0-alpha01 和 androidx.tv:tv-material:1.0.0-alpha01。1.0.0-alpha01 版包含此連結所列的修訂項目。

新功能

第一個 Alpha 版包含下列早期預先發布版的元件實作，適用於電視用途：

  • 新增修飾符 scrollableWithPivot，允許非延遲捲動容器 (例如 Row、Column、Grid) 透過捲動容器來捲動內容，讓已選取項目保持在電視螢幕的相同位置。
  • 新增可組合項 TvLazyRow、TvLazyColumn、TvLazyHorizontalGrid 和 TvLazyVerticalGrid，以利透過捲動容器來捲動內容，讓已選取項目保持在電視螢幕的相同位置。
  • 為電視新增「精選輪轉介面」可組合項目，以便使用者建立自動捲動的橫幅輪轉介面。
  • 為電視新增「沉浸式清單」可組合項目，以便使用者建立沉浸式列/欄/格狀清單，並根據已選取清單項目變更背景。

已知問題

  • 根據預設，當捲動容器取得焦點時，第一個元素不會取得焦點。
  • 聚焦於 TextField 時，不一定會開啟鍵盤，也可能導致焦點無法移至其他欄位。
  • 如果在包含 LazyRows 的 LazyColumn 中垂直捲動，則捲動效能不佳。