platforms/.agents/skills/arco-design-vue/references/components/data-display/carousel.md

name, description, user-invocable

name	description	user-invocable
arco-vue-carousel	Arco Design Vue 图片轮播 Carousel 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-carousel>`、属性、事件、插槽、示例和实现细节。	false

图片轮播 Carousel

简介

基本用法

基本用法

<template>
  <a-carousel
    :style="{
      width: '600px',
      height: '240px',
    }"
    :default-current="2"
    @change="handleChange"
  >
    <a-carousel-item v-for="image in images">
      <img
        :src="image"
        :style="{
          width: '100%',
        }"
      />
    </a-carousel-item>
  </a-carousel>
</template>

<script>
export default {
  setup() {
    const images = [
      'https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/cd7a1aaea8e1c5e3d26fe2591e561798.png~tplv-uwbnlip3yd-webp.webp',
      'https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/6480dbc69be1b5de95010289787d64f1.png~tplv-uwbnlip3yd-webp.webp',
      'https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/0265a04fddbd77a19602a15d9d55d797.png~tplv-uwbnlip3yd-webp.webp',
    ];
    const handleChange=(value)=>{
      console.log(value)
    }
    return {
      images,
      handleChange
    }
  },
};
</script>

API

<carousel> 属性

参数名	描述	类型	默认值
current (v-model)	当前展示索引	number	-
default-current	当前展示索引	number	1
auto-play	是否自动循环展示，或者传入 { interval: 自动切换的时间间隔(默认: 3000), hoverToPause: 鼠标悬浮时是否暂停自动切换(默认: true) } 进行高级配置	boolean | CarouselAutoPlayConfig	false
move-speed	幻灯片移动速率(ms)	number	500
animation-name	切换动画	'slide' | 'fade' | 'card'	'slide'
trigger	幻灯片切换触发方式, click/hover 指示器	'click' | 'hover'	'click'
direction	幻灯片移动方向	'horizontal' | 'vertical'	'horizontal'
show-arrow	切换箭头显示时机	'always' | 'hover' | 'never'	'always'
arrow-class	切换箭头样式	string	''
indicator-type	指示器类型，可为小方块和小圆点或不显示	'line' | 'dot' | 'slider' | 'never'	'dot'
indicator-position	指示器位置	'bottom' | 'top' | 'left' | 'right' | 'outer'	'bottom'
indicator-class	指示器的样式	string	''

仅列出常用项，低频属性按需查阅官方 API。

<carousel> 事件

事件名	描述	参数
change	幻灯片发生切换时的回调函数	index: number prevIndex: number isManual: boolean

常用模式

• 自动切换：可以通过 autoPlay 设置是否自动切换。可设置 moveSpeed, timingFunc 实现不同切换幻灯片效果。
• 指示器：可以指定指示器类型：dot | line | slider 和位置 left | right | top | bottom | outer。
• 切换方向：默认情况下，direction 为 horizontal。通过设置 direction 为 vertical 来使用垂直方向切换。
• 卡片化：当页面宽度方向空间空余，但高度方向空间多余时，可指定 animation 为 card 使用卡片化风格。
• 渐隐切换：指定 animation 为 fade 使用渐隐切换效果。

最佳实践

• 新代码优先使用 Vue 3、Composition API 和 <script setup lang="ts">。
• 模板属性使用 kebab-case，事件使用 @event-name，插槽使用 #slot-name。
• 不要套用 React 专属 API，例如 JSX children、Component.Sub 或 Form.useForm。
• 数据展示组件只负责呈现，分页、筛选、排序等远程状态放在业务层维护。
• 大数据量场景优先使用组件自带的分页、虚拟滚动或懒加载能力。