图片轮播 Carousel

用于展示多张图片、视频或内嵌框架等内容的循环播放，支持系统自动播放或用户手动切换。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

基础用法：最基本的使用
自动切换：可以通过 autoPlay 设置是否自动切换。可设置 moveSpeed, timingFunc 实现不同切换幻灯片效果。
指示器：可以指定指示器类型：dot | line | slider 和位置 left | right | top | bottom | outer。
切换方向：默认情况下，direction 为 horizontal。通过设置 direction 为 vertical 来使用垂直方向切换。
卡片化：当页面宽度方向空间空余，但高度方向空间多余时，可指定 animation 为 card 使用卡片化风格。
纵向卡片：当使用纵向卡片卡片时，需要手动指定容器的宽高来撑起空间，容器高度可以指定为 图片高度 * 1.5。在此模式下需要同时设定 indicatorPosition="outer-right"。
渐隐切换：指定 animation 为 fade 使用渐隐切换效果。
自定义子元素：因为动画是通过 CSS 实现，所以当使用自定义组件作为Carousel的子元素时，自定义组件需要支持style和className两个属性。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

Carousel

参数名	描述	类型	默认值	版本
miniRender	是否仅渲染满足动画效果的最少数量的 children	boolean	`-`	2.21.0
currentIndex	当前展示索引	number	`0`	-
moveSpeed	幻灯片移动速率(ms)	number	`500`	-
timingFunc	过渡速度曲线, 默认匀速 transition-timing-function	string	`cubic-bezier(0.34, 0.69, 0.1, 1)`	-
animation	切换动画	'slide' \| 'card' \| 'fade'	`slide`	-
direction	幻灯片移动方向	'horizontal' \| 'vertical'	`horizontal`	-
indicatorPosition	指示器位置	'bottom' \| 'top' \| 'left' \| 'right' \| 'outer' \| 'outer-right'	`bottom`	-
indicatorType	指示器类型，可为小方块和小圆点或不显示	'line' \| 'dot' \| 'slider' \| 'never'	`dot`	-
showArrow	切换箭头显示时机	'always' \| 'hover' \| 'never'	`always`	-
trigger	幻灯片切换触发方式, click/hover 指示器	'click' \| 'hover'	`click`	-
arrowClassName	切换箭头样式	string \| string[]	`-`	-
autoPlay	是否自动循环展示，或者传入 `{ interval: 自动切换的时间间隔(默认: 3000), hoverToPause: 鼠标悬浮时是否暂停自动切换(默认: true) }` 进行高级配置 (`2.14.0` 支持传入对象)	boolean \| { interval?: number; hoverToPause?: boolean }	`-`	-
carousel	用于获得带有 API 方法的 Carousel 引用。	MutableRefObject<CarouselHandle>	`-`	2.16.1
className	节点类名	string \| string[]	`-`	-
icons	自定义图标	{prev?: ReactNode;next?: ReactNode;}	`-`	2.25.0
indicatorClassName	指示器的样式	string \| string[]	`-`	-
style	节点样式	CSSProperties	`-`	-
onChange	幻灯片发生切换时的回调函数。	(index: number, prevIndex: number, isManual: boolean) => void	`-`	`isManual` in 2.4.0

CarouselHandle

export type CarouselHandle = {
  dom: HTMLElement;
  goto: (options: {
    /** 目标索引 */
    index: number;
    /** 是否为逆向 */
    isNegative?: boolean;
    /** 是否由用户触发，将决定 onChange 回调的第三个参数 */
    isManual?: boolean;
    /** 是否重置自动播放的 interval */
    resetAutoPlayInterval?: boolean;
  }) => void;
};

常见问题

动画结束后闪动

如果子元素是透明的，Carousel 翻页完成之后可能出现由于浏览器渲染导致的闪动问题，此时可以尝试为子元素添加背景色解决。参考此 ISSUE。