Carousel 走马灯
uni-appH5微信小程序App
uni-app 跨端走马灯。轮播展示一组内容,支持自动播放、循环、触摸滑动跟手与指示点导航。
何时使用
首页 Banner、图片/卡片轮播、新手引导分页。
何时不使用
内容超过 5 屏或需要标题联动的分页场景,用 Tabs。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
autoplay | number | 0 | 自动播放间隔(毫秒),0 表示不自动播放 |
loop | boolean | true | 循环播放;关闭后播放到末屏停止 |
showArrows | boolean | false | 显示左右切换箭头;移动端无 hover,开启后常显 |
showDots | boolean | true | 显示底部指示点,激活项拉长为胶囊 |
height | string | "200px" | 容器高度 |
initialIndex | number | 0 | 初始显示的屏索引 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
change | number | 切换屏时触发,参数为当前索引 |
Slots
| 名称 | 说明 |
|---|---|
default | 若干屏内容,每个顶层子节点作为一屏(用 <view> 包裹每屏内容) |
Methods
| 名称 | 签名 | 说明 |
|---|---|---|
goTo | goTo(index: number): void | 跳转到指定屏(循环模式自动取模,loop 关闭时 clamp 到边界) |
next | next(): void | 切换到下一屏 |
prev | prev(): void | 切换到上一屏 |
currentIndex | Ref<number> | 当前屏索引的响应式引用(配合 ref 读取) |
示例
基础轮播
vue
<Carousel height="160px">
<view style="height:160px;background:linear-gradient(120deg,#3b6ef6,#06b6d4)" />
<view style="height:160px;background:linear-gradient(120deg,#ff9a62,#f65e8b)" />
<view style="height:160px;background:linear-gradient(120deg,#22a06b,#06b6d4)" />
</Carousel>自动播放
vue
<Carousel height="140px" :autoplay="2500">
<view style="height:140px;background:linear-gradient(120deg,#8b5cf6,#3b6ef6)" />
<view style="height:140px;background:linear-gradient(120deg,#e2a03f,#f65e8b)" />
</Carousel>指定初始页
vue
<Carousel height="140px" :initial-index="1" :loop="false">
<view style="height:140px;background:linear-gradient(120deg,#3b6ef6,#06b6d4)" />
<view style="height:140px;background:linear-gradient(120deg,#ff9a62,#f65e8b)" />
<view style="height:140px;background:linear-gradient(120deg,#22a06b,#06b6d4)" />
</Carousel>