@tanzhenxing/zx-swiper v1.0.4

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

基础属性

轮播控制

滑动控制

显示控制

指示器

内容显示

视频控制

🎯 Events 事件

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

🎨 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