轮播界面

轮播界面会显示可滚动列表，其中的项会根据窗口大小动态调整。您可以使用轮播界面来展示一系列相关内容。 轮播界面中的项会突出显示视觉元素，但也可以包含简短的文字，这些文字会根据项的大小进行调整。

有四种轮播界面布局可供选择，以满足不同的使用情形：

  • 多项浏览：包含大小不同的项。建议用于一次浏览多个项，例如照片。
  • 无容器：包含大小相同的项，这些项会流过屏幕边缘 。可以自定义，以便在每个项上方或下方显示更多文字或其他界面。
  • 焦点：突出显示一个大图片以聚焦，并通过一个小项提供下一个内容的预览。建议用于突出显示您想要强调的内容，例如电影或节目缩略图。
  • 全屏：一次显示一个从边缘到边缘的大项，并垂直滚动。建议用于高度大于宽度的内容。
并排显示的不含容器的全屏轮播界面类型。非容器轮播广告类型包含多个轮播广告项，而全屏轮播广告类型包含一个占据整个屏幕的广告项
图 1.无容器 (1) 和全屏 (2) 轮播界面类型。

本页面介绍了如何实现多项浏览和无容器轮播界面布局。如需详细了解布局类型，请参阅轮播界面 Material 3 指南，

API Surface

如需实现多项浏览和无容器轮播界面，请使用 HorizontalMultiBrowseCarousel 和 HorizontalUncontainedCarousel 可组合项。这些可组合项共享以下关键参数：

  • state：一个 CarouselState 实例，用于管理当前项索引和滚动位置。使用 rememberCarouselState { itemCount } 创建此状态， 其中 itemCount 是轮播界面中的项总数。
  • itemSpacing：用于定义轮播界面中相邻项之间的空白区域大小。
  • contentPadding：用于在轮播界面的内容区域周围应用内边距。您可以使用此参数在第一项之前或最后一项之后添加间距，或为可滚动区域内的项提供边距。
  • content：一个可组合函数，用于接收整数索引。您可以使用此 lambda 根据索引为轮播界面中的每个项定义界面。

这些可组合项在指定项大小的方式上有所不同：

  • itemWidth（适用于 HorizontalUncontainedCarousel）：用于指定无容器轮播界面中每个项的确切宽度。
  • preferredItemWidth（适用于 HorizontalMultiBrowseCarousel）：用于建议多项浏览轮播界面中项的理想宽度，以便组件在空间允许的情况下显示多个项。

示例：多项浏览轮播界面

以下代码段实现了一个多项浏览轮播界面：

代码要点

  • 定义一个 CarouselItem 数据类，用于构建轮播界面中每个元素的数据。
  • 创建并记住一个 CarouselItem 对象 List，其中填充了图片资源和说明。
  • 使用 HorizontalMultiBrowseCarousel 可组合项，该可组合项专为在轮播界面中显示多个项而设计。
    • 轮播界面的状态使用 rememberCarouselState 初始化，该状态会获得项的总数。
    • 项具有 preferredItemWidth（此处为 186.dp），用于建议每个项的最佳宽度。轮播界面使用此参数来确定一次可以在屏幕上显示多少项。
    • itemSpacing 参数会在项之间添加一个小间距。
    • HorizontalMultiBrowseCarousel 的尾随 lambda 会遍历 CarouselItems。在每次迭代中，它都会检索索引 i 处的项，并为其呈现 Image 可组合项。
    • Modifier.maskClip(MaterialTheme.shapes.extraLarge) 会将预定义的形状遮罩应用于每个图片，使其具有圆角。
    • contentDescription 为图片提供无障碍功能说明。

结果

下图显示了上述代码段的结果：

一个包含 3 张图片的多浏览轮播界面，其中两张图片完整显示，一张图片部分显示在屏幕外。
图 2.一个多项浏览轮播界面，其中最后一项被剪裁。

示例：无容器轮播界面

以下代码段实现了一个无容器轮播界面：

代码要点

  • HorizontalUncontainedCarousel 可组合项用于创建轮播界面布局。
    • itemWidth 参数用于为轮播界面中的每个项设置固定宽度。

结果

下图显示了上述代码段的结果：

包含 3 项内容的非容器化轮播界面。最后一项部分可见，但未被剪裁。
图 3.一个无容器轮播界面，其中轮播界面中的最后一项未被剪裁。