android compose HorizontalMultiBrowseCarousel 多项浏览轮播界面 使用
有四种轮播界面布局可供选择，以满足不同的使用情形：
- 多项浏览：包含大小不同的项。建议用于一次浏览多个项，例如照片。
- 无容器：包含大小相同的项，这些项会流过屏幕边缘 。可以自定义，以便在每个项上方或下方显示更多文字或其他界面。
- 焦点：突出显示一个大图片以聚焦，并通过一个小项提供下一个内容的预览。建议用于突出显示您想要强调的内容，例如电影或节目缩略图。
- 全屏：一次显示一个从边缘到边缘的大项，并垂直滚动。建议用于高度大于宽度的内容。
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为图片提供无障碍功能说明。
- 轮播界面的状态使用
package com.wn.androidcomposedemo1.basegoogle
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.remember
import com.wn.androidcomposedemo1.R
import androidx.compose.material3.carousel.HorizontalMultiBrowseCarousel
import androidx.compose.material3.carousel.HorizontalUncontainedCarousel
import androidx.compose.material3.carousel.rememberCarouselState
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import com.wn.androidcomposedemo1.ui.theme.AndroidComposeDemo1Theme
/**
* Author : wn
* Email : maoning20080808@163.com
* Date : 2026/6/22 21:38
* Description : 轮播界面
*/
class CarouselMultiBrowseActivity : ComponentActivity(){
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
AndroidComposeDemo1Theme() {
Surface(
modifier = Modifier.fillMaxSize(),
color = MaterialTheme.colorScheme.background
) {
CarouselExample()
}
}
}
}
@Preview
@Composable
fun CarouselExample(){
Column() {
Spacer(modifier = Modifier.height(20.dp))
Text("多项浏览轮播界面", color = Color.Red)
CarouselMultiBrowseExample()
Spacer(modifier = Modifier.height(20.dp))
Text("无容器轮播界面", color = Color.Blue)
CarouselUncontainedBrowseExample()
}
}
//多项浏览轮播界面
@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun CarouselMultiBrowseExample(){
val items = remember {
listOf(
CarouseItem(0, R.drawable.base_banner0, "图片1"),
CarouseItem(1, R.drawable.base_banner1, "图片2"),
CarouseItem(2, R.drawable.base_banner2, "图片3"),
CarouseItem(3, R.drawable.base_banner3, "图片4"),
CarouseItem(4, R.drawable.base_banner4, "图片5"),
)
}
//不同点
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(200.dp),
painter = painterResource(id = item.imageResId),
contentDescription = item.contentDescription,
contentScale = ContentScale.Crop
)
}
}
//无容器轮播界面
@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun CarouselUncontainedBrowseExample(){
val items = remember {
listOf(
CarouseItem(0, R.drawable.base_banner0, "图片1"),
CarouseItem(1, R.drawable.base_banner1, "图片2"),
CarouseItem(2, R.drawable.base_banner2, "图片3"),
CarouseItem(3, R.drawable.base_banner3, "图片4"),
CarouseItem(4, R.drawable.base_banner4, "图片5"),
)
}
//不同点
HorizontalUncontainedCarousel(
state = rememberCarouselState {items.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 = items[i]
Image(
modifier = Modifier.height(200.dp),
painter = painterResource(id = item.imageResId),
contentDescription = item.contentDescription,
contentScale = ContentScale.Crop
)
}
}
}
data class CarouseItem(
val id : Int,
val imageResId: Int,
val contentDescription : String
)