更新记录

1.0.0（2024-12-11） 下载此版本

无

平台兼容性

uni-app

其他

轮播图组件使用文档

1. 组件介绍

这是一个功能丰富的 uniapp 轮播图组件，支持水平/垂直轮播、自定义指示器、标题显示、遮罩效果、卡片效果等多种功能。

2. 安装使用

2.1 安装

将 my-swiper 组件复制到项目的 components 目录下。

2.2 引入组件

import MySwiper from '@/components/my-swiper/my-swiper.vue'

export default {
  components: {
    MySwiper
  }
}

3. 基础用法

3.1 水平轮播

<template>
  <my-swiper
    :list="swiperList"
    :options="swiperOptions"
    :height="250"
    @change="onChange"
  />
</template>

<script>
export default {
  data() {
    return {
      swiperList: [
        { 
          id: 1,
          image: 'path/to/image1.jpg',
          title: '标题1',
          subtitle: '副标题1',
          url: '/pages/detail/detail?id=1'
        }
      ],
      swiperOptions: {
        autoplay: true,
        interval: 3000,
        customIndicator: true,
        showTitle: true
      }
    }
  }
}
</script>

3.2 垂直轮播

<my-swiper
  :list="swiperList"
  :options="{
    verticalOptions: {
      enabled: true,
      height: '300rpx',
      spacing: '0'
    },
    customIndicator: true,
    indicatorPosition: 'right'
  }"
  :height="300"
/>

4. API

4.1 Props

4.2 数据结构

interface SwiperItem {
  id: number;          // 唯一标识
  image: string;       // 图片地址
  title?: string;      // 标题（可选）
  subtitle?: string;   // 副标题（可选）
  url?: string;        // 点击跳转链接（可选）
}

4.3 配置项（options）

基础配置

指示器配置

标题配置

效果配置

垂直轮播配置

verticalOptions: {
  enabled: Boolean,    // 是否启用垂直轮播
  height: String,      // 垂直轮播高度
  spacing: String      // 垂直间距
}

4.4 事件

5. 示例

5.1 卡片式轮播

swiperOptions: {
  cardEffect: true,
  shadowEffect: true,
  imageRadius: '16rpx',
  customIndicator: true,
  indicatorPosition: 'bottomRight'
}

5.2 带渐变标题的轮播

swiperOptions: {
  showTitle: true,
  titlePosition: 'overlay',
  showOverlay: true,
  overlayGradient: true,
  titleStyle: {
    background: 'linear-gradient(to top, rgba(0,0,0,0.7), transparent)',
    padding: '40rpx 20rpx 20rpx'
  }
}

5.3 自定义垂直轮播

swiperOptions: {
  verticalOptions: {
    enabled: true,
    height: '300rpx'
  },
  customIndicator: true,
  indicatorPosition: 'right',
  indicatorStyle: {
    right: '40rpx',
    padding: '5rpx',
    background: 'rgba(0, 0, 0, 0.3)',
    borderRadius: '10rpx'
  }
}

6. 注意事项

1. 图片资源

   • 建议使用相同尺寸的图片
   • 支持本地图片和网络图片
   • 建议图片进行压缩优化

2. 性能优化

   • 合理设置自动播放间隔
   • 避免同时使用过多动画效果
   • 图片预加载优化

3. 样式调整

   • 可通过 titleStyle 和 indicatorStyle 自定义样式
   • 注意 z-index 层级关系
   • 垂直轮播时注意内容布局

7. 常见问题

1. 图片不显示

   • 检查图片路径是否正确
   • 确认图片资源是否可访问
   • 查看是否有跨域限制

2. 指示器位置不正确

   • 检查 indicatorPosition 配置
   • 确认 indicatorStyle 样式设置
   • 垂直轮播时注意指示器方向

3. 动画效果不生效

   • 确认 animationMode 配置正确
   • 检查是否与其他动画效果冲突
   • 查看是否支持相关CSS属性