> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/carousel.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Carousel 轮播

依次浏览图片或内容。

## 基础用法


计划创作分享

1 / 3

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/carousel/basic.tsx"
import { Carousel } from '@ifhover/leaf-ui';

const slides = [
  { key: 'plan', zh: '计划', en: 'Plan', color: '#edf6ee' },
  { key: 'create', zh: '创作', en: 'Create', color: '#eef3ff' },
  { key: 'share', zh: '分享', en: 'Share', color: '#fff5df' },
];

export function CarouselBasic() {
  return (
    <Carousel aria-label={'项目阶段'}>
      {slides.map((slide) => (
        <div
          key={slide.key}
          style={{
            display: 'grid',
            placeItems: 'center',
            height: 180,
            background: slide.color,
            color: '#24372c',
            fontSize: 24,
          }}
        >
          {slide.zh}
        </div>
      ))}
    </Carousel>
  );
}
```

展开代码

## 自动播放


计划创作分享

1 / 3

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/carousel/basic.tsx"
import { Carousel } from '@ifhover/leaf-ui';

const slides = [
  { key: 'plan', zh: '计划', en: 'Plan', color: '#edf6ee' },
  { key: 'create', zh: '创作', en: 'Create', color: '#eef3ff' },
  { key: 'share', zh: '分享', en: 'Share', color: '#fff5df' },
];

export function CarouselAutoplay() {
  return (
    <Carousel autoplay={5000} arrows={false} aria-label={'精选内容'}>
      {slides.map((slide) => (
        <div
          key={slide.key}
          style={{
            display: 'grid',
            placeItems: 'center',
            height: 150,
            background: slide.color,
            color: '#24372c',
          }}
        >
          {slide.zh}
        </div>
      ))}
    </Carousel>
  );
}
```

展开代码

## CarouselHandle

| 属性         | 类型                        | 默认值 | 说明           |
| ---------- | ------------------------- | --- | ------------ |
| `goTo`     | `(index: number) => void` | —   | 必需。切换到指定的索引。 |
| `next`     | `() => void`              | —   | 必需。切换到下一项。   |
| `previous` | `() => void`              | —   | 必需。切换到上一项。   |

## Carousel API

| 属性                   | 类型                        | 默认值     | 说明                  |
| -------------------- | ------------------------- | ------- | ------------------- |
| `activeIndex`        | `number`                  | —       | 受控的当前幻灯片索引。         |
| `defaultActiveIndex` | `number`                  | `0`     | 初始幻灯片索引。            |
| `onChange`           | `(index: number) => void` | —       | 值发生变化时调用。           |
| `arrows`             | `boolean`                 | `true`  | 显示前后切换按钮。           |
| `dots`               | `boolean`                 | `true`  | 显示幻灯片指示器。           |
| `autoplay`           | `boolean \| number`       | `false` | 启用自动播放；数字表示间隔毫秒数。   |
| `infinite`           | `boolean`                 | `true`  | 允许循环切换。             |
| `pauseOnHover`       | `boolean`                 | `true`  | 鼠标悬停时暂停播放；焦点进入也会暂停。 |

## 类型与交互

组装可复用配置时，可导入对应的属性和数据类型。

```ts
import type { CarouselHandle, CarouselProps } from '@ifhover/leaf-ui';
```

为仅展示图标的操作提供可访问名称。交互控件支持键盘操作，并跟随 ConfigProvider 的主题和减少动画设置。