npm package: @hbis-uni/hbis-swiper
Description: HBIS Swiper component - 轮播图组件
Latest version: 1.0.0

# hbis-swiper 轮播图组件

一个功能完善的 Vue 3 轮播图组件，支持自动播放、触摸滑动、自定义样式等多种功能。

## 功能特性

- ✅ 自动播放，可配置播放间隔
- ✅ 支持触摸滑动切换
- ✅ 支持鼠标拖拽切换
- ✅ 支持循环播放
- ✅ 支持水平和垂直方向
- ✅ 可自定义指示器（圆点、数字）
- ✅ 可自定义指示器位置
- ✅ 支持左右箭头导航
- ✅ 支持自定义插槽
- ✅ 响应式设计，适配移动端
- ✅ 性能优化，使用 CSS transform
- ✅ 多平台支持：H5、App、小程序

## 平台支持

| 平台 | 支持状态 | 说明 |
|------|----------|------|
| H5 | ✅ 完全支持 | 支持所有功能 |
| App | ✅ 完全支持 | 支持所有功能 |
| 小程序 | ✅ 完全支持 | 已适配小程序环境，支持所有功能 |

## 安装

```bash
npm install @hbis-uni/components
```

## 基础用法

### 图片轮播

```vue
<template>
  <hbis-swiper :data="images" />
</template>

<script setup>
import { ref } from 'vue';
import { hbisSwiper } from '@hbis-uni/components';

const images = ref([
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg',
  'https://example.com/image3.jpg'
]);
</script>
```

### 自定义内容

```vue
<template>
  <hbis-swiper :data="items" height="400px">
    <template #default="{ item, index }">
      <div class="custom-slide">
        <h3>{{ item.title }}</h3>
        <p>{{ item.description }}</p>
      </div>
    </template>
  </hbis-swiper>
</template>

<script setup>
import { ref } from 'vue';
import { hbisSwiper } from '@hbis-uni/components';

const items = ref([
  { title: '标题1', description: '描述1' },
  { title: '标题2', description: '描述2' },
  { title: '标题3', description: '描述3' }
]);
</script>
```

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| data | 轮播数据数组 | Array | [] |
| autoplay | 是否自动播放 | Boolean | true |
| interval | 自动播放间隔时间（毫秒） | Number | 3000 |
| duration | 切换动画时长（毫秒） | Number | 500 |
| direction | 轮播方向，可选值：'horizontal'、'vertical' | String | 'horizontal' |
| showIndicators | 是否显示指示器 | Boolean | true |
| indicatorType | 指示器类型，可选值：'dots'、'numbers'、'none' | String | 'dots' |
| indicatorPosition | 指示器位置，可选值：'top'、'bottom'、'left'、'right' | String | 'bottom' |
| showArrows | 是否显示左右箭头 | Boolean | true |
| loop | 是否循环播放 | Boolean | true |
| height | 轮播容器高度 | String/Number | '300px' |
| width | 轮播容器宽度 | String/Number | '100%' |
| slideWidth | 单个轮播项宽度 | String/Number | '100%' |
| slideHeight | 单个轮播项高度 | String/Number | '100%' |
| indicatorColor | 指示器颜色 | String | '#ffffff' |
| indicatorActiveColor | 当前指示器颜色 | String | '#ffffff' |
| indicatorSize | 指示器大小 | String/Number | 8 |
| touchRatio | 触摸滑动比例 | Number | 0.5 |
| threshold | 滑动切换阈值 | Number | 50 |

### Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| change | 当前轮播项改变时触发 | (index: number) |
| transition-start | 切换动画开始时触发 | (index: number) |
| transition-end | 切换动画结束时触发 | (index: number) |

### Slots

| 插槽名 | 说明 | 作用域参数 |
|--------|------|-----------|
| default | 自定义轮播项内容 | { item, index } |
| arrow-prev | 自定义左箭头 | - |
| arrow-next | 自定义右箭头 | - |

### Methods

通过 ref 可以调用以下方法：

| 方法名 | 说明 | 参数 |
|--------|------|------|
| next | 切换到下一张 | - |
| prev | 切换到上一张 | - |
| goToSlide | 切换到指定索引 | (index: number) |
| startAutoplay | 开始自动播放 | - |
| stopAutoplay | 停止自动播放 | - |

## 高级用法

### 禁用自动播放

```vue
<template>
  <hbis-swiper :data="images" :autoplay="false" />
</template>
```

### 自定义播放速度

```vue
<template>
  <hbis-swiper :data="images" :interval="5000" :duration="800" />
</template>
```

### 垂直轮播

```vue
<template>
  <hbis-swiper :data="images" direction="vertical" height="100%" width="200px" />
</template>
```

### 数字指示器

```vue
<template>
  <hbis-swiper :data="images" indicator-type="numbers" />
</template>
```

### 自定义指示器样式

```vue
<template>
  <hbis-swiper 
    :data="images" 
    indicator-color="#ff0000" 
    indicator-active-color="#00ff00" 
    indicator-size="12"
  />
</template>
```

### 自定义箭头

```vue
<template>
  <hbis-swiper :data="images">
    <template #arrow-prev>
      <button class="custom-arrow">←</button>
    </template>
    <template #arrow-next>
      <button class="custom-arrow">→</button>
    </template>
  </hbis-swiper>
</template>

<style scoped>
.custom-arrow {
  background: #409eff;
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
}
</style>
```

### 程序控制

```vue
<template>
  <div>
    <hbis-swiper ref="swiperRef" :data="images" />
    <button @click="goToSlide(0)">第一张</button>
    <button @click="goToSlide(2)">第三张</button>
    <button @click="toggleAutoplay">{{ isPlaying ? '暂停' : '播放' }}</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { hbisSwiper } from '@hbis-uni/components';

const swiperRef = ref(null);
const isPlaying = ref(true);

const goToSlide = (index) => {
  swiperRef.value?.goToSlide(index);
};

const toggleAutoplay = () => {
  if (isPlaying.value) {
    swiperRef.value?.stopAutoplay();
  } else {
    swiperRef.value?.startAutoplay();
  }
  isPlaying.value = !isPlaying.value;
};
</script>
```

### 监听事件

```vue
<template>
  <hbis-swiper 
    :data="images" 
    @change="onChange"
    @transition-start="onTransitionStart"
    @transition-end="onTransitionEnd"
  />
</template>

<script setup>
import { hbisSwiper } from '@hbis-uni/components';

const onChange = (index) => {
  console.log('当前轮播项索引:', index);
};

const onTransitionStart = (index) => {
  console.log('切换动画开始:', index);
};

const onTransitionEnd = (index) => {
  console.log('切换动画结束:', index);
};
</script>
```

## 注意事项

1. **数据格式**：data 属性应该是一个数组，可以是图片 URL 字符串数组，也可以是对象数组
2. **触摸滑动**：在移动端支持触摸滑动切换，可以通过 touchRatio 和 threshold 调整滑动灵敏度
3. **循环播放**：loop 为 true 时，第一张和最后一张会自动衔接
4. **性能优化**：组件使用 CSS transform 实现动画，性能较好
5. **响应式**：组件会自动适应容器大小变化

## 浏览器兼容性

- Chrome (最新版本)
- Firefox (最新版本)
- Safari (最新版本)
- Edge (最新版本)
- iOS Safari (iOS 12+)
- Android Chrome (最新版本)

## License

ISC