hbis-previewImage 组件

用于图片预览的 UniApp 组件，支持手势滑动切换、缩放、平移等功能。

功能特性

• ✅ 支持多张图片预览
• ✅ 手势滑动切换图片
• ✅ 鼠标滚轮缩放图片
• ✅ 图片平移功能
• ✅ 支持触摸和鼠标事件
• ✅ 自定义缩放范围
• ✅ 左右导航按钮切换
• ✅ 关闭按钮控制显示
• ✅ 图片加载状态管理
• ✅ 响应式设计，适配不同屏幕
• ✅ Vue 3 + TypeScript 开发
• ✅ 支持按需引入
• ✅ 兼容 UniApp 所有平台

安装

方式一：通过主组件库安装

pnpm add @hbis-uni/components

方式二：单独安装

pnpm add @hbis-uni/hbis-previewImage

使用

基本使用

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

带控制按钮的使用

<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

构建命令

# 构建整个组件库
pnpm run build

示例

完整示例

<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: [email protected]

HBIS UNI Components Library

打造高质量的 UniApp 组件库