npm package: @hbis-uni/hbis-previewimage
Description: HBIS UNI previewImage component
Latest version: 1.0.5

# hbis-previewImage 组件

用于图片预览的 UniApp 组件，支持手势滑动切换、缩放、平移等功能。

## 功能特性

- ✅ 支持多张图片预览
- ✅ 手势滑动切换图片
- ✅ 鼠标滚轮缩放图片
- ✅ 图片平移功能
- ✅ 支持触摸和鼠标事件
- ✅ 自定义缩放范围
- ✅ 左右导航按钮切换
- ✅ 关闭按钮控制显示
- ✅ 图片加载状态管理
- ✅ 响应式设计，适配不同屏幕
- ✅ Vue 3 + TypeScript 开发
- ✅ 支持按需引入
- ✅ 兼容 UniApp 所有平台

## 安装

### 方式一：通过主组件库安装

```bash
pnpm add @hbis-uni/components
```

### 方式二：单独安装

```bash
pnpm add @hbis-uni/hbis-previewImage
```

## 使用

### 基本使用

```vue
<template>
  <hbisPreviewImage
    :images="[
      'https://example.com/image1.jpg',
      'https://example.com/image2.jpg'
    ]"
  />
</template>

<script setup lang="ts">
import { hbisPreviewImage } from '@hbis-uni/components';
</script>
```

### 带控制按钮的使用

```vue
<template>
  <button @click="togglePreview">预览图片</button>
  <hbisPreviewImage
    v-if="showPreview"
    :images="imageList"
    @close="showPreview = false"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { hbisPreviewImage } from '@hbis-uni/components';

const showPreview = ref(false);
const imageList = ref([
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg'
]);

const togglePreview = () => {
  showPreview.value = !showPreview.value;
};
</script>
```

## API

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| images | string[] | 必填 | 要预览的图片URL数组 |
| initialIndex | number | 0 | 初始显示的图片索引 |
| minScale | number | 0.5 | 最小缩放倍数 |
| maxScale | number | 5 | 最大缩放倍数 |
| showCloseBtn | boolean | true | 是否显示关闭按钮 |
| enableSwipe | boolean | true | 是否启用滑动切换图片功能 |

### 事件

| 事件名 | 参数 | 说明 |
| --- | --- | --- |
| close | 无 | 关闭预览时触发 |
| change | index: number | 图片切换时触发，返回当前图片索引 |
| update:initialIndex | index: number | 图片切换时触发，用于v-model双向绑定 |

### 方法（内部使用）

| 方法名 | 说明 |
| --- | --- |
| prevImage() | 切换到上一张图片 |
| nextImage() | 切换到下一张图片 |
| handleTouchStart() | 处理触摸开始事件 |
| handleTouchMove() | 处理触摸移动事件 |
| handleTouchEnd() | 处理触摸结束事件 |
| handleMouseDown() | 处理鼠标按下事件 |
| handleMouseMove() | 处理鼠标移动事件 |
| handleMouseUp() | 处理鼠标释放事件 |
| handleWheel() | 处理鼠标滚轮缩放事件 |
| zoomImage() | 缩放图片 |

## 样式说明

### 组件结构

```
.image-preview/
├── .counter               # 图片数量指示器
├── .close-btn             # 关闭按钮
├── .swiper-container      # 图片滑动容器
│   ├── .swiper-wrapper    # 滑动包装器
│   │   ├── .swiper-slide  # 单个图片幻灯片
│   │   │   ├── .image-container # 图片容器
│   │   │   │   └── .preview-image # 预览图片
├── .nav-btn.prev-btn      # 上一张按钮
└── .nav-btn.next-btn      # 下一张按钮
```

### 样式类名

| 类名 | 说明 |
| --- | --- |
| image-preview | 组件根容器类 |
| counter | 图片数量指示器类 |
| counter-text | 数量文本类 |
| close-btn | 关闭按钮类 |
| swiper-container | 滑动容器类 |
| swiper-wrapper | 滑动包装器类 |
| swiper-slide | 单个幻灯片类 |
| image-container | 图片容器类 |
| preview-image | 预览图片类 |
| nav-btn | 导航按钮类 |
| prev-btn | 上一张按钮类 |
| next-btn | 下一张按钮类 |

## 兼容性

| 平台 | 兼容性 |
| --- | --- |
| H5 | ✅ 支持 |
| App (iOS) | ✅ 支持 |
| App (Android) | ✅ 支持 |
| 微信小程序 | ✅ 支持 |
| 支付宝小程序 | ✅ 支持 |
| 百度小程序 | ✅ 支持 |
| 字节跳动小程序 | ✅ 支持 |
| QQ小程序 | ✅ 支持 |

## 开发说明

### 组件结构

```
hbis-previewImage/
├── src/
│   └── hbis-previewImage.vue   # 组件源码
├── index.ts                    # 组件入口
├── package.json                # 包配置
└── README.md                   # 组件文档
```

### 开发环境

- Vue 3 + TypeScript
- Vite
- UniApp

### 构建命令

```bash
# 构建整个组件库
pnpm run build
```

## 示例

### 完整示例

```vue
<template>
  <div class="container">
    <h1>hbis-PreviewImage 组件测试</h1>
    <button @click="togglePreview" class="preview-button">
      预览图片
    </button>
    <hbisPreviewImage
      v-if="showPreview"
      :images="[
        'https://gips2.baidu.com/it/u=195724436,3554684702&fm=3028&app=3028&f=JPEG&fmt=auto?w=1280&h=960',
        'https://qcloud.dpfile.com/pc/tDtlU13RHE3KUPgi1BKJRQRWVxtQFgSxDFd5SWK7g8ULeRH_uHl9qBQHIwIxPC2T.jpg'
      ]"
      @close="showPreview = false"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { hbisPreviewImage } from '@hbis-uni/components';

const showPreview = ref(false);

const togglePreview = () => {
  showPreview.value = !showPreview.value;
};
</script>

<style scoped>
.container {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
  font-family: Arial, sans-serif;
}

h1 {
  color: #333;
  margin-bottom: 20px;
  text-align: center;
}

.preview-button {
  background-color: #409eff;
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
  font-size: 16px;
  transition: background-color 0.3s;
}

.preview-button:hover {
  background-color: #66b1ff;
}

.preview-button:active {
  background-color: #3a8ee6;
}
</style>
```

## 注意事项

1. 确保图片URL正确且可访问
2. 组件默认全屏显示，建议通过v-if控制其显示/隐藏
3. 支持鼠标和触摸事件，可在不同设备上使用
4. 图片加载采用lazy模式，优化性能
5. 在UniApp中使用时，确保正确引入组件

## 更新日志

### v1.0.0

- ✅ 初始版本发布
- ✅ 支持多张图片预览
- ✅ 手势滑动切换图片
- ✅ 鼠标滚轮缩放图片
- ✅ 图片平移功能
- ✅ 自定义缩放范围
- ✅ 左右导航按钮
- ✅ 关闭按钮控制

## 许可证

ISC

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如果有任何问题或建议，欢迎通过以下方式联系：

- Email: [1162116242@qq.com](mailto:1162116242@qq.com)
---

**HBIS UNI Components Library**

*打造高质量的 UniApp 组件库*