hbis-swiper 轮播图组件

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

功能特性

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

平台支持

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

安装

npm install @hbis-uni/components

基础用法

图片轮播

<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>

自定义内容

<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 | 停止自动播放 | - |

高级用法

禁用自动播放

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

自定义播放速度

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

垂直轮播

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

数字指示器

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

自定义指示器样式

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

自定义箭头

<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>

程序控制

<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>

监听事件

<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