轮播图

轮播图显示一个可滚动的项目列表，这些项目会根据窗口大小动态调整。使用轮播图展示一组相关内容。轮播图项目侧重于视觉效果，但也可以包含适应项目大小的简短文本。

有四种轮播图布局可供选择，以适应不同的用例：

  • 多浏览：包含不同大小的项目。建议用于一次浏览多个项目，例如照片。
  • 未限制：包含单一大小的项目，这些项目会流出屏幕边缘。可以自定义以在每个项目上方或下方显示更多文本或其他 UI。
  • 主推：突出显示一张大图以供聚焦，并提供一个小项目以预览接下来内容。建议用于突出显示您想要强调的内容，例如电影或节目缩略图。
  • 全屏：一次显示一个边缘到边缘的大项目，并垂直滚动。建议用于高度大于宽度的内容。
An uncontained and full-screen carousel type shown next to each other. The uncontained carousel type has multiple carousel items, while full-screen has one item taking up the screen
图 1. 未限制 (1) 和全屏 (2) 轮播图类型。

本页面向您展示如何实现多浏览和未限制轮播图布局。有关布局类型的更多信息，请参阅 轮播图 Material 3 指南。

API 接口

要实现多浏览和未限制轮播图，请使用 HorizontalMultiBrowseCarousel 和 HorizontalUncontainedCarousel 可组合项。这些可组合项共享以下关键参数：

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

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

  • itemWidth（适用于 HorizontalUncontainedCarousel）：指定未限制轮播图中每个项目的确切宽度。
  • preferredItemWidth（适用于 HorizontalMultiBrowseCarousel）：建议多浏览轮播图中项目的理想宽度，如果空间允许，组件可以显示多个项目。

示例：多浏览轮播图

此代码段实现了多浏览轮播图：

关于代码的要点：

  • 定义了一个 CarouselItem 数据类，用于构造轮播图中每个元素的数据。
  • 创建并记住一个 CarouselItem 对象列表，该列表填充了图像资源和描述。
  • 使用 HorizontalMultiBrowseCarousel 可组合项，它专为在轮播图中显示多个项目而设计。
    • 轮播图的状态使用 rememberCarouselState 初始化，并传入项目的总数。
    • 项目具有 preferredItemWidth（此处为 186.dp），它建议了每个项目的最佳宽度。轮播图使用此宽度来确定一次可在屏幕上容纳多少个项目。
    • itemSpacing 参数在项目之间添加了小间隙。
    • HorizontalMultiBrowseCarousel 的尾随 lambda 迭代 CarouselItems。在每次迭代中，它检索索引 i 处的项目并为其渲染一个 Image 可组合项。
    • Modifier.maskClip(MaterialTheme.shapes.extraLarge) 对每个图像应用预定义的形状遮罩，使其具有圆角。
    • contentDescription 为图像提供了无障碍描述。

结果

下图显示了前面代码段的结果：

A multi-browse carousel with 3 images, two of which are fully shown and one which is partially offscreen.
图 2. 一个多浏览轮播图，最后一个项目被裁剪。

示例：未限制轮播图

以下代码段实现了一个未限制轮播图：

关于代码的要点：

  • HorizontalUncontainedCarousel 可组合项创建了轮播图布局。
    • itemWidth 参数为轮播图中的每个项目设置了固定宽度。

结果

下图显示了前面代码段的结果：

An uncontained carousel with 3 items. The last item is partially visible, but not clipped.
图 3. 一个未限制轮播图，其中轮播图中的最后一个项目未被裁剪。