tv

  
为开发者提供 Compose 和 Material Design 功能，以便编写 TV 应用
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2024 年 8 月 21 日 1.0.0 - - -

声明依赖项

若要添加 tv-foundation 和 tv-material 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    implementation "androidx.tv:tv-foundation:1.0.0-alpha11"
    implementation "androidx.tv:tv-material:1.0.0"
}

Kotlin

dependencies {
    implementation("androidx.tv:tv-foundation:1.0.0-alpha11")
    implementation("androidx.tv:tv-material:1.0.0")
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

此工件没有版本说明。

Tv-Material 版本 1.0

版本 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 中包含这些提交内容。

bug 修复

  • 修复了 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)
  • Surface 组件现已稳定（I58758、I04aca）
  • 已将 NonInteractiveSurfaceDefaults 重命名为 SurfaceDefaults，并将 NonInteractiveSurfaceColors 重命名为 SurfaceColors (I0812e)
  • Selectable Surface 现在使用“select”而不是“check”，因为它们具有不同的语义含义 (I5a206)
  • NavigationDrawer 和 NavigationDrawerScope 现已稳定 (I249c1)
  • NavigationDrawerItem 组件现已稳定 (Id6986)
  • Tab 和 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）
  • 更新了在其 API 中公开 MutableInteractionSource 的 tv-material 组件，现在公开了一个默认为 null 的可为 null MutableInteractionSource。这里没有语义更改：传递 null 表示您不希望提升 MutableInteractionSource，系统将根据需要在组件内创建它。如果更改为 null，则某些组件永远不会分配 MutableInteractionSource，而允许其他组件仅在需要时延迟创建实例，从而提高这些组件的性能。如果您未使用传递给这些组件的 MutableInteractionSource，建议您改为传递 null。此外，我们还建议您在自己的组件中进行类似的更改。（I309b4、b/298048146）
  • TV Text 组件的 TextAlign 参数现在为非 null（Ib73b1、b/299490814）
  • 为 ParagraphTextStyle 的 TextAlign、TextDirection、Hyphens 和 LineBreak 字段引入了一个特殊的未指定值进行替换（I4197e、b/299490814）

行为变更

  • 非交互式 Surface 的 shape 参数的默认值已更改为 RectangleShape (I1b859cb)
  • 由于必要的 API 处于实验阶段，某些轮播界面功能已被舍弃在 Beta 版发布中 (I0e755d4)
  • 在 Surface 中更改 contentColor 不会再在状态之间添加动画效果 (I436e794f)

版本 1.0.0

版本 1.0.0-alpha11

2024 年 7 月 10 日

发布了 androidx.tv:tv-foundation:1.0.0-alpha11。版本 1.0.0-alpha11 中包含这些提交内容。

API 变更

  • TV 延迟布局已从 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 中包含这些提交内容。

新功能

  • 引入了在 NavigationDrawer 和 ModalNavigationDrawer 中使用的 NavigationDrawerItem。（I4b491）
  • 向 tv-foundation 库添加了基准配置文件。(2b57fd7)
  • 向 tv-material 库添加了基准配置文件。(1711ff5)

API 变更

  • NavigationDrawerScope.doesTabRowHaveFocus 已重命名为 NavigationDrawerScope.hasFocus。（I8286b）
  • TabRowScope.isActivated 已重命名为 TabRowScope.hasFocus。（Ic4273）

bug 修复

  • 修复了轮播界面与使用焦点恢复器 API 的相邻项的兼容性。（7b2a7a4）
  • 为低于 28 的 API_LEVEL 停用发光指示，因为操作系统不支持。(6d3616f)
  • 修复了由于反向快速滚动时项在延迟容器中不当放置而导致的 ANR 崩溃问题。（642d65c）
  • 移除了模态抽屉式导航栏中的背景内边距。(69965b2)
  • 修复了抽屉式导航栏中的纱罩，使其在背景内容上方而不是在背景内容后面绘制。(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 Material 引入了 Chip 组件。(I86da4)
  • 在 TV Compose Material 中添加了 ListItem 组件。(I3f0b3)
  • 在 TV Compose Material 中添加了 DenseListItem 组件。(I536bf)

API 变更

  • 将公共的 tv-material API 标记成了实验性 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)
  • 针对 TV Material Surface 将 color 与 contentColor 两个参数合并成了 colors。(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)
  • 添加了针对 TV 进行了优化的 Material 3 按钮实现。

API 变更

  • 将 Carousel 中的 CarouselSlide 和 slideCount 重命名为了 CarouselItem 和 itemCount。(Ie554c)
  • 将 forward 和 backward ContentTransforms 重命名为了 StartToEnd 和 EndToStart。(Ie554c)

bug 修复

  • 当焦点位于 NavigationDrawer 上时处理方向键返回按钮。(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 中引入了侧边抽屉式导航栏可组合项。如需了解如何使用此可组合项，请参考示例。(I12c08)
  • 在 TV Material 3 中引入了图标可组合项。(I72db9)
  • 在 tv-material 中引入了 Surface 可组合项，带有边框、发光、缩放等指示，可用于构建能清晰突出 TV 屏幕上的聚焦元素的组件。(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 中包含这些提交内容。

新功能

  • 在延迟行、列和网格中，必要时可覆盖轴心，以确保整个项显示到视野中。(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)
  • 引入了 PinnableContainer API，由延迟列表通过本地组合进行传播，以便固定当前项。（Ib8881、b/259274257、b/195049010）
  • 向 TvLazyListLayoutInfo 和 TvLazyGridLayoutInfo 添加了 mainAxisItemSpacing 属性 (I37765)

bug 修复

  • 更新了标签页行，以确保它能正确处理标签页数量为 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 设备应该会加载标签页。
  • TV 专用指示器（比如底线状指示器和药丸状指示器）均可即开即用。您可在 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 中包含这些提交内容。

bug 修复

  • 通过减少焦点搜索空间，提升了滚动一系列 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 版包含适用于 TV 用例的组件的早期预览版实现，包括：

  • 添加了修饰符 scrollableWithPivot，可允许非延迟滚动容器（例如：行、列和网格）让滚动容器滚动内容，从而使获得焦点的项在 TV 屏幕上保持同一位置。
  • 添加了可组合项 TvLazyRow、TvLazyColumn、TvLazyHorizontalGrid 和 TvLazyVerticalGrid，可让滚动容器滚动内容，从而使获得焦点的项目在 TV 屏幕上保持同一位置。
  • 添加了适用于 TV 的精选轮播界面可组合项，可让用户创建自动滚动横幅的轮播界面。
  • 为 TV 添加了沉浸式列表可组合项，可让用户创建根据获得焦点的列表项来更改背景的沉浸式行/列/网格。

已知问题

  • 默认情况下，滚动容器获得焦点后，第一个元素不会获得焦点。
  • 聚焦在 TextField 上时，不一定会打开键盘，也可能阻止焦点移至其他字段。
  • 在包含 LazyRows 的 LazyColumn 中垂直滚动时，性能不佳。