Carousel 走马灯

xy-carousel 提供更适合中后台编排的受控、拖拽、自适应高度和内容流布局能力。适合首页焦点位、图文轮播、活动推荐和运营位展示。

基础用法

最常见的场景是横向焦点图，自动轮播配合指示器展示当前页。

Featured运营焦点位

适合首页 Banner、活动主视觉和公告入口。

Featured版本发布

把新功能和更新日志集中放进一个轮播序列里。

Featured内容推荐

用于推荐专题、精选文章和关键任务入口。

无缝循环边界

普通单页 slide 循环会直接回绕真实索引，并把首尾项重排到相邻轨道，减少切到边界后再“收一下”的感觉。

当前页：边界无缝 1观察末页切回首屏时的位置衔接和进度条重置

Seamless Loop边界无缝 1

自动播放到最后一张后，会直接回到第一张，并保持首尾视觉位置连续。

Seamless Loop边界无缝 2

边界切换不再额外走收尾轨道，而是按真实索引回绕到下一张。

Seamless Loop边界无缝 3

进度条会在切到新一项后重新开始计时，节奏和普通切换保持一致。

两项循环补位

当只有 2 项内容且开启 loop 时，会自动补位成 4 个物理 slide，保持循环切换和指示器索引都更自然。

当前逻辑页：双项循环 A观察只有两项时的循环衔接

Two Items Loop双项循环 A

两项内容开启 loop 后会自动补位，避免来回翻面的生硬感。

Two Items Loop双项循环 B

对外 activeIndex 和 change 事件仍然保持 0 / 1 这组逻辑索引。

Two Items Loop双项循环 A

两项内容开启 loop 后会自动补位，避免来回翻面的生硬感。

Two Items Loop双项循环 B

对外 activeIndex 和 change 事件仍然保持 0 / 1 这组逻辑索引。

指示器与箭头

可以调整箭头显示时机和指示器位置，适合不同密度的轮播位。

outside 指示器 + 常显箭头

Outside 1

Outside 2

Outside 3

纯净模式，无箭头无指示器

Clean 1

Clean 2

Clean 3

受控模式

通过 activeIndex + update:activeIndex 把轮播接进外部状态管理或路由编排。

Page 1

Page 2

Page 3

当前页：2

自适应高度

height='auto' 适合不同内容高度的图文卡片和公告流。

自适应高度 1

当前 slide 会根据内容高度自动调整容器。

自适应高度 2

当前 slide 会根据内容高度自动调整容器。

当前 slide 会根据内容高度自动调整容器。

自适应高度 3

当前 slide 会根据内容高度自动调整容器。

当前 slide 会根据内容高度自动调整容器。

当前 slide 会根据内容高度自动调整容器。

拖拽切换

默认支持鼠标和触摸拖拽切换，适合更自然的运营位浏览体验。

拖拽切换 1

按住并左右拖动即可切换当前页。

拖拽切换 2

按住并左右拖动即可切换当前页。

拖拽切换 3

按住并左右拖动即可切换当前页。

垂直方向

纵向走马灯适合公告流、更新日志和步骤式提示。

Step 1纵向公告流 1

适合发布记录、升级提醒和时间线式内容。

Step 2纵向公告流 2

适合发布记录、升级提醒和时间线式内容。

Step 3纵向公告流 3

适合发布记录、升级提醒和时间线式内容。

卡片模式

type="card" 适合推荐位和内容流预览，支持点击左右卡片切换。

Pick 1推荐位 1

点击左右卡片可以直接切换当前内容。

Pick 2推荐位 2

点击左右卡片可以直接切换当前内容。

Pick 3推荐位 3

点击左右卡片可以直接切换当前内容。

Pick 4推荐位 4

点击左右卡片可以直接切换当前内容。

Pick 5推荐位 5

点击左右卡片可以直接切换当前内容。

内容流布局

slidesPerView / slidesPerGroup / gap / centered 适合露出下一张和多卡并列的内容流轮播。

Flow 1内容流 1

Flow 2内容流 2

Flow 3内容流 3

Flow 4内容流 4

Flow 5内容流 5

Fade 动画

effect='fade' 适合 Hero Banner 和强视觉海报切换。

Fade 1

Fade 2

Fade 3

缩略图联动

thumbs 适合图库详情、商品图和媒体预览场景。

Ocean

Aurora

Sunset

Forest

自动播放进度条

show-progress 可以让用户感知自动播放节奏。

Progress 1

Progress 2

Progress 3

自定义控制区

通过 indicator / arrow-prev / arrow-next / progress 插槽，可以把控制区改成更贴业务的样式。

Custom 1

Custom 2

Custom 3

单项播放节奏

CarouselItem.duration 和 autoplayDisabled 适合运营位混排场景。

Duration 1

Duration 2

Duration 3

手动切换页

Lazy 渲染

lazy 适合内容较重、图片较多，但总量还不算特别大的轮播序列。

Lazy 1

Lazy 2

Lazy 3

Lazy 4

Lazy 5

Lazy 6

Virtual 窗口化

virtual 适合数量更多的轮播序列，只保留当前窗口附近内容。

Virtual 1

Virtual 2

Virtual 3

Virtual 4

Virtual 5

Virtual 6

Virtual 7

Virtual 8

Virtual 9

Virtual 10

Virtual 11

Virtual 12

图库场景

主轮播 + 缩略图条是图库和商品图详情页最常见的轮播形态。

封面 1

封面 2

封面 3

封面 4

方法控制

通过 expose 的 prev / next / setActiveItem / activeIndex，可以把走马灯接进更复杂的运营编排流程。

A

B

C

当前索引：0

使用提示

• effect='fade' 只在普通单页模式下生效；当 type='card'、slides-per-view > 1 或 centered 开启时，会自动回退为普通滑动。
• type='card' 是独立模式，不与 slides-per-view / slides-per-group / gap / centered 这类内容流布局能力混用。
• 普通单页 slide 且 loop=true 时，首尾切换会直接回绕真实索引，并通过 slide 重排保持首尾衔接更连续。
• 当只有 2 项内容且 loop=true 时，会自动补位为 4 个物理 slide；对外暴露的 activeIndex、change 和 update:activeIndex 仍然保持 0 / 1 这组逻辑索引。
• height='auto' 配合 virtual 且一屏展示多项时，会退回按当前激活项测量高度，避免窗口化场景的高度抖动。
• 自动播放除了受 pause-on-hover 控制外，在焦点进入轮播区和拖拽过程中也会暂停，交互结束后再恢复计时。
• 开启 show-progress 时，自动播放切换到下一项后会立即按新一轮节奏重新计时。
• 开启 keyboard 后，横向支持 Left / Right，纵向支持 Up / Down，同时支持 Home / End 快速跳到首尾。

API

Carousel Attributes

属性	说明	类型	默认值
initial-index	初始激活项索引	number	0
active-index	当前激活项索引（受控）	number	—
height	走马灯高度	string	''
trigger	指示器触发方式	CarouselTrigger	'hover'
autoplay	是否自动播放	boolean	true
interval	自动播放间隔	number	3000
indicator-position	指示器位置	CarouselIndicatorPosition	''
arrow	箭头显示时机	CarouselArrow	'hover'
type	走马灯类型	CarouselType	''
card-scale	卡片模式缩放比例	number	0.83
loop	是否循环显示	boolean	true
direction	展示方向	CarouselDirection	'horizontal'
pause-on-hover	鼠标移入时是否暂停	boolean	true
draggable	是否支持拖拽切换	boolean	true
effect	动画效果	CarouselEffect	'slide'
duration	动画时长	number	400
easing	动画缓动函数	string	cubic-bezier(0.22, 0.61, 0.36, 1)
slides-per-view	可视 slide 数量	number	1
slides-per-group	每次翻页数量	number	1
gap	slide 间距	number | string	0
centered	是否居中当前页	boolean	false
indicator-type	指示器样式	CarouselIndicatorType	line
thumbs	是否显示缩略图条	boolean	false
thumbs-placement	缩略图条位置	CarouselThumbPlacement	'bottom'
thumbs-per-view	缩略图条每屏可见数量	number	5
thumbs-gap	缩略图间距	number | string	8
thumbs-indicator-type	缩略图样式	CarouselThumbIndicatorType	'thumbnail'
show-progress	是否显示自动播放进度	boolean	false
progress-placement	进度条位置	CarouselProgressPlacement	'bottom'
progress-color	进度条颜色	string	''
align	内容流对齐方式	CarouselAlignment	'start'
contain-scroll	内容流边界策略	CarouselContainScroll	'trim'
peek	露出边缘尺寸	number | string	0
lazy	是否启用邻近懒渲染	boolean	false
lazy-range	邻近懒渲染范围	number	1
virtual	是否启用窗口化渲染	boolean	false
virtual-buffer	窗口化缓冲范围	number	1
aria-label	无障碍标签	string	''
keyboard	是否启用键盘切换	boolean	true

Carousel Events

事件	说明	参数
update:activeIndex	受控模式下当前页变更	CarouselActiveIndexChangeHandler
change	当前激活项切换时触发	CarouselChangeHandler

Carousel Exposes

暴露项	说明	类型
activeIndex	当前激活项索引	CarouselInstance["activeIndex"]
setActiveItem	手动切换到指定项	CarouselInstance["setActiveItem"]
prev	切换到上一项	CarouselInstance["prev"]
next	切换到下一项	CarouselInstance["next"]

CarouselItem Attributes

属性	说明	类型	默认值
name	项目名称，可用于 setActiveItem	string	''
label	指示器文案	string | number	''
duration	单项自动播放时长（毫秒），可覆盖全局 interval	number	—
autoplay-disabled	是否跳过自动播放序列，手动切换仍可进入	boolean	false

Carousel Slots

插槽	说明
default	轮播项列表，通常传入 xy-carousel-item
indicator	自定义指示器，接收 CarouselIndicatorSlotProps
arrow-prev	自定义上一页箭头，接收 CarouselArrowSlotProps
arrow-next	自定义下一页箭头，接收 CarouselArrowSlotProps
progress	自定义进度条，接收 CarouselProgressSlotProps
thumb	自定义缩略图项，接收 CarouselThumbSlotProps