239 lines
4.9 KiB
Markdown
239 lines
4.9 KiB
Markdown
# ImageSwiper 轮播图组件
|
||
|
||
一个功能丰富的轮播图组件，支持自定义圆角、缩略图导航和图片描述。
|
||
|
||
## 功能特性
|
||
|
||
- 🎨 **可配置圆角**：支持数字(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>
|
||
<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 |
|
||
| 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" />
|
||
</template>
|
||
|
||
<script setup>
|
||
import { computed } from 'vue'
|
||
|
||
// 根据屏幕宽度动态调整圆角
|
||
const responsiveRadius = computed(() => {
|
||
const screenWidth = uni.getSystemInfoSync().screenWidth
|
||
return screenWidth > 750 ? 16 : 8
|
||
})
|
||
</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. **图片比例**：建议使用相同比例的图片以获得最佳显示效果
|
||
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 |