@fish-render/carousel/README.md

Fish Render carousel component for Vue 3

# Fish Render Carousel

一个功能丰富的 Vue 3 轮播图组件，支持自动播放、指示器、导航按钮和响应式高度。

## 特性

- 🎯 **自动播放** - 支持自动轮播，可配置播放间隔
- 🎮 **交互控制** - 支持点击指示器和导航按钮
- 🔄 **无限循环** - 支持无限循环模式
- 📱 **响应式设计** - 支持响应式高度配置
- 🎨 **自定义样式** - 灵活的样式定制选项
- ⚡ **高性能** - 使用 CSS 变量和媒体查询，支持 SSR

## 安装

```bash
npm install @fish-render/carousel
```

## 基础用法

```vue
<template>
  <Carousel :autoplay="true" :interval="3000" indicator-position="outside">
    <CarouselItem>
      <div class="slide">
        <h3>第一张幻灯片</h3>
        <p>这是第一张幻灯片的内容</p>
      </div>
    </CarouselItem>
    <CarouselItem>
      <div class="slide">
        <h3>第二张幻灯片</h3>
        <p>这是第二张幻灯片的内容</p>
      </div>
    </CarouselItem>
  </Carousel>
</template>

<script setup>
import { Carousel, CarouselItem } from '@fish-render/carousel'
</script>
```

## 高度配置

### 固定高度

```vue
<Carousel :height="300">
  <!-- 轮播项 -->
</Carousel>
```

### 字符串高度

```vue
<Carousel height="50vh">
  <!-- 轮播项 -->
</Carousel>
```

### 响应式高度

```vue
<Carousel
  :height="{
    xs: 200, // < 640px
    sm: 300, // ≥ 640px
    md: 400, // ≥ 768px
    lg: 500, // ≥ 1024px
    xl: 600, // ≥ 1280px
  }"
>
  <!-- 轮播项 -->
</Carousel>
```

## API

### Carousel Props

| 参数              | 说明                                       | 类型                            | 默认值   |
| ----------------- | ------------------------------------------ | ------------------------------- | -------- |
| autoplay          | 是否自动播放                               | boolean                         | true     |
| interval          | 自动播放间隔时间（毫秒）                   | number                          | 3000     |
| indicatorPosition | 指示器位置                                 | 'outside' \| 'inside' \| 'none' | 'inside' |
| loop              | 是否启用无限循环模式                       | boolean                         | true     |
| height            | 轮播图高度，支持固定值、字符串或响应式对象 | string \| number \| object      | -        |

### 响应式断点

- **xs**: < 640px
- **sm**: ≥ 640px
- **md**: ≥ 768px
- **lg**: ≥ 1024px
- **xl**: ≥ 1280px

## 服务端渲染支持

组件使用 CSS 变量和媒体查询实现响应式高度，完全支持服务端渲染（SSR）。无需 JavaScript 计算，性能优异。

### SSR 兼容性

组件已针对 SSR 环境进行了优化，支持在 Nuxt 3/4 项目中使用：

```vue
<template>
  <ClientOnly>
    <Carousel :autoplay="true" :interval="3000">
      <CarouselItem>
        <div>内容 1</div>
      </CarouselItem>
      <CarouselItem>
        <div>内容 2</div>
      </CarouselItem>
    </Carousel>
  </ClientOnly>
</template>
```

**注意：** 建议使用 `<ClientOnly>` 包装组件，以确保自动播放功能正常工作。

## 样式定制

组件提供了丰富的 CSS 类名，方便自定义样式：

```css
.fish-carousel {
  /* 轮播容器 */
}

.fish-carousel__container {
  /* 轮播内容容器 */
}

.fish-carousel-item-wrapper {
  /* 轮播项包装器 */
}

.fish-carousel-item {
  /* 轮播项 */
}

.fish-carousel__nav-button {
  /* 导航按钮 */
}

.fish-carousel__indicators {
  /* 指示器容器 */
}

.fish-carousel__indicator {
  /* 指示器 */
}
```

## 许可证

MIT