更新记录

2.0.1（2026-08-09）

• PDF 支持 pdfMode: "scroll" | "page"，默认连续滚动；page 为单页 + 底栏翻页
• pdfBar 增加 height / prevText / nextText / showPageInfo；iconColor 在 page 模式生效
• 原生全屏预览无 Vue slot；业务可用 showTopBar: false + pdfBar.show: false + gotoPage 自建切页 UI
• Android / iOS / 鸿蒙 Next 三端对齐

2.0.0（2026-08-08）

• 新增本地音视频预览：视频 mp4 / mov / 3gp，音频 mp3 / m4a / aac / wav
• 完善鸿蒙 Next 离线预览（PDF / Office / 图片 / 文本 / HTML / 音视频）
• PDF 滚动连续翻页体验对齐三端；PPT 仅支持 .pptx
• 依赖系统解码器，同后缀不同编码可能黑屏/无声；关闭预览页会释放播放器避免漏音

1.0.0（2026-06-28）

1.0.0（2026-06-28）

• 首次发布
• 支持 Office文档、图片、文本、HTML 离线预览
• 支持 自定义导航栏、水印、防截屏等
• 提供 openPreview、closePreview、gotoPage、clearCache、getVersion API

平台兼容性

uni-app(4.0)

uni-app x(4.0)

其他

wg-app-preview-file

uni-app APP 端离线文件预览 UTS 插件。支持 PDF、Office（docx / xlsx / pptx）、图片、文本、HTML、音视频的本地预览，以及 URL 下载后预览。

特性

• 真离线：本地路径直接预览，无需联网
• URL 模式：插件内下载后预览，支持缓存与 SSL 证书链异常重试
• Office 高保真：Android / iOS 均使用 WebView + 专业 JS 引擎
• 水印：文字平铺水印，可调透明度与角度（Android / iOS / 鸿蒙 v1.2+）
• 防截屏：Android FLAG_SECURE；iOS 录屏时内容模糊；鸿蒙隐私窗口模式

平台支持

本插件为 UTS 原生插件，必须在 App 端 + 自定义调试基座 / 正式打包 中使用，标准基座无效。鸿蒙端需 HBuilderX 4.61+，运行到鸿蒙真机或模拟器。

安装

1. 从插件市场导入，或将 uni_modules/wg-app-preview-file 复制到项目 uni_modules 目录
2. 在 HBuilderX 中打开项目
3. 运行 → 运行到手机或模拟器 → 制作自定义调试基座，勾选本插件
4. 基座制作完成后，选择「自定义调试基座」运行到 Android / iOS / 鸿蒙 真机

快速开始

import {
    openPreview,
    closePreview,
    gotoPage,
    clearCache,
    getVersion,
} from "@/uni_modules/wg-app-preview-file";

// 本地文件（推荐：先 download 再 preview）
uni.downloadFile({
    url: "https://example.com/report.pdf",
    success: (res) => {
        openPreview({
            source: { type: "path", path: res.tempFilePath },
            title: "合同附件",
            watermark: { text: "内部资料", opacity: 0.15, angle: -30 },
            success: (result) => console.log("预览成功", result.filePath),
            fail: (err) => console.error(err.errCode, err.errMsg),
        });
    },
});

// 持久化路径
openPreview({
    source: { type: "path", path: "_doc/report.pdf" },
    title: "年度报告",
    targetPage: 1,
    pdfMode: "scroll", // 或 "page"：单页 + 底栏翻页
    pdfBar: {
        show: true,
        textColor: "#666666",
        iconColor: "#3370FF",
        prevText: "上一页",
        nextText: "下一页",
    },
});

// URL 模式（插件内下载）
openPreview({
    source: { type: "url", url: "https://example.com/file.docx" },
    title: "在线文档",
    keepCache: true,
});

API

openPreview(options)

打开全屏文件预览页。

PreviewSource

PreviewWatermark

PreviewPdfBar

pdfMode: "scroll" 时底栏默认仅页码；"page" 时显示上一页 / 页码 / 下一页。原生全屏预览不提供 Vue slot，若要自建切页 UI，请 showTopBar: false、pdfBar.show: false，再用 gotoPage。

PreviewResult

closePreview()

关闭当前预览页。

gotoPage(page: number)

跳转到 PDF 指定页，页码从 1 开始。scroll / page 两种模式均可用。

clearCache(options?)

清除插件下载与 Office 预览缓存目录，返回释放的字节数。

clearCache({
    success: (res) => console.log("释放", res.freedBytes, "字节"),
});

getVersion()

返回插件版本号字符串，如 "2.0.1"。

错误码

支持格式

不支持 Office 97-2003 二进制格式（.doc、.xls、.ppt）。请转换为 .docx、.xlsx、.pptx 后预览。

音视频说明：依赖系统解码器，不保证同后缀全部编码可播（如部分 HEVC / 特殊 AAC）；3gp 在 iOS/鸿蒙兼容性通常弱于 Android。不支持 HLS/流媒体与自定义播放 UI。gotoPage / pdfBar / targetPage 对媒体无效。

离线预览最佳实践

// 1. 下载到本地
uni.downloadFile({
    url: fileUrl,
    success: (res) => {
        // 2. 可选：持久化到 _doc
        uni.saveFile({
            tempFilePath: res.tempFilePath,
            success: (saveRes) => {
                openPreview({
                    source: { type: "path", path: saveRes.savedFilePath },
                    title: "离线文档",
                });
            },
            fail: () => {
                // 临时路径也可直接预览
                openPreview({
                    source: { type: "path", path: res.tempFilePath },
                    title: "离线文档",
                });
            },
        });
    },
});

常见问题

1. 标准基座无法使用？

UTS 插件必须在 自定义调试基座 或 云打包 / 本地打包 中使用。

2. 文件打不开？

• 确认路径可读，插件已内置 _doc/、_www/ 等虚拟路径解析
• 无扩展名时传 fileName 或 fileType
• 检查文件是否损坏、格式是否在支持列表内

3. Office 预览空白？

• 首次打开会将 assets 复制到缓存目录，请稍候
• 确认文件为 Open XML 格式（docx / xlsx / pptx）
• 复杂文档（大量公式、宏、嵌入对象）建议真机实测

4. URL 预览失败？

• 检查网络权限与 HTTPS 证书
• 插件会对 SSL 证书链不完整的服务器自动重试一次
• 可改用 downloadFile + path 模式

5. 修改插件后如何生效？

重新 制作自定义调试基座，或重新打包正式版。