98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
|
---
|
|||
|
|
name: arco-vue-carousel
|
|||
|
|
description: "Arco Design Vue 图片轮播 Carousel 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-carousel>`、属性、事件、插槽、示例和实现细节。"
|
|||
|
|
user-invocable: false
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 图片轮播 Carousel
|
|||
|
|
|
|||
|
|
## 简介
|
|||
|
|
|
|||
|
|
基本用法
|
|||
|
|
|
|||
|
|
## 基本用法
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<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`<br>prevIndex: `number`<br>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`。
|
|||
|
|
- 数据展示组件只负责呈现，分页、筛选、排序等远程状态放在业务层维护。
|
|||
|
|
- 大数据量场景优先使用组件自带的分页、虚拟滚动或懒加载能力。
|