更新记录

1.1.0（2026-09-08） 下载此版本

• 彻底重构为「本地渲染引擎」方案：docx / PDF 文档字节由 App 通过 uni.request（原生网络栈、可带鉴权头）取回，经任务桥交给 renderjs 视图层，由随包依赖 @js-preview/docx（docx-preview）、@js-preview/pdf（pdf.js）本地解析渲染。
• 移除对 XDOC / 微软 / Google 等所有第三方公网在线转换服务的依赖；不再把文档 URL 交给任何第三方网站，也不跳系统其它 App。
• 新增属性：docType（强制类型）、headers（鉴权请求头）、hostHeight、maxSizeMb、renderTimeout。
• 支持平台：App（Android / iOS）；鸿蒙端 renderjs 能力取决于 uni-app 版本，请真机实测。
• 注意：.doc 旧版格式无本地开源渲染器，1.1.0 起仅支持 .docx / .pdf。

平台兼容性

uni-app(3.8.3)

其他

lv-doc-preview

App 端「在线文档预览」组件：传入一个 docx / PDF 的网络 URL，文档字节由 App 自己取回（可带鉴权头），交给随包自带的本地渲染引擎在视图层解析展示。

全程不依赖任何第三方公网转换服务（不用 XDOC / 微软 / Google 在线预览）、不跳系统其它 App、不把文档内容发送到任何第三方网站。

特性

• 支持 .docx（Word 合同 / 文书）、.pdf 两种格式在线预览
• URL 即文档地址，组件内部 uni.request（原生网络栈）取字节，跨域、鉴权都不受限
• 渲染引擎 @js-preview/docx（内部封装 docx-preview）与 @js-preview/pdf（内部封装 pdf.js）已内置在 npm 依赖产物里，运行时不请求任何外网
• 渲染发生在页面 renderjs 视图层，效果与网页版一致，可双指缩放系统级滚动
• 失败兜底：下载失败 / 类型不支持 / 渲染出错均有明确提示与「重新加载 / 复制地址」操作
• 不改动宿主项目任何业务代码，easycom 零配置即用

局限（务必先读）

1. .doc（旧版二进制 Word）本地没有成熟开源渲染器，本插件不支持，请服务端先转成 .docx 或 .pdf；.docx 才是本地引擎支持的对象。
2. 不支持 Excel / PPT / txt / 图片（这些不在本次需求范围）。
3. 只适合在独立页面使用（web 渲染内容需要一块完整视图区）。
4. 受逻辑层与视图层数据通道限制，单文件默认上限 20MB（可用 maxSizeMb 调整）。
5. 鸿蒙端：本组件基于 renderjs，其支持情况取决于你所用 uni-app 版本对 HarmonyOS 视图层 renderjs 的支持程度，请以真机实测为准（实测不生效时会走「渲染超时」错误提示，可据此判断）。

快速开始

1. 安装依赖（引擎在 npm 包内）

组件顶部 import 了两个渲染引擎包，项目必须能解析它们：

npm install docx-preview @js-preview/pdf

• docx-preview：渲染 .docx（纯浏览器实现，只依赖 jszip，无 Node 内置模块依赖，可安全打进 renderjs）
• @js-preview/pdf：渲染 .pdf（内部封装 pdf.js，产物自包含、无外部 import）

本项目已安装 docx-preview ^0.4.0、@js-preview/pdf ^2.0.10（package.json 中已声明），另有 jszip 也已具备。

注意：不要用 @js-preview/docx 替代 docx-preview——它的产物顶层 import "stream"/"events"/"buffer"/"util"，renderjs 由 esbuild 按浏览器平台打包，会直接报 Could not resolve "stream" 导致构建失败。

2. 使用组件

easycom 会自动扫描 uni_modules/*/components，无需注册，直接当标签用：

<lv-doc-preview src="https://你的域名/合同/劳动合同.docx" />

3. 完整示例（独立页面）

新建 pages/preview/preview.vue 并注册到 pages.json：

<template>
  <view style="width: 100%; height: 100vh;">
    <lv-doc-preview
      :src="docUrl"
      :fileName="docName"
      :headers="docHeaders"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      docUrl: '',
      docName: '',
      docHeaders: {
        // 若文档服务器要求登录态 / 鉴权头，在这里传（选填）
        // Authorization: 'Bearer xxx',
        // Buthorization: 'xxxx'
      }
    }
  },
  onLoad(options) {
    // 上一页 navigateTo 传参：
    // /pages/preview/preview?url=<encodeURIComponent(文件URL)>&name=<encodeURIComponent(文件名)>
    this.docUrl = options.url ? decodeURIComponent(options.url) : ''
    this.docName = options.name ? decodeURIComponent(options.name) : ''
  }
}
</script>

上一页跳转：

uni.navigateTo({
  url: '/pages/preview/preview?url=' + encodeURIComponent(fileUrl) +
       '&name=' + encodeURIComponent(fileName || '')
})

4. 常见传法

<!-- 带扩展名的直链 -->
<lv-doc-preview src="https://xxx/files/劳动合同.docx" />

<!-- CDN 下载型链接（URL 无扩展名）→ 用 fileName 补文件名用于识别 -->
<lv-doc-preview src="https://xxx/download?fileId=123&t=xxx" fileName="审查报告.docx" />

<!-- PDF -->
<lv-doc-preview src="https://xxx/files/判决书.pdf" />

<!-- 服务端实为 docx 但扩展名不规范 / URL 被 .doc 命名 → 用 docType 强制 -->
<lv-doc-preview src="https://xxx/合同/合同.doc" docType="docx" />

<!-- 需要鉴权头 -->
<lv-doc-preview src="https://xxx/doc/123" fileName="合同.docx"
  :headers="{ Authorization: 'Bearer ' + token }" />

属性（Props）

工作原理

页面 (webview 视图层)
   └─ renderjs 模块：import @js-preview/docx / @js-preview/pdf（引擎已随依赖打包，无网络请求）
                          │  解码 base64 → ArrayBuffer → 引擎渲染
逻辑层 uni.request(url, responseType:'arraybuffer', header)  取回文档字节
   │  base64
任务桥 :change:task ──────┘

• 逻辑层 uni.request 走原生网络栈，不受 CORS 限制，可携带任意鉴权头；
• 字节仅在 App 内部流转（内存 + 视图层 DOM），不写文件、不落盘、不发给第三方；
• docx 由 docx-preview 解析为 HTML 排版展示；pdf 由 pdf.js（主线程渲染，产物内已规避 Web Worker 限制）逐页绘制。

注意事项 / 排查

• 地址必须是 App 能访问的公网 http(s)，不能被防盗链、UA 拦截。
• 若停留在「正在下载…」报错，多为网络/服务器问题；停留在「正在解析…」后超时，多为平台不支持 renderjs 或依赖未安装。
• docx 排版异常、缺字体时，可能是文档使用嵌入字体之外的字体，属本地引擎固有表现。
• 中文 PDF 若有罕见 CID 字体未嵌入可能出现缺字，绝大多数正常 PDF（字体已嵌入）不受影响。
• 超大 PDF（几十 MB）渲染较慢且占内存，建议服务端限制或用 maxSizeMb 提前拦截。

平台

• App（Android / iOS）：支持（renderjs 官方能力）
• 鸿蒙：取决于当前 uni-app 对 HarmonyOS renderjs 的支持，请真机实测
• H5：理论上可用（renderjs 在 H5 同样生效），本项目不维护 H5