zx-swiper 轮播组件

一个功能丰富、高度可定制的 uni-app 轮播组件，支持图片、视频、自定义内容等多种形式的轮播展示。

✨ 特性

• 🖼️ 多媒体支持：支持图片、视频、自定义内容轮播
• 🎛️ 丰富配置：支持所有 uni-app swiper 组件的原生属性
• 📱 响应式设计：支持横向、纵向滑动，自适应高度
• 🎨 自定义样式：可自定义指示器、遮罩层、圆角等样式
• ⚡ 性能优化：懒加载、视频自动暂停等性能优化
• 🎯 事件完整：完整的事件回调支持
• 🔧 方法暴露：提供编程式控制方法

📦 安装使用

1. 将 zx-swiper 文件夹复制到项目的 components 目录下
2. 在页面中引入并使用：

<template>
  <zx-swiper :list="imageList" :height="'400rpx'" />
</template>

<script setup>
import { ref } from 'vue'

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

📋 Props 属性

基础属性

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | list | Array | [] | 轮播数据列表 | | height | String/Number | '320rpx' | 组件高度 | | width | String/Number | '750rpx' | 组件宽度 | | loading | Boolean | false | 是否显示加载状态 | | bgColor | String | '#f3f4f6' | 背景颜色 | | radius | String/Number | '10rpx' | 圆角大小 |

轮播控制

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | autoplay | Boolean | true | 是否自动播放 | | interval | String/Number | 3000 | 自动切换间隔时间(ms) | | duration | String/Number | 500 | 滑动动画时长(ms) | | circular | Boolean | true | 是否启用循环播放 | | current | String/Number | 0 | 当前显示的索引 | | currentItemId | String | '' | 当前显示的item-id |

滑动控制

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | vertical | Boolean | false | 是否纵向滑动 | | disableTouch | Boolean | false | 是否禁用触摸滑动 | | touchable | Boolean | true | 是否响应用户触摸事件 | | previousMargin | String/Number | '0rpx' | 前边距 | | nextMargin | String/Number | '0rpx' | 后边距 |

显示控制

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | displayMultipleItems | Number | 1 | 同时显示的滑块数量 | | acceleration | Boolean | false | 是否开启连续滑动 | | easingFunction | String | 'default' | 切换缓动动画类型 |

指示器

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | indicator | Boolean | true | 是否显示指示器 | | indicatorMode | String | 'dot' | 指示器模式: 'dot', 'line' | | indicatorActiveColor | String | '#FFFFFF' | 激活指示器颜色 | | indicatorInactiveColor | String | 'rgba(255,255,255,0.35)' | 非激活指示器颜色 | | indicatorStyle | String/Object | '' | 指示器自定义样式 |

内容显示

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | keyName | String | 'url' | 对象数组中的图片字段名 | | imgMode | String | 'aspectFill' | 图片裁剪模式 | | showTitle | Boolean | false | 是否显示标题 | | showMask | Boolean | false | 是否显示遮罩 | | maskStyle | String/Object | '' | 遮罩样式 | | autoHeight | Boolean | false | 是否自适应高度 | | lazyLoad | Boolean | true | 是否开启懒加载 |

视频控制

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | videoControls | Boolean | true | 是否显示视频控制栏 | | videoAutoplay | Boolean | false | 视频是否自动播放 | | videoLoop | Boolean | false | 视频是否循环播放 | | videoMuted | Boolean | false | 视频是否静音 |

🎯 Events 事件

| 事件名 | 参数 | 说明 | |--------|------|------| | change | { current, source, currentItem } | 轮播切换时触发 | | click | { index, item } | 点击轮播项时触发 | | transition | event.detail | 轮播过渡时触发 | | animationfinish | event.detail | 动画结束时触发 | | imageLoad | event | 图片加载成功时触发 | | imageError | event | 图片加载失败时触发 | | videoPlay | event | 视频开始播放时触发 | | videoPause | event | 视频暂停时触发 | | videoEnded | event | 视频播放结束时触发 | | videoError | event | 视频播放错误时触发 |

🔧 Methods 方法

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

<template>
  <zx-swiper ref="swiperRef" :list="list" />
  <button @click="next">下一张</button>
</template>

<script setup>
import { ref } from 'vue'

const swiperRef = ref()

// 切换到下一张
const next = () => {
  swiperRef.value.next()
}
</script>

| 方法名 | 参数 | 说明 | |--------|------|------| | switchTo(index) | index: Number | 切换到指定索引 | | next() | - | 切换到下一张 | | prev() | - | 切换到上一张 | | getCurrentItem() | - | 获取当前轮播项数据 | | pauseAllVideos() | - | 暂停所有视频播放 |

🎨 Slots 插槽

indicator 插槽

自定义指示器：

<zx-swiper :list="list">
  <template #indicator="{ current, total }">
    <view class="custom-indicator">
      {{ current + 1 }} / {{ total }}
    </view>
  </template>
</zx-swiper>

item 插槽

自定义轮播项内容：

<zx-swiper :list="customList">
  <template #item="{ item, index }">
    <view class="custom-item">
      <text>{{ item.text }}</text>
    </view>
  </template>
</zx-swiper>

overlay 插槽

自定义覆盖层：

<zx-swiper :list="list">
  <template #overlay="{ current, total }">
    <view class="overlay">
      自定义覆盖内容
    </view>
  </template>
</zx-swiper>

📱 使用示例

基础图片轮播

<template>
  <zx-swiper 
    :list="imageList"
    :height="'400rpx'"
    :autoplay="true"
    :interval="3000"
  />
</template>

<script setup>
const imageList = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg',
  'https://example.com/image3.jpg'
]
</script>

带标题的轮播

<template>
  <zx-swiper 
    :list="titleList"
    :show-title="true"
    :height="'400rpx'"
  />
</template>

<script setup>
const titleList = [
  {
    url: 'https://example.com/image1.jpg',
    title: '图片标题1'
  },
  {
    url: 'https://example.com/image2.jpg',
    title: '图片标题2'
  }
]
</script>

视频轮播

<template>
  <zx-swiper 
    :list="videoList"
    :height="'300rpx'"
    :video-controls="true"
    @video-play="onVideoPlay"
  />
</template>

<script setup>
const videoList = [
  {
    type: 'video',
    url: 'https://example.com/video1.mp4',
    poster: 'https://example.com/poster1.jpg'
  }
]

const onVideoPlay = (e) => {
  console.log('视频开始播放', e)
}
</script>

纵向轮播

<template>
  <zx-swiper 
    :list="imageList"
    :vertical="true"
    :height="'600rpx'"
  />
</template>

自定义内容轮播

<template>
  <zx-swiper :list="customList">
    <template #item="{ item, index }">
      <view class="custom-item" :style="{ backgroundColor: item.color }">
        <text>{{ item.text }}</text>
      </view>
    </template>
  </zx-swiper>
</template>

<script setup>
const customList = [
  { text: '自定义内容1', color: '#ff6b6b' },
  { text: '自定义内容2', color: '#4ecdc4' }
]
</script>

🔍 数据格式说明

字符串数组

['image1.jpg', 'image2.jpg', 'video.mp4']

对象数组

[
  {
    url: 'image1.jpg',        // 图片/视频地址
    title: '标题',            // 可选：标题
    poster: 'poster.jpg',     // 可选：视频封面
    type: 'image|video|custom', // 可选：类型
    id: 'unique_id'           // 可选：唯一标识
  }
]

🚀 高级用法

1. 自适应高度

开启 autoHeight 后，组件会根据图片的实际高度自动调整：

<zx-swiper :list="imageList" :auto-height="true" />

2. 多项显示

同时显示多个轮播项：

<zx-swiper 
  :list="imageList"
  :display-multiple-items="2"
  :previous-margin="'20rpx'"
  :next-margin="'20rpx'"
/>

3. 编程式控制

通过 ref 调用方法进行控制：

<template>
  <zx-swiper ref="swiperRef" :list="imageList" />
  <view class="controls">
    <button @click="prev">上一张</button>
    <button @click="next">下一张</button>
    <button @click="goToFirst">第一张</button>
  </view>
</template>

<script setup>
const swiperRef = ref()

const prev = () => swiperRef.value.prev()
const next = () => swiperRef.value.next()
const goToFirst = () => swiperRef.value.switchTo(0)
</script>

🐛 注意事项

1. 视频播放：在小程序中，视频组件层级较高，可能会遮挡其他内容
2. 自适应高度：开启后会异步获取图片信息，可能导致初始化时高度闪动
3. 性能优化：大量图片时建议开启 lazyLoad 懒加载
4. 平台差异：部分属性在不同平台可能有差异，详见 uni-app 官方文档

🔄 更新日志

v2.0.0

• ✨ 新增视频轮播支持
• ✨ 新增自定义内容插槽
• ✨ 新增更多事件回调
• ✨ 新增编程式控制方法
• 🐛 修复 nextMargin 默认值错误
• 🐛 修复多项显示时的样式问题
• ⚡ 优化性能和代码结构

v1.0.0

• 🎉 初始版本发布
• ✨ 基础轮播功能
• ✨ 指示器支持
• ✨ 自适应高度

📄 许可证

MIT License