YGChatCS/components/ImageSwiper/README.md

# ImageSwiper 轮播图组件

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

## 功能特性

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

## 基础用法

### 默认使用

```vue
<template>
  <ImageSwiper />
</template>

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

### 自定义圆角

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

### 自定义高度

```vue
<template>
  <!-- 数字形式 (px) -->
  <ImageSwiper :height="300" />
  
  <!-- 字符串形式 -->
  <ImageSwiper height="50vh" />
  
  <!-- 小高度轮播图 -->
  <ImageSwiper :height="120" />
</template>
```

### 隐藏缩略图

```vue
<template>
  <!-- 隐藏缩略图，只显示主轮播图 -->
  <ImageSwiper :show-thumbnails="false" />
  
  <!-- 结合其他属性使用 -->
  <ImageSwiper 
    :height="250" 
    :border-radius="15" 
    :show-thumbnails="false" 
  />
</template>
```

### 自定义图片数据

```vue
<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>
```

### 缩略图滑动功能

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

```vue
<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 数组结构

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

## 样式定制

### 圆角配置示例

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

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

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

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

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

### 动态圆角控制

```vue
<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>
```

## 高级用法

### 响应式配置

```vue
<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>
```

### 动态控制示例

```vue
<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>
```

### 主题适配

```vue
<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