此页面由 Cloud Translation API 翻译。

轮播界面

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

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

多浏览：包含不同尺寸的项。适合一次浏览多个内容（例如照片）。
未包含：包含单一尺寸且超出屏幕边缘的项。可自定义，以在每个项上方或下方显示更多文本或其他界面。
主打：突出显示一张大图片以吸引用户注意，并通过一项小项预览后续内容。建议用于突出显示您想要强调的内容，例如电影或节目缩略图。
全屏：一次显示一个从边到边的大项，并垂直滚动。适用于高度大于宽度的内容。

并排显示的非容器式全屏轮播界面类型。非封闭式轮播界面类型包含多个轮播界面项，而全屏界面只有一个项占据整个屏幕 — **图 1.** 非嵌套 (1) 和全屏 (2) 轮播界面类型。

本页介绍了如何实现多浏览和非包含式轮播界面布局。如需详细了解布局类型，请参阅 Carousel 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 用于为图片提供无障碍功能说明。

结果

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

一个包含 3 张图片的多浏览轮播界面，其中 2 张图片完全显示，1 张图片部分超出屏幕。 — **图 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 项内容的无容器轮播界面。最后一项部分可见，但未被剪裁。 — **图 3.** 未包含容器的轮播界面，其中轮播界面中的最后一项不会被剪裁。