Carousel

基于 Embla Carousel 的轮播容器,通过组合 CarouselContent、CarouselItem、CarouselDot、CarouselPrevious、CarouselNext 等子组件自由搭建交互样式,支持自动播放等 Embla 插件。

Anatomy

• Carousel轮播根,提供 Embla 上下文与键盘导航
  • CarouselContent内部滚动轨道,渲染所有 CarouselItem
  • CarouselItem单张幻灯片,占满容器宽/高
  • CarouselPrevious上一张按钮(canScrollPrev 为 false 时自动 disabled)
  • CarouselNext下一张按钮(canScrollNext 为 false 时自动 disabled)
  • CarouselDot分页器,点击跳转到对应页;data-state 标记当前激活
• CarouselPlugin内置插件集合,目前提供 Autoplay 自动播放

基本用法

默认横向轮播

循环播放 + 点击指示点切换。

1

2

3

4

<script setup lang="ts">
import { Carousel, CarouselContent, CarouselDot, CarouselItem } from '@tripo3d/design';
</script>

<template>
  <Carousel class="max-w-90 w-full" :opts="{ loop: true }">
    <CarouselContent>
      <CarouselItem v-for="i in 4" :key="i">
        <div class="aspect-2 bg-gray-3 rounded-3 flex items-center justify-center text-4xl text-white font-bold">
          {{ i }}
        </div>
      </CarouselItem>
    </CarouselContent>
    <div class="mt-3 flex items-center justify-center gap-2">
      <CarouselDot class="size-2 rounded-full bg-white-20 data-[state=active]:bg-white transition" />
    </div>
  </Carousel>
</template>

前后翻页按钮

Previous / Next

自带 disabled 逻辑,抵达边界时自动禁用。

1

2

3

<Carousel class="max-w-90 w-full">
  <CarouselContent>
    <CarouselItem v-for="i in 3" :key="i">
      <div class="aspect-2 bg-gray-3 rounded-3 flex items-center justify-center text-4xl text-white font-bold">
        {{ i }}
      </div>
    </CarouselItem>
  </CarouselContent>
  <div class="mt-3 flex items-center justify-center gap-3">
    <CarouselPrevious class="h-8 w-16 rounded-2 bg-gray-4 text-white disabled:opacity-40">
      上一张
    </CarouselPrevious>
    <CarouselNext class="h-8 w-16 rounded-2 bg-gray-4 text-white disabled:opacity-40">
      下一张
    </CarouselNext>
  </div>
</Carousel>

自动播放

CarouselPlugin.Autoplay

通过 Embla 插件实现无人值守的自动切换,配合 loop 可无限滚动。

1

2

3

4

<script setup lang="ts">
import { Carousel, CarouselContent, CarouselDot, CarouselItem, CarouselPlugin } from '@tripo3d/design';
</script>

<template>
  <Carousel
    class="max-w-90 w-full"
    :opts="{ loop: true }"
    :plugins="[CarouselPlugin.Autoplay({ delay: 2000 })]"
  >
    <CarouselContent>
      <CarouselItem v-for="i in 4" :key="i">
        <div class="aspect-2 bg-gray-3 rounded-3 flex items-center justify-center text-4xl text-white font-bold">
          {{ i }}
        </div>
      </CarouselItem>
    </CarouselContent>
    <div class="mt-3 flex items-center justify-center gap-2">
      <CarouselDot class="size-2 rounded-full bg-white-20 data-[state=active]:bg-white" />
    </div>
  </Carousel>
</template>

纵向轮播

orientation="vertical"

切换到垂直滚动方向,需给 Carousel 设置显式高度,CarouselContent 使用 h-full 继承。

1

2

3

4

<Carousel class="w-50 h-60" orientation="vertical" :opts="{ loop: true }">
  <CarouselContent class="h-full">
    <CarouselItem v-for="i in 4" :key="i" class="min-h-0">
      <div class="h-full bg-gray-3 rounded-3 flex items-center justify-center text-4xl text-white font-bold">
        {{ i }}
      </div>
    </CarouselItem>
  </CarouselContent>
</Carousel>

API

Carousel Props

名称	类型	默认值	说明
opts	EmblaCarouselOptions	—	透传给 Embla 的配置,如 loop、align、dragFree 等
orientation	'horizontal' | 'vertical'	'horizontal'	滚动方向
plugins	EmblaPlugin[]	—	插件数组,如 [CarouselPlugin.Autoplay()]
class	string	—	容器 class

Carousel Events

事件	Payload	说明
init-api	(api: CarouselApi)	Embla API 初始化后触发,可拿到原生 api 进行更底层操作

Carousel Expose

字段	类型	说明
carouselApi	Ref<CarouselApi>	Embla 实例
scrollNext	() => void	滚动到下一张
scrollPrev	() => void	滚动到上一张
canScrollNext	Ref<boolean>	是否可以继续下一张(非 loop 模式下边界判定)
canScrollPrev	Ref<boolean>	是否可以继续上一张

CarouselDot Props

名称	类型	默认值	说明
class	string	—	单个指示点的 class;组件会根据当前高亮自动设置 data-state="active"

子组件 Slots

插槽	作用域	说明
default (Carousel)	—	可访问 orientation、scrollNext、scrollPrev、carouselApi 等作用域变量
default (CarouselContent / CarouselItem)	—	自定义幻灯片内容
default (CarouselPrevious / CarouselNext / CarouselDot)	—	按钮内部渲染内容(图标 / 文本)

可访问性

• 根容器带 role="region" 与 aria-roledescription="carousel",并 tabindex="0" 支持键盘聚焦
• 聚焦后可用方向键切换幻灯片(横向为 Left/Right,纵向为 Up/Down)
• CarouselPrevious / CarouselNext 是原生 <button>,在抵达边界时会被自动 disabled,避免无效点击
• CarouselItem 带 role="group" 与 aria-roledescription="slide",便于辅助技术识别