更新记录

1.0.0（2025-09-23）

[1.0.0] - 2025-09-21

新增

• 初次发布 hy-file-preview-plus 插件
• 支持图片文件预览（JPG、PNG、GIF、WebP等格式）
• 支持PDF文件预览（前端渲染+服务端转换）
• 支持Office文档预览（Word、Excel、PowerPoint、TXT）
• 支持音视频文件预览（MP4、MP3等格式）
• 提供完整的工具栏和控制功能
• 支持多平台适配（App、H5、小程序）
• 提供TypeScript类型定义
• 完整的错误处理和加载状态

功能特性

平台兼容性

uni-app(3.6.5)

uni-app x(3.6.5)

其他

hy-file-preview-plus 增强型文件预览组件

一个功能强大、支持多种格式的 uni-app 文件预览组件，支持图片、PDF、Office文档、音视频等格式预览。

特性

• 🖼️ 多格式支持: 支持图片、PDF、Office文档、音视频等常见格式
• 📱 多端兼容: 完美适配 App、H5、微信小程序、支付宝小程序等平台
• 🎨 高度可定制: 可配置预览方式、工具栏、主题样式等
• ⚡ 性能优化: 智能缓存、懒加载、服务端转换优化
• 🔧 开发友好: 完整的 API 文档和 TypeScript 支持

安装

方式一：通过 uni_modules 安装

1. 在 HBuilderX 中右键项目
2. 选择「导入插件」
3. 搜索 hy-file-preview-plus 并安装

方式二：手动安装

1. 下载插件包
2. 将 hy-file-preview-plus 文件夹复制到项目的 uni_modules 目录
3. 在页面中引入组件

快速开始

基本使用

<template>
  <view class="container">
    <hy-file-preview-plus
      ref="filePreviewer"
      :file-list="fileList"
      @download="onDownload"
      @open="onOpen"
      @close="onClose"
    />

    <button @click="previewFile">预览文件</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      fileList: [
        {
          name: '示例图片.jpg',
          url: 'https://example.com/image.jpg',
          size: 1024000
        }
      ]
    };
  },
  methods: {
    previewFile() {
      this.$refs.filePreviewer.previewFile(this.fileList[0]);
    },
    onDownload(file) {
      console.log('下载文件:', file);
    },
    onOpen({ file, index }) {
      console.log('打开文件:', file, index);
    },
    onClose() {
      console.log('关闭预览');
    }
  }
};
</script>

API 文档

Props 属性

属性                  类型       默认值    说明
fileList            Array    []     文件列表
currentIndex        Number   0      当前预览文件索引
showFileList        Boolean  false  是否显示文件列表
modalWidth          String  '90vw'  预览模态框宽度
modalHeight         String  '80vh'  预览模态框高度
hideToolbar         Boolean  false  是否隐藏工具栏
showControls        Boolean  true   是否显示控制栏
showDownload        Boolean  true   是否显示下载按钮
maskClosable        Boolean  true   点击遮罩是否关闭
imageScale          Number   1      图片初始缩放比例
maxScale            Number   5      图片最大缩放比例
minScale            Number   0.5    图片最小缩放比例
pdfUseService       Boolean  false  PDF是否使用服务端转换
pdfServiceUrl       String   ''     PDF转换服务地址
officeServiceUrl    String   ''     Office转换服务地址
officeConvertFormat String   'pdf'  Office转换格式
mediaAutoplay       Boolean  false  音视频是否自动播放
mediaControls       Boolean  true   音视频是否显示控制条

Events 事件

事件名         参数              说明
@open           { file, index } 打开预览时触发
@close          -               关闭预览时触发
@download       file            点击下载时触发
@file-select    file, index     选择文件时触发
@error          error, file     预览错误时触发
@load           file            文件加载完成时触发

Methods 方法

通过 ref 调用组件方法：

// 预览指定文件
this.$refs.filePreviewer.previewFile(file, index);

// 关闭预览
this.$refs.filePreviewer.closePreview();

// 下一文件
this.$refs.filePreviewer.nextFile();

// 上一文件
this.$refs.filePreviewer.prevFile();

// 下载当前文件
this.$refs.filePreviewer.downloadCurrentFile();

文件格式支持

类型       格式                                 说明
图片       JPG, PNG, GIF, WebP, BMP, SVG          直接预览
PDF      PDF                                    支持前端渲染和服务端转换
Office   DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT   需要服务端转换
视频     MP4, AVI, MOV, WMV, FLV, M3U8            直接播放
音频      MP3, WAV, OGG, M4A, AAC                 直接播放

服务端转换

对于PDF和Office文档，建议使用服务端转换以获得更好的兼容性：

服务端接口要求

// 转换请求
POST /convert
{
  "url": "文件URL",
  "filename": "文件名",
  "format": "pdf|image",
  "scale": 1.5
}

// 转换响应
{
  "success": true,
  "pdfUrl": "转换后的PDF地址",
  "images": ["图片1地址", "图片2地址"],
  "totalPages": 10,
  "conversionTime": 2.5
}

自建转换服务

推荐使用以下开源方案：

LibreOffice: Office文档转换
ImageMagick: 图片处理
PDF.js: PDF渲染
FFmpeg: 音视频处理

平台差异说明

功能           App    H5  小程序
图片预览         ✅     ✅     ✅
PDF直接预览  ✅     ✅     ❌
PDF服务端转换 ✅     ✅     ✅
Office预览     ✅     ✅     ❌
音视频预览    ✅     ✅     ✅

注意: 小程序环境由于安全限制，部分格式需要服务端转换。

常见问题

Q: 小程序端PDF预览不显示？
A: 小程序环境限制，请配置 pdf-use-service="true" 使用服务端转换。

Q: Office文档预览失败？
A: Office文档需要服务端转换，请配置有效的 office-service-url。

Q: 大文件加载缓慢？
A: 建议使用CDN加速或服务端压缩转换。

Q: 如何自定义预览样式？
A: 使用插槽和CSS变量来自定义样式：

:root {
  --hy-preview-primary: #007AFF;
  --hy-preview-bg: #ffffff;
  --hy-preview-toolbar-height: 50px;
}