在 Android 传统 View 体系里，轮播图通常要把 ViewPager 或 ViewPager2、定时器和手势处理拼在一起，代码不算复杂，但零散且不够直观。到了 Jetpack Compose，这件事可以收敛到 HorizontalPager、状态管理和协程三个核心点上：先搭出可滑动的基础版本，再补上自动轮播、伪无限循环、拖拽暂停和指示器，最后封装成一个页面里能直接复用的组件。
为什么现在直接用 HorizontalPager
如果你现在准备在 Compose 里做轮播图，首先要确认 API 选型。自 Compose 1.4.0（BOM 2023.03.00）起，Pager 相关 API 已经从 Accompanist 正式迁移到 androidx.compose.foundation.pager，也就是说，这类场景已经可以直接依赖官方基础库，不必再额外引入第三方实现。
基础依赖
确保你的 build.gradle 中使用了较新的 Compose Foundation 版本：
implementation("androidx.compose.foundation:foundation:1.6.0") // 或更高版本
这个前提很关键：后文的 HorizontalPager、rememberPagerState 等 API 都建立在官方 Pager 之上。
先做一个最基础的轮播图
完整功能往往建立在一个简单可运行的骨架上。最基础的版本只需要两件事：一是根据数据数量创建 PagerState，二是在 HorizontalPager 里按页渲染内容。下面这个例子用颜色块代替图片，方便先验证滑动行为本身。
@Composable
fun SimpleCarousel(
imageUrls: List,
modifier: Modifier = Modifier
) {
val pagerState = rememberPagerState(pageCount = { imageUrls.size })
HorizontalPager(
state = pagerState,
modifier = modifier.fillMaxWidth().height(200.dp)
) { page ->
// 这里可以使用 Coil 或 Glide 加载图片
// AsyncImage(model = imageUrls[page], ...)
Box(
modifier = Modifier
.fillMaxSize()
.background(if (page % 2 == 0) Color.Blue else Color.Red),
contentAlignment = Alignment.Center
) {
Text(text = "Page $page", color = Color.White)
}
}
}
如果只是展示几张静态 Banner，这个版本已经能满足基本横向滑动需求。但要做线上常见的首页轮播区，还需要继续补齐交互和状态逻辑。
一个可用轮播组件需要补哪些能力
真正能落地的轮播图，通常不只要求“能滑”。常见需求一般集中在下面四项：
- 自动轮播：每隔几秒自动切到下一页。
- 无限循环：滑到最后一张后还能连续浏览，不出现明显边界。
- 指示器：用户能知道当前停留在哪一页。
- 交互优化：用户手指拖拽时暂停自动轮播，避免和手势抢控制权。
这四项里，最核心的是“伪无限循环”和“自动轮播暂停恢复”，因为它们决定了组件的体验是否自然。
伪无限循环怎么实现
Compose 里常见的做法不是复制数据集，而是把 pageCount 设成一个足够大的值，例如 Int.MAX_VALUE，再通过取模把页码映射回真实数据索引。
// 实际数据索引 = pageIndex % list.size
val actualIndex = page % imageUrls.size
这样做的好处是，用户看到的是一个几乎没有边界的 Pager，而业务层仍然只维护原始列表。为了保证一进入页面就能左右双向滑动，初始页通常不会从 0 开始，而是放在一个中间位置。
自动轮播与拖拽暂停怎么配合
自动轮播可以交给 LaunchedEffect 和协程 delay 处理；拖拽暂停则需要监听用户当前是否正在操作 Pager。这里可以使用 PagerState 提供的 isScrollInProgress，或者更直接地通过 collectIsDraggedAsState() 感知拖拽状态。
实现思路很简单：当用户开始拖拽时，自动轮播协程取消；拖拽结束后，再重新启动定时逻辑。这样不会出现“用户刚拖到一半，组件自己又跳页”的问题。
完整 BannerCarousel 组件实现
下面这份代码把前面的几个关键点合并成一个可复用组件：空数据直接返回；大页数配合取模实现伪无限循环；通过 interactionSource 监听拖拽；使用 LaunchedEffect 驱动自动轮播；最后在底部绘制指示器。
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.background
import androidx.compose.foundation.interaction.collectIsDraggedAsState
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.pager.HorizontalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
@OptIn(ExperimentalFoundationApi::class)
@Composable
fun BannerCarousel(
dataList: List, // 这里可以是任意数据模型
modifier: Modifier = Modifier,
autoScrollDelay: Long = 3000L,
content: @Composable (String) -> Unit // 自定义 Item 内容
) {
if (dataList.isEmpty()) return
// 1. 设置一个超大的页数来实现伪无限循环
// 初始页面定在中间某个位置，保证左右都能滑
val initialPage = Int.MAX_VALUE / 2
// 修正初始页，使其对应数据列表的第一个元素 (index 0)
val startIndex = initialPage - (initialPage % dataList.size)
val pagerState = rememberPagerState(
initialPage = startIndex,
pageCount = { Int.MAX_VALUE }
)
// 2. 监听用户是否正在拖拽
val isDragged by pagerState.interactionSource.collectIsDraggedAsState()
// 3. 自动轮播逻辑
// 当 isDragged 为 true 时，Key 发生变化，LaunchedEffect 重启/取消
// 这里利用 isDragged 作为 key，当用户拖拽时，自动轮播协程会被取消；停止拖拽后重新开始
LaunchedEffect(isDragged) {
if (!isDragged) {
while (true) {
delay(autoScrollDelay)
try {
pagerState.animateScrollToPage(pagerState.currentPage + 1)
} catch (e: Exception) {
// 忽略异常或处理页面销毁时的取消异常
}
}
}
}
Box(modifier = modifier) {
// 4. 轮播主体
HorizontalPager(
state = pagerState,
modifier = Modifier.fillMaxSize()
) { pageIndex ->
// 使用取模运算获取实际的数据索引
val actualIndex = pageIndex % dataList.size
content(dataList[actualIndex])
}
// 5. 指示器 (Indicator)
Row(
modifier = Modifier
.align(Alignment.BottomCenter)
.padding(bottom = 16.dp),
horizontalArrangement = Arrangement.spacedBy(8.dp)
) {
val currentActualIndex = pagerState.currentPage % dataList.size
repeat(dataList.size) { index ->
val isSelected = currentActualIndex == index
Box(
modifier = Modifier
.size(if (isSelected) 8.dp else 6.dp)
.clip(CircleShape)
.background(if (isSelected) Color.White else Color.White.copy(alpha = 0.5f))
)
}
}
}
}
这份实现里值得注意的细节
有几个实现点值得单独拎出来看：
if (dataList.isEmpty()) return：先挡住空列表，避免后续取模时报错。initialPage = Int.MAX_VALUE / 2：给左右滑动预留空间，避免一打开就在边界。startIndex = initialPage - (initialPage % dataList.size)：把初始页修正到真实数据的第一个元素上。autoScrollDelay: Long = 3000L：轮播间隔可配置，默认是3000毫秒。currentPage % dataList.size：指示器和内容展示都要基于真实索引，而不是超大页码本身。
这几个细节处理好后，组件的行为会稳定很多，尤其是在初次进入页面和用户频繁拖拽时。
页面中怎么调用这个组件
封装完成后，页面层只需要准备数据并传入内容渲染方式即可。下面是一个直接可用的调用示例：
@Composable
fun HomeScreen() {
val banners = listOf(
"https://example.com/1.jpg",
"https://example.com/2.jpg",
"https://example.com/3.jpg"
)
BannerCarousel(
dataList = banners,
modifier = Modifier
.fillMaxWidth()
.height(200.dp)
) { imageUrl ->
// 这里展示具体的图片内容
// 示例：使用 Coil 加载
/*
AsyncImage(
model = imageUrl,
contentDescription = null,
contentScale = ContentScale.Crop,
modifier = Modifier.fillMaxSize()
)
*/
// 演示用的占位符
Box(
modifier = Modifier
.fillMaxSize()
.background(Color.Gray),
contentAlignment = Alignment.Center
) {
Text("Image: $imageUrl")
}
}
}
实际项目里，这里的 content 通常会接上图片加载组件，例如文中提到的 Coil。这样做的好处是，轮播逻辑和内容展示彻底解耦，后续无论你要展示图片、卡片还是运营位，都不需要改动核心组件。
实现思路总结
用 Jetpack Compose 做轮播图，关键不在于代码量，而在于把几个状态点理顺：
- HorizontalPager 负责横向分页的基础滑动能力。
- Int.MAX_VALUE + 取模 用来实现伪无限循环。
- LaunchedEffect + delay 负责自动轮播的定时推进。
- interactionSource 用来监听拖拽状态，控制自动轮播暂停与恢复。
如果你需要的是一个适合首页 Banner、专题入口或活动位的通用轮播组件，这套实现已经具备比较完整的基础能力，而且依赖的都是 Compose 官方能力，后续维护成本也相对可控。
