轮播界面

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

有四种轮播界面布局可供选择，以适应不同的应用场景：

• 多浏览：包含不同尺寸的商品。建议用于一次浏览多个内容，例如照片。
• 无容器：包含大小相同且会流过屏幕边缘的内容。可自定义为在每个内容项上方或下方显示更多文字或其他界面。
• 主打：突出显示一张大图片以吸引注意力，并提供一个小内容项来预览下一个内容。建议用于突出显示您要强调的内容，例如电影或节目缩略图。
• 全屏：一次显示一个无边框的大型内容，并垂直滚动。建议用于高度大于宽度的内容。

图 1. 无容器 (1) 和全屏 (2) 轮播界面类型。

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

API Surface

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

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

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

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

示例：多浏览轮播界面

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

@Composable
fun CarouselExample_MultiBrowse() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val items = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalMultiBrowseCarousel(
        state = rememberCarouselState { items.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        preferredItemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = items[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

代码要点

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

结果

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

图 2. 多浏览轮播界面，最后一项内容被剪裁。

示例：无容器轮播界面

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

@Composable
fun CarouselExample() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val carouselItems = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalUncontainedCarousel(
        state = rememberCarouselState { carouselItems.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        itemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = carouselItems[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

代码要点

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

结果

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

图 3. 无容器轮播界面，其中轮播界面中的最后一项未被剪裁。