更新记录

1.1.0（2025-10-22）

新增功能 ✨

内联预览模式: 新增 inline-mode 属性，支持在页面中直接展示预览内容，无需弹窗
新增 inline-width 和 inline-height 属性，可自定义内联模式尺寸
新增 show-close-button 属性，控制内联模式下是否显示关闭按钮

优化改进

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类型定义
完整的错误处理和加载状态

功能特性

平台兼容性

其他

多语言	暗黑模式	宽屏模式
√	√	√

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

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

特性

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

安装

方式一：通过 uni_modules 安装

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

方式二：手动安装

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

快速开始

基本使用（弹窗模式）

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

内联模式使用

<template>
  <view class="container">
    <!-- 内联预览模式，直接在页面中显示，不使用弹窗 -->
    <hy-file-preview-plus
      ref="filePreviewer"
      :file-list="fileList"
      :inline-mode="true"
      inline-width="100%"
      inline-height="600px"
      :show-close-button="true"
      @download="onDownload"
      @open="onOpen"
      @close="onClose"
    />

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

<script>
export default {
  data() {
    return {
      fileList: [
        {
          name: '文档.pdf',
          url: 'https://example.com/document.pdf',
          size: 2048000
        }
      ]
    };
  },
  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      是否显示文件列表
inlineMode          Boolean  false      预览模式：false=弹窗，true=内联
inlineWidth         String   '100%'     内联模式宽度
inlineHeight        String   '500px'    内联模式高度
showCloseButton     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
}

自建转换服务

平台差异说明

支持平台

本组件已全面测试并支持以下平台：

✅ App（iOS）：所有功能完全支持
✅ App（Android）：所有功能完全支持
✅ H5：所有功能完全支持
✅ 微信小程序：部分功能需配置（见下表）
✅ 支付宝小程序：部分功能需配置
✅ 其他小程序：百度、字节跳动、QQ小程序

功能兼容性对照表

功能               App(iOS/Android)    H5      微信小程序    说明
图片预览             ✅                  ✅      ✅           全平台支持
图片缩放/旋转      ✅                  ✅      ✅           全平台支持
PDF直接预览        ✅                  ✅      ❌           小程序需服务端转换
PDF服务端转换      ✅                  ✅      ✅           推荐使用
Office预览         ✅                  ✅      ❌           需服务端转换
音视频预览         ✅                  ✅      ✅           全平台支持
弹窗模式           ✅                  ✅      ✅           全平台支持
内联模式           ✅                  ✅      ✅           全平台支持
文件下载           ✅                  ✅      ⚠️           小程序需授权

小程序特别说明

由于小程序环境的安全限制：

PDF和Office文档：必须配置 pdf-use-service="true" 和 office-service-url，使用服务端转换
文件下载：需用户授权，建议提前申请相关权限
网络图片：需在小程序后台配置域名白名单
内联模式：在小程序中同样支持，可替代弹窗方式

使用建议

<!-- 小程序环境推荐配置 -->
<hy-file-preview-plus
  ref="filePreviewer"
  :file-list="fileList"
  :pdf-use-service="true"
  pdf-service-url="https://your-api.com/pdf-convert"
  office-service-url="https://your-api.com/office-convert"
/>

常见问题

Q1: 能否不在弹窗内展示预览？

A: 可以！从 v1.0.0 版本起，组件支持内联模式。设置 :inline-mode="true" 即可在页面中直接展示预览内容，不使用弹窗。

<hy-file-preview-plus
  :inline-mode="true"
  inline-width="100%"
  inline-height="600px"
/>

Q2: 支持安卓、iOS、微信小程序吗？

A: 完全支持！

✅ iOS 和 Android：所有功能完全支持
✅ 微信小程序：支持，但PDF和Office需要配置服务端转换
✅ 其他平台：H5、支付宝等小程序均已测试通过

Q3: 小程序端PDF预览不显示？

A: 小程序环境限制，请配置 pdf-use-service="true" 使用服务端转换。

<hy-file-preview-plus
  :pdf-use-service="true"
  pdf-service-url="https://your-api.com/pdf-convert"
/>

Q4: Office文档预览失败？

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

Q5: 大文件加载缓慢？

A: 建议使用CDN加速或服务端压缩转换。

Q6: 如何自定义预览样式？

A: 可以通过以下方式自定义：

使用 hide-toolbar 隐藏工具栏
使用 show-controls 控制底部控制栏
通过 inline-width 和 inline-height 调整尺寸
自定义图标路径

<hy-file-preview-plus
  :hide-toolbar="false"
  :show-controls="true"
  modal-width="95vw"
  modal-height="90vh"
/>

Q7: 图标不显示怎么办？

A: 组件已内置文本图标作为备用方案，如果PNG图标加载失败，会自动显示文本图标（+、-、↻）。

如需自定义图标，可以通过以下方式：

<!-- 方式1：使用自己的图标图片 -->
<hy-file-preview-plus
  close-icon="/static/custom/close.png"
  download-icon="/static/custom/download.png"
  zoom-in-icon="/static/custom/zoom-in.png"
  zoom-out-icon="/static/custom/zoom-out.png"
  rotate-icon="/static/custom/rotate.png"
/>

<!-- 方式2：不设置图标，使用默认的文本图标 -->
<hy-file-preview-plus
  :file-list="fileList"
/>

增强型文件预览组件 文件预览 PDF预览 Office预览 图片预览 文档查看

更新记录

1.1.0（2025-10-22）

1.1.0（2025-10-22）

新增功能 ✨

优化改进

1.0.0（2025-09-23）

[1.0.0] - 2025-09-21

新增

功能特性

平台兼容性

其他

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

特性

安装

方式一：通过 uni_modules 安装

方式二：手动安装

快速开始

基本使用（弹窗模式）

内联模式使用

API 文档

Props 属性

Events 事件

Methods 方法

通过 ref 调用组件方法：

文件格式支持

服务端转换

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

服务端接口要求

自建转换服务

推荐使用以下开源方案：

平台差异说明

支持平台

功能兼容性对照表

小程序特别说明

使用建议

常见问题

Q1: 能否不在弹窗内展示预览？

Q2: 支持安卓、iOS、微信小程序吗？

Q3: 小程序端PDF预览不显示？

Q4: Office文档预览失败？

Q5: 大文件加载缓慢？

Q6: 如何自定义预览样式？

Q7: 图标不显示怎么办？

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

增强型文件预览组件

hy-scroll-plus

增强型虚拟列表与瀑布流组件

增强型网络请求封装

增强型拖拽排序组件

Modal title

增强型文件预览组件文件预览 PDF预览 Office预览图片预览文档查看