JP JitWord-Preview 文件预览 SDK Word 协同编辑

接入指南

从零到预览上线：部署 SDK 静态资源，选择任意一种接入方式，五分钟完成集成。

概述与环境要求

JitWord 文件预览 SDK 是纯前端文档预览方案：文件校验、安全检查、解析渲染全部在浏览器内完成，无任何后端依赖。支持格式：docx / xlsx / pptx / ofd / pdf / txt / md / html。

产物与部署托管

SDK 构建产物为 dist-sdk/ 目录，需原样整体托管在同一目录下，不可拆散：

dist-sdk/
├── file-preview.global.js   # ~1.5KB IIFE 引导脚本（ESM 分块的 script 标签入口）
├── file-preview.bundle.js   # ~13.9MB IIFE 单文件全量构建（CDN / 零 CORS）
├── file-preview.esm.js      # ESM 入口（打包器 / module 直连）
├── style.css                # 已作用域化的样式（自动注入）
├── chunks/                  # 核心 + 各格式渲染引擎（按需加载）
├── assets/                  # 安全检查 Worker 等资源
├── vendor/                  # mermaid.min.js（仅 MD 含流程图时按需 script 注入）
└── pdfjs/                   # PDF.js 资产（cmaps / 字体 / wasm）

引导脚本与 CDN 单文件都会通过自身 <script src> 自动探测资源基地址（ESM 直连则基于 import.meta.url 解析）。因此目录可以托管在任意静态路径（如本站的 https://jitword.com/preview_sdk/），无需任何额外配置。

提示 产物使用相对资源路径，托管在子路径（如 /preview_sdk/）下同样开箱即用，无需修改 base 或传入 assetPath。

快速开始

以本站托管地址为例，三步完成预览：

<!-- ① 准备一个有高度的容器 -->
<div id="preview-box" style="height: 660px"></div>

<!-- ② 引入 CDN 单文件构建（经典 script，跨域零 CORS） -->
<script src="https://jitword.com/preview_sdk/file-preview.bundle.js"></script>

<script>
  // ③ 创建实例并打开文件
  const preview = JitWordFilePreview.createFilePreview('#preview-box', {
    onError: (error) => console.error(error.code, error.detail),
  })
  preview.open('https://example.com/report.docx')
</script>

方式一：CDN 单文件（零 CORS，跨域托管推荐）

file-preview.bundle.js 是全量 IIFE 单文件构建（Vue + 八格式渲染引擎 + PDF.js 全部打入，约 13.9MB / gzip 约 4.7MB），运行时零动态 import：经典 <script> 标签跨域加载不受同源策略约束，无需任何 CORS 配置，PDF 渲染 Worker 也内联为 data URL，适合无法设置响应头的静态托管与 CDN 分发。mermaid 图表库（~3MB）不内联其中，而是随 vendor/mermaid.min.js 分发，仅当 MD 文档实际包含 ```mermaid 代码块时才以经典 script 按需注入，同样零 CORS。

<div id="preview-box" style="height: 660px"></div>

<!-- 经典 script 标签：加载完成后全局对象同步可用 -->
<script src="https://jitword.com/preview_sdk/file-preview.bundle.js"></script>

<script>
  // 全局 API 与 ESM 构建完全一致
  const preview = JitWordFilePreview.createFilePreview('#preview-box')
  preview.open('https://example.com/report.docx')
</script>
权衡 单文件首屏即加载全部内容，无按格式分包，体积较大；若宿主与 SDK 同域（或托管方可开放 CORS），推荐下方「方式二」ESM 分块构建按需加载。样式 style.css 由 SDK 基于脚本地址自动注入，同样免 CORS。

方式二：script 标签 + ESM 分块（按需加载）

全局对象 JitWordFilePreview 提供与 ESM 一致的命名导出：createFilePreview / registerFormat / preloadRenderers / setDefaults / setMessages / supportedFormats / version。

说明 引导脚本异步加载 ESM 核心：createFilePreview 同步返回实例代理，open / close / destroy / on 立即可用，核心就绪前的调用会自动排队重放；模块级方法（registerFormat / setDefaults / setMessages / supportedFormats / preloadRenderers）返回 Promise，打开文件前如需注册自定义格式请先 await。

方式三：ESM 直连（script type="module"）

<script type="module">
  import { createFilePreview } from 'https://jitword.com/preview_sdk/file-preview.esm.js'
  const preview = createFilePreview('#preview-box')
  preview.open('https://example.com/report.docx')
</script>

样式默认由 createFilePreview 自动注入 <link>；如需自行管理，可手动引入 style.css 并设置 injectStyle: false。

方式四：打包器（Vite / webpack）

产物为原生 ESM 且按格式分包。可将 dist-sdk 复制进构建产物作为静态资源托管，再 import ESM 入口；或用 assetPath 选项指向托管目录。渲染引擎 chunk 仍走运行时懒加载，不会被静态打进主 bundle。

打开文件与 URL 预览

本地文件（File / Blob / ArrayBuffer）

// File：直接打开（文件名自动取自 file.name）
input.addEventListener('change', (e) => preview.open(e.target.files[0]))

// Blob / ArrayBuffer：第二参数必须传文件名（含扩展名，用于识别格式）
preview.open(blob, '季度报表.xlsx')

远程文件（URL）

// 常规 URL：按扩展名自动识别格式
preview.open('https://example.com/合同.pdf')

// 无法从 URL 识别格式时（如 /download?id=123），显式指定 format
const controller = new AbortController()
preview.open('/api/download?id=123', {
  format: 'pdf',
  fileName: '采购合同.pdf',
  signal: controller.signal,   // 可随时中断下载
  cache: true,                 // LRU 下载缓存，默认开启
})
⚠ CORS URL 预览通过浏览器 fetch 下载，文件服务器必须允许跨域（Access-Control-Allow-Origin），否则报 fetch-failed。同域地址不受此限制。

MD / HTML 格式说明

Markdown（md）

HTML（html）

说明 大图查看器基于预览根的事件委托，覆盖 MD 等 DOM 渲染内容中的 <img>；docx / pptx / xlsx 为 canvas 页渲染、图片不经 DOM，不适用。

配置选项

完整选项表见 API 参考 · FilePreviewOptions。常用组合：

JitWordFilePreview.createFilePreview('#preview-box', {
  toolbar: true,             // 工具栏：翻页 / 缩放 / 全屏
  dropzone: true,            // 空态显示拖拽上传区
  imageLightbox: true,       // 点击图片查看大图（MD 等 DOM 内容）
  formats: ['pdf', 'docx'],   // 收窄格式白名单（默认全部）
  urlCacheBudget: 100 * 1024 * 1024, // URL 缓存预算（字节），0 关闭
  onReady: (info) => console.log('就绪', info.format),
  onError: (error) => console.error(error.code),
  onProgress: (p) => updateLoadingBar(p),
})

事件订阅

const unsubscribe = preview.on('progress', ({ phase, loaded, total }) => {
  if (phase === 'download' && total) {
    setLoading(Math.round(loaded / total * 100))
  }
})

preview.on('pagechange', ({ page, total }) => showPager(page, total))
preview.on('error', ({ code, title, detail }) => toast(title))

unsubscribe() // on() 返回取消函数；也可 preview.off(event, cb)

事件一览：ready（渲染就绪）/ error（失败）/ pagechange（翻页）/ progress（download / inspect / render 三阶段进度）/ statuschange（状态机变化）。详见 API 参考。

错误处理与国际化

所有失败都以结构化错误码通过 error 事件上报（16 个错误码完整列表见 API 参考 · 错误码表），可按 code 定制宿主侧的兜底策略：

preview.on('error', ({ code }) => {
  if (code === 'legacy-doc') guideUserToConvert()   // 旧版 .doc 引导转换
  else if (code === 'fetch-failed') retryDownload()  // 网络 / CORS 失败重试
})

// 文案覆盖 / 国际化
JitWordFilePreview.setMessages({
  'file-too-large': { title: '文件过大', detail: '请上传 50MB 以内的文件' },
})

自定义格式扩展

registerFormat 允许扩展新格式（如 csv / 私有格式），内置格式不可重复注册：

await JitWordFilePreview.registerFormat({
  format: 'csv',
  extensions: ['csv'],
  // 渲染器懒加载入口：默认导出 Vue 组件，props: { source }
  loader: () => import('./csv-renderer.vue'),
  // 可选：自定义内容检查器（默认走 Office zip 结构检查）
  inspect: async (file, signal) => ({
    buffer: await file.arrayBuffer(),
    format: 'csv',
    text: await file.text(),
  }),
})

preview.open('data.csv') // 注册后即可预览

多实例与样式隔离

常见问题

跨域托管 SDK 报 CORS 拦截？

ESM 分块构建通过动态 import() 拉取模块，要求托管方返回 Access-Control-Allow-Origin。若无法配置响应头，请改用 CDN 单文件构建：经典 script 标签不受同源策略约束，零 CORS 即可运行。

双击 HTML 打开报错「无法加载 SDK」？

页面必须通过 HTTP(S) 服务访问，file:// 协议下浏览器禁止加载 ES 模块。用任意静态服务托管即可（如 python3 -m http.server）。

URL 预览报 fetch-failed？

文件服务器未开放 CORS。请为其响应添加 Access-Control-Allow-Origin，或将 SDK 与文件服务部署在同域下。

打开 .doc / .wps 提示不支持？

SDK 面向现代 OOXML 与开放版式格式，旧版二进制格式（.doc / .xls / .ppt）会返回 legacy-doc，建议引导用户转换为新格式。

首次打开格式略慢？

对应格式的渲染引擎 chunk 是首次打开时才按需下载（之后浏览器缓存复用）。可在空闲时调用 preview.preload('all') 或模块级 preloadRenderers(...formats) 预热。

下一步：API 参考 查看在线演示