Carousel 轮播图

轮播图组件用于循环展示图片或内容块，支持滑动和淡入淡出两种动画效果。

基础用法

通过 items 传入数据源，v-model 双向绑定当前索引。默认使用滑动（slide）动画，支持键盘 ← → 方向键切换。

<script setup>
const slideItems = [
  { image: 'https://picsum.photos/seed/car1/800/400', title: 'Slide 1' },
  { image: 'https://picsum.photos/seed/car2/800/400', title: 'Slide 2' },
  { image: 'https://picsum.photos/seed/car3/800/400', title: 'Slide 3' },
]
</script>

<template>
  <TCarousel :items="slideItems" />
</template>

淡入淡出

设置 animation="fade" 切换为淡入淡出效果。

<TCarousel :items="slideItems" animation="fade" />

圆点指示器

设置 indicator-style="dot" 使用圆点样式的指示器替代默认横条。

<TCarousel :items="slideItems" indicator-style="dot" />

缩略图指示器

设置 indicator-style="thumb" 使用图片缩略图作为指示器。

<TCarousel :items="slideItems" indicator-style="thumb" />

垂直指示器

设置 vertical-indicators 将指示器垂直放置在轮播图右侧。

<TCarousel :items="slideItems" vertical-indicators />

图片 + 遮罩 + 字幕

图片模式下开启 caption-background，字幕区域获得半透明深色衬底，文字更清晰易读。

<TCarousel :items="slideItems" :show-captions="true" :caption-background="true" caption-always />

纯色背景

数据项中使用 bgColor 字段替代 image，展示纯色背景轮播，适合无图片场景。

<TCarousel :items="[
  { bgColor: '#4299e1', title: 'Blue Slide' },
  { bgColor: '#48bb78', title: 'Green Slide' },
  { bgColor: '#ed8936', title: 'Orange Slide' },
]" :show-captions="true" :caption-background="true" caption-always />

点击事件

点击幻灯片触发 @clickItem 事件，回调参数为当前项对象和索引。

<TCarousel :items="slideItems" @click-item="onSlideClick" />

<script setup>
function onSlideClick(item, index) {
  console.log('Clicked:', item, index)
}
</script>

自定义指示器与控件

通过 #indicators 和 #controls 作用域插槽可以完全自定义底部指示器和控制按钮的 UI。

<TCarousel :items="slideItems" :indicators="false" :controls="false">
  <template #indicators="{ current, total }">
    <div class="text-center">
      <span class="badge">{{ current + 1 }} / {{ total }}</span>
    </div>
  </template>
  <template #controls="{ prev, next }">
    <button @click="prev">‹ 上一张</button>
    <button @click="next">下一张 ›</button>
  </template>
</TCarousel>

API

Props

Prop	说明	类型	默认值
items	轮播数据项数组	CarouselItem[]	undefined
v-model	当前激活索引	number	0
interval	自动播放间隔（毫秒），设为 0 禁用	number	5000
animation	动画类型	'slide' | 'fade'	'slide'
indicators	显示底部指示器	boolean	true
indicatorStyle	指示器样式	'default' | 'dot' | 'thumb'	'default'
verticalIndicators	指示器垂直排布（右侧）	boolean	false
controls	显示左右控制按钮	boolean	true
pauseOnHover	悬停时暂停自动播放	boolean	true
wrap	是否循环播放	boolean	true
showCaptions	显示标题与描述	boolean	false
captionAlways	始终显示字幕（小屏不隐藏）	boolean	false
captionBackground	为字幕添加深色背景遮罩	boolean	false
dark	暗色模式（控制按钮适配深色背景）	boolean	false
height	固定高度	string	undefined
ariaLabel	无障碍标签	string	'Carousel'

CarouselItem

字段	说明	类型	默认值
image	图片地址	string	undefined
title	标题	string	undefined
description	描述	string	undefined
bgColor	背景色（无图片时显示）	string	undefined
html	自定义 HTML 内容	string	undefined

Events

事件	说明	参数
change	切换幻灯片时触发	index: number
clickItem	点击幻灯片时触发	(item: CarouselItem, index: number)

Slots

插槽	作用域属性	说明
indicators	current: number, total: number, goTo: (index) => void	自定义底部指示器
controls	prev: () => void, next: () => void, current: number, total: number	自定义左右控制按钮

键盘导航

组件支持键盘无障碍操作：聚焦后按 ←（左箭头）切换到上一张，按 →（右箭头）切换到下一张。