跳到主要内容

Carousel

  • 组件说明：基于 embla-carousel-react 封装的轮播 / 滑块组件，提供声明式的 items API。
  • 交互特征：支持键盘方向键、拖拽切换、横向 / 纵向方向。
  • 实现约定：ui/carousel 保留 embla 的结构骨架，design 层提供声明式的 items API。

基础用法​

传入 items 数组声明每张幻灯片的内容，是最常用的写法。

结果
Loading...
实时编辑器
<Carousel
  items={[
    {
      key: '1',
      content: (
        <div style={{ background: '#f0f0f0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
          Slide 1
        </div>
      ),
    },
    {
      key: '2',
      content: (
        <div style={{ background: '#e8e8e8', borderRadius: 8, padding: 40, textAlign: 'center' }}>
          Slide 2
        </div>
      ),
    },
    {
      key: '3',
      content: (
        <div style={{ background: '#e0e0e0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
          Slide 3
        </div>
      ),
    },
  ]}
/>

一屏多张​

通过 slidesPerView 控制一次可见的幻灯片数量。

结果
Loading...
实时编辑器
<Carousel
  slidesPerView={3}
  items={Array.from({ length: 6 }, (_, i) => ({
    key: i,
    content: (
      <div style={{ background: '#f0f0f0', borderRadius: 8, padding: 24, textAlign: 'center' }}>
        Item {i + 1}
      </div>
    ),
  }))}
/>

隐藏控制按钮​

设置 showControls={false} 可以隐藏左右箭头按钮，适合纯拖拽或自动播放场景。

结果
Loading...
实时编辑器
<Carousel
  showControls={false}
  items={[
    {
      key: '1',
      content: (
        <div style={{ background: '#f0f0f0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
          拖拽切换 1
        </div>
      ),
    },
    {
      key: '2',
      content: (
        <div style={{ background: '#e8e8e8', borderRadius: 8, padding: 40, textAlign: 'center' }}>
          拖拽切换 2
        </div>
      ),
    },
    {
      key: '3',
      content: (
        <div style={{ background: '#e0e0e0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
          拖拽切换 3
        </div>
      ),
    },
  ]}
/>

纵向方向​

设置 orientation="vertical" 切换为纵向轮播。

结果
Loading...
实时编辑器
<div style={{ height: 200 }}>
  <Carousel
    orientation="vertical"
    items={[
      {
        key: '1',
        content: (
          <div style={{ background: '#f0f0f0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
            Vertical 1
          </div>
        ),
      },
      {
        key: '2',
        content: (
          <div style={{ background: '#e8e8e8', borderRadius: 8, padding: 40, textAlign: 'center' }}>
            Vertical 2
          </div>
        ),
      },
      {
        key: '3',
        content: (
          <div style={{ background: '#e0e0e0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
            Vertical 3
          </div>
        ),
      },
    ]}
  />
</div>

自动播放​

设置 autoplay 开启自动切换。传 true 走默认 4 秒间隔，也可以直接传毫秒数。结合 opts={{ loop: true }} 可实现无限循环。

结果
Loading...
实时编辑器
<Carousel
  autoplay={3000}
  opts={{ loop: true }}
  items={Array.from({ length: 5 }, (_, i) => ({
    key: i,
    content: (
      <div style={{ background: '#f0f0f0', borderRadius: 8, padding: 40, textAlign: 'center' }}>
        Slide {i + 1}
      </div>
    ),
  }))}
/>

Props​

Prop类型默认值说明
itemsCarouselItemEntry[]-声明式幻灯片数据
showControlsbooleantrue是否显示左右箭头按钮
slidesPerViewnumber1一次可见的幻灯片数量
autoplayboolean | numberfalse自动切换。true 表示 4000ms，也可传具体毫秒数
prevIconReactNode<ChevronLeftIcon />自定义上一张图标
nextIconReactNode<ChevronRightIcon />自定义下一张图标
orientation'horizontal' | 'vertical''horizontal'滚动方向
optsEmblaCarouselOptions-embla 参数（如 loop、align）
pluginsEmblaCarouselPlugin[]-embla 插件
setApi(api: CarouselApi) => void-接收 carousel API 实例的回调
gapstring-应用到每个 item 的 gap class
contentClassNamestring-内容容器自定义 class
itemClassNamestring-每个 item 的自定义 class
classNamestring-根容器自定义 class

CarouselItemEntry​

字段类型默认值说明
keystring | number-唯一标识
contentReactNode-幻灯片内容
classNamestring-当前 item 的自定义 class