轮播界面

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

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

• 多项浏览：包含大小不同的项目。建议用于一次浏览多个项目，例如照片。
• 无容器：包含大小相同的项目，这些项目会流过屏幕边缘。可以自定义，以便在每个项目上方或下方显示更多文字或其他界面。
• 焦点：突出显示一张大图片以供关注，并使用小项目预览下一张图片。建议用于突出显示您想要强调的内容，例如电影或节目缩略图。
• 全屏：一次显示一个边缘到边缘的大项目，并垂直滚动。建议用于高度大于宽度的内容。

图 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 数据类，用于构建轮播界面中每个元素的数据。
• 创建并记住填充了图片资源和说明的 CarouselItem 对象的 List。
• 使用 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.无容器轮播界面，其中轮播界面中的最后一个项目未被剪裁。