更新记录

1.0.0（2026-06-28）

1.0.0（2026-06-28）

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

平台兼容性

uni-app(3.8.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 端 + 自定义调试基座 / 正式打包 中使用，标准基座无效。鸿蒙端敬请期待～

安装

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,
    pdfBar: { show: true, textColor: "#666666" },
});

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

API

openPreview(options)

打开全屏文件预览页。

PreviewSource

PreviewWatermark

PreviewPdfBar

PreviewResult

closePreview()

关闭当前预览页。

gotoPage(page: number)

跳转到 PDF 指定页，页码从 1 开始。仅在 PDF 预览打开时有效。

clearCache(options?)

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

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

getVersion()

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

错误码

支持格式

不支持 Office 97-2003 二进制格式（.doc、.xls）。请转换为 .docx、.xlsx、.pptx 后预览。旧版 .ppt 在 iOS 上可能通过 QuickLook 降级预览。

离线预览最佳实践

// 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. 修改插件后如何生效？

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