YGChatCS/components/ImageSwiper

ImageSwiper 轮播图组件

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

功能特性

• 🎨 可配置圆角：支持数字(px)或字符串形式的圆角设置
• 📏 可配置高度：支持数字(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>
  <!-- 数字形式 (px) -->
  <ImageSwiper :height="300" />
  
  <!-- 字符串形式 -->
  <ImageSwiper height="50vh" />
  
  <!-- 小高度轮播图 -->
  <ImageSwiper :height="120" />
</template>

隐藏缩略图

<template>
  <!-- 隐藏缩略图，只显示主轮播图 -->
  <ImageSwiper :show-thumbnails="false" />
  
  <!-- 结合其他属性使用 -->
  <ImageSwiper 
    :height="250" 
    :border-radius="15" 
    :show-thumbnails="false" 
  />
</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
height	Number | String	200	轮播图高度，数字时单位为px
showThumbnails	Boolean	true	是否显示缩略图
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" 
    :height="responsiveHeight"
    :show-thumbnails="showThumbnails"
  />
</template>

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

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

const responsiveHeight = computed(() => {
  const screenWidth = uni.getSystemInfoSync().screenWidth
  return screenWidth > 750 ? 300 : 200
})

// 动态控制缩略图显示
const showThumbnails = ref(true)
</script>

动态控制示例

<template>
  <view>
    <!-- 控制面板 -->
    <view class="control-panel">
      <text>高度: {{ dynamicHeight }}px</text>
      <slider 
        :value="dynamicHeight" 
        :min="100" 
        :max="400" 
        @change="handleHeightChange"
      />
      
      <view class="checkbox-wrapper">
        <checkbox :checked="showThumbnails" @change="handleThumbnailToggle" />
        <text>显示缩略图</text>
      </view>
    </view>
    
    <!-- 轮播图组件 -->
    <ImageSwiper 
      :height="dynamicHeight" 
      :show-thumbnails="showThumbnails" 
      :border-radius="10" 
    />
  </view>
</template>

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

const dynamicHeight = ref(200)
const showThumbnails = ref(true)

const handleHeightChange = (e) => {
  dynamicHeight.value = e.detail.value
}

const handleThumbnailToggle = (e) => {
  showThumbnails.value = e.detail.value
}
</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. 高度单位：数字类型自动添加px单位，字符串类型直接使用（支持vh、rem等）
3. 缩略图显示：当设置 showThumbnails 为 false 时，缩略图完全隐藏
4. 图片比例：建议使用相同比例的图片以获得最佳显示效果
5. 性能优化：大量图片时建议使用懒加载
6. 兼容性：支持微信小程序、H5、App等平台

更新日志

v1.3.0

• ✨ 新增 height 属性，支持自定义轮播图高度
• ✨ 新增 showThumbnails 属性，支持隐藏缩略图
• 🎨 优化样式系统，移除硬编码高度
• 🔧 改进计算属性，支持动态高度和缩略图控制
• 📝 更新文档和演示示例，新增多个高级用法示例
• 🎯 增强组件灵活性，适应更多使用场景

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