Carousel 轮播图

一组内容（图片、卡片、公告等）循环轮播展示，支持自动播放、淡入淡出、指示点与箭头切换。

导入

import { Carousel } from "@reglow/reui";

何时使用

当有一组平级的内容（图片、卡片、公告等）需要轮播展示时。
当需要自动播放或让用户手动切换（指示点 / 箭头 / 拖拽 / 键盘）时。
当需要首尾无缝循环，或容器高度随当前内容自适应时。

代码演示

基础用法

默认插槽的每个直接子节点即一张幻灯片，默认显示指示点、无限循环。

<script setup lang="ts">
import { Carousel } from "@reglow/reui";
</script>

<template>
  <Carousel dots class="h-[200px] overflow-hidden rounded-lg">
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      1
    </div>
    <div class="flex h-full items-center justify-center bg-accent text-lg font-medium">
      2
    </div>
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      3
    </div>
    <div class="flex h-full items-center justify-center bg-accent text-lg font-medium">
      4
    </div>
  </Carousel>
</template>

自动播放

autoplay 开启自动播放，autoplaySpeed 控制切换间隔（毫秒，默认 3000）；鼠标悬浮时自动暂停。

<script setup lang="ts">
import { Carousel } from "@reglow/reui";
</script>

<template>
  <Carousel autoplay :autoplay-speed="2000" class="h-[200px] overflow-hidden rounded-lg">
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      1
    </div>
    <div class="flex h-full items-center justify-center bg-accent text-lg font-medium">
      2
    </div>
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      3
    </div>
  </Carousel>
</template>

淡入淡出

effect="fade" 使用淡入淡出切换（默认为 scrollx 水平滑动），speed 控制动画时长（毫秒）。

<script setup lang="ts">
import { Carousel } from "@reglow/reui";
</script>

<template>
  <Carousel effect="fade" :speed="800" class="h-[200px] overflow-hidden rounded-lg">
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      1
    </div>
    <div class="flex h-full items-center justify-center bg-accent text-lg font-medium">
      2
    </div>
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      3
    </div>
  </Carousel>
</template>

指示点位置

dotPosition 控制指示点位置：top / bottom / left / right，默认 bottom；左右位置时指示点竖排。设置 dots 为 false 可隐藏指示点。

<template>
  <!-- 指示点在上方 -->
  <Carousel dot-position="top" class="h-[160px] overflow-hidden rounded-lg border">
    <div class="flex h-full items-center justify-center bg-muted">1</div>
    <div class="flex h-full items-center justify-center bg-accent">2</div>
    <div class="flex h-full items-center justify-center bg-muted">3</div>
  </Carousel>

  <!-- 指示点在下方（默认） -->
  <Carousel dot-position="bottom" class="h-[160px] overflow-hidden rounded-lg border">
    <div class="flex h-full items-center justify-center bg-muted">1</div>
    <div class="flex h-full items-center justify-center bg-accent">2</div>
    <div class="flex h-full items-center justify-center bg-muted">3</div>
  </Carousel>

  <!-- 指示点在左侧（竖排） -->
  <Carousel dot-position="left" class="h-[160px] overflow-hidden rounded-lg border">
    <div class="flex h-full items-center justify-center bg-muted">1</div>
    <div class="flex h-full items-center justify-center bg-accent">2</div>
    <div class="flex h-full items-center justify-center bg-muted">3</div>
  </Carousel>

  <!-- 指示点在右侧（竖排） -->
  <Carousel dot-position="right" class="h-[160px] overflow-hidden rounded-lg border">
    <div class="flex h-full items-center justify-center bg-muted">1</div>
    <div class="flex h-full items-center justify-center bg-accent">2</div>
    <div class="flex h-full items-center justify-center bg-muted">3</div>
  </Carousel>

  <!-- 隐藏指示点 -->
  <Carousel :dots="false" class="h-[160px] overflow-hidden rounded-lg border">
    <div class="flex h-full items-center justify-center bg-muted">1</div>
    <div class="flex h-full items-center justify-center bg-accent">2</div>
    <div class="flex h-full items-center justify-center bg-muted">3</div>
  </Carousel>
</template>

切换箭头

arrows 为 true 时显示切换箭头；指示点竖排（left / right）时自动切换为上下箭头。

<script setup lang="ts">
import { h } from "vue";
import { ArrowBigLeft, ArrowBigRight } from "lucide-vue-next";
import { Carousel } from "@reglow/reui";

// 传入对象自定义箭头节点
const arrows = {
  prev: h(ArrowBigLeft, { class: "size-4" }),
  next: h(ArrowBigRight, { class: "size-4" }),
};
</script>

<template>
  <Carousel :arrows="arrows" class="h-[200px] overflow-hidden rounded-lg">
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      1
    </div>
    <div class="flex h-full items-center justify-center bg-accent text-lg font-medium">
      2
    </div>
    <div class="flex h-full items-center justify-center bg-muted text-lg font-medium">
      3
    </div>
  </Carousel>
</template>

也可以用 prev / next 插槽自定义箭头内容（插槽优先级低于 arrows 对象形式）：

<template>
  <Carousel arrows class="h-[200px]">
    <template #prev>
      <ArrowBigLeft class="size-4" />
    </template>
    <template #next>
      <ArrowBigRight class="size-4" />
    </template>

    <div class="flex h-full items-center justify-center bg-muted">1</div>
    <div class="flex h-full items-center justify-center bg-accent">2</div>
    <div class="flex h-full items-center justify-center bg-muted">3</div>
  </Carousel>
</template>

API

Carousel Props

参数	说明	类型	默认值
autoplay	是否自动播放	`boolean`	`false`
autoplaySpeed	自动播放间隔，单位毫秒	`number`	`3000`
dotPosition	指示点位置	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`
dots	是否显示指示点，或指示点容器配置	`boolean \| { className?: string }`	`true`
arrows	是否显示切换箭头，或自定义箭头节点	`boolean \| { prev?: VNode; next?: VNode }`	`false`
effect	切换效果	`"scrollx" \| "fade"`	`"scrollx"`
speed	切换动画时长，单位毫秒	`number`	`500`
easing	切换动画缓动函数，为空时使用内置缓动	`string`	`""`
infinite	是否无限循环	`boolean`	`true`
draggable	是否可拖拽切换	`boolean`	`false`
initialSlide	初始幻灯片下标（从 0 开始）	`number`	`0`
waitForAnimate	切换动画进行中是否忽略新的切换请求	`boolean`	`true`
adaptiveHeight	容器高度是否随当前幻灯片自适应	`boolean`	`false`
class	附加类名	`string`	-
style	附加样式	`CSSProperties`	-

Carousel Events

事件	说明	回调参数
beforeChange	切换开始前触发	`(from: number, to: number) => void`
change	切换完成后触发	`(current: number, prev: number) => void`
click	点击幻灯片时触发	`(index: number, e: MouseEvent) => void`

Carousel 方法

通过 ref 获取组件实例后调用：

方法	说明	签名
goTo	切换到指定幻灯片，`dontAnimate` 为真时不播放动画	`(index: number, dontAnimate?: boolean) => void`
next	切换到下一张	`() => void`
prev	切换到上一张	`() => void`
current	当前幻灯片下标（从 0 开始）	`readonly current: number`

import type { CarouselExpose } from "@reglow/reui";

Carousel Slots

名称	说明
default	幻灯片内容，每个直接子节点为一张幻灯片
prev	自定义「上一张」按钮内容（优先级低于 `arrows` 对象形式）
next	自定义「下一张」按钮内容（优先级低于 `arrows` 对象形式）

与 antd 的差异

说明：无限循环通过「首尾克隆 + 过渡结束后无动画回跳」实现，infinite=false 时到边界不越界。

说明：组件尊重 prefers-reduced-motion: reduce，此时关闭切换过渡动画；键盘方向键（左右 / 上下）可直接切换，无需额外配置。

Card 卡片

Chart 图表

基于 Unovis 的图表组件，涵盖面积 / 柱状 / 折线 / 环图等常规图表，以及漏斗、仪表盘、雷达、迷你图等扩展类型

内容锚点

导入
何时使用
代码演示
API