YGChatCS/components/ImageSwiper/README.md

ImageSwiper 轮播图组件

一个功能丰富的轮播图组件，支持自定义圆角、缩略图导航和图片描述。

功能特性

• 🎨 可配置圆角：支持数字(px)或字符串形式的圆角设置
• 🖼️ 缩略图导航：底部缩略图快速切换，支持左右滑动
• 📱 响应式设计：适配不同屏幕尺寸
• 🎯 自定义数据：支持传入自定义图片数据
• 📊 进度指示器：显示当前图片位置
• 🎭 选中状态：缩略图选中时高亮显示，带缩放动画
• 🔄 自动滚动：缩略图自动滚动到可视区域
• ⚡ 性能优化：使用计算属性优化渲染

基础用法

默认使用

<template>
  <ImageSwiper />
</template>

<script setup>
import ImageSwiper from '@/components/ImageSwiper/index.vue'
</script>

自定义圆角

<template>
  <!-- 数字形式 (px) -->
  <ImageSwiper :border-radius="12" />
  
  <!-- 字符串形式 -->
  <ImageSwiper border-radius="1rem" />
  
  <!-- 无圆角 -->
  <ImageSwiper :border-radius="0" />
</template>

自定义图片数据

<template>
  <ImageSwiper 
    :border-radius="15" 
    :images="customImages" 
  />
</template>

<script setup>
import { ref } from 'vue'
import ImageSwiper from '@/components/ImageSwiper/index.vue'

const customImages = ref([
  {
    photoUrl: "https://example.com/image1.jpg",
    photoName: "图片描述1"
  },
  {
    photoUrl: "https://example.com/image2.jpg",
    photoName: "图片描述2"
  }
])
</script>

缩略图滑动功能

组件支持缩略图左右滑动，当图片数量较多时，缩略图会自动滚动到可视区域：

<template>
  <!-- 多图片展示，缩略图支持滑动 -->
  <ImageSwiper :images="manyImages" />
</template>

<script setup>
const manyImages = ref([
  { photoUrl: "https://example.com/1.jpg", photoName: "图片1" },
  { photoUrl: "https://example.com/2.jpg", photoName: "图片2" },
  { photoUrl: "https://example.com/3.jpg", photoName: "图片3" },
  // ... 更多图片
  { photoUrl: "https://example.com/10.jpg", photoName: "图片10" }
])
</script>

API 文档

Props

参数	类型	默认值	说明
borderRadius	Number | String	8	轮播图圆角大小，数字时单位为px
images	Array	[]	图片数据数组，为空时使用默认数据

images 数组结构

interface ImageItem {
  photoUrl: string;   // 图片URL
  photoName: string;  // 图片名称/描述
}

样式定制

圆角配置示例

<!-- 小圆角 -->
<ImageSwiper :border-radius="4" />

<!-- 中等圆角 -->
<ImageSwiper :border-radius="12" />

<!-- 大圆角 -->
<ImageSwiper :border-radius="24" />

<!-- 使用rem单位 -->
<ImageSwiper border-radius="0.5rem" />

<!-- 使用百分比 -->
<ImageSwiper border-radius="10%" />

动态圆角控制

<template>
  <view>
    <slider 
      :value="radius" 
      :min="0" 
      :max="50" 
      @change="handleChange"
    />
    <ImageSwiper :border-radius="radius" />
  </view>
</template>

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

const radius = ref(8)

const handleChange = (e) => {
  radius.value = e.detail.value
}
</script>

高级用法

响应式圆角

<template>
  <ImageSwiper :border-radius="responsiveRadius" />
</template>

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

// 根据屏幕宽度动态调整圆角
const responsiveRadius = computed(() => {
  const screenWidth = uni.getSystemInfoSync().screenWidth
  return screenWidth > 750 ? 16 : 8
})
</script>

主题适配

<template>
  <ImageSwiper :border-radius="themeRadius" />
</template>

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

// 根据主题调整圆角
const isDarkMode = ref(false)
const themeRadius = computed(() => {
  return isDarkMode.value ? 12 : 8
})
</script>

注意事项

1. 圆角单位：数字类型自动添加px单位，字符串类型直接使用
2. 图片比例：建议使用相同比例的图片以获得最佳显示效果
3. 性能优化：大量图片时建议使用懒加载
4. 兼容性：支持微信小程序、H5、App等平台

更新日志

v1.2.0

• ✨ 新增缩略图左右滑动功能
• ✨ 新增缩略图选中状态高亮显示
• ✨ 新增缩略图自动滚动到可视区域
• 🎨 优化缩略图动画效果和交互体验
• 🔧 改进主轮播图与缩略图的联动机制
• 📝 更新文档和演示示例

v1.1.0

• ✨ 新增 borderRadius 属性，支持自定义圆角
• ✨ 新增 images 属性，支持自定义图片数据
• 🔧 优化组件结构，使用计算属性提升性能
• 📝 完善文档和示例

v1.0.0

• 🎉 初始版本发布
• ✨ 基础轮播图功能
• ✨ 缩略图导航
• ✨ 进度指示器

技术栈

• Vue 3 Composition API
• SCSS
• uni-app

浏览器支持

• 微信小程序
• H5 (Chrome, Firefox, Safari, Edge)
• App (iOS, Android)

许可证

MIT License