API 参考

全局对象 JitWordFilePreview（script 标签）与 ESM 入口 file-preview.esm.js 提供完全一致的导出： createFilePreview / registerFormat / preloadRenderers / setDefaults / setMessages / supportedFormats / version。

createFilePreview(container, options?)

const preview = JitWordFilePreview.createFilePreview(container, options?)

参数	类型	说明
`container`	`HTMLElement \| string`	挂载容器或 CSS 选择器。容器未设置高度时默认给 `560px`
`options`	`FilePreviewOptions`	可选，见下表

返回值：预览实例。script 标签接入时引导脚本尚未加载完成也同步返回实例代理——ESM 核心就绪前的 open / close / destroy / on 调用会自动排队，核心就绪后按序重放。

配置选项 FilePreviewOptions

选项	类型	默认	说明
`toolbar`	`boolean`	`true`	是否显示工具栏（翻页 / 缩放 / 全屏）
`dropzone`	`boolean`	`false`	空态是否显示拖拽上传区
`imageLightbox`	`boolean`	`true`	点击图片查看大图（缩放 / 平移 / 多图切换）；覆盖 MD 等 DOM 渲染内容中的 `<img>`，docx / pptx / xlsx 为 canvas 页渲染不适用
`formats`	`string[]`	全部	收窄格式白名单（内置：`docx` / `xlsx` / `pptx` / `ofd` / `pdf` / `txt` / `md` / `html`）
`assetPath`	`string`	自动探测	SDK 静态资源目录；目录原样托管时无需配置
`injectStyle`	`boolean`	`true`	是否自动注入 `style.css`
`urlCacheBudget`	`number`	`100 * 1024 * 1024`	URL 下载结果 LRU 缓存预算（字节），`0` 关闭缓存
`onReady`	`(info) => void`	—	渲染就绪回调，等价 `on('ready')`
`onError`	`(error) => void`	—	错误回调，等价 `on('error')`
`onPageChange`	`(info) => void`	—	翻页回调，等价 `on('pagechange')`
`onProgress`	`(info) => void`	—	进度回调，等价 `on('progress')`

全局默认值可通过 setDefaults(options) 设置，实例选项优先。

实例方法

方法	说明
`open(input, nameOrOptions?)`	打开文件。`File` 直接打开；`Blob` / `ArrayBuffer` 第二参数须为文件名（含扩展名）；`string` 按 URL 处理，第二参数为 UrlOpenOptions。返回 `Promise<void>`；新的 `open` 会抢占中断上一次未完成的打开
`preload(...formats)`	预热渲染引擎 chunk；传 `'all'` 预热全部已注册格式
`close()`	关闭当前文档回到空态（实例保留，可继续 `open`）
`destroy()`	卸载实例：Vue 卸载、DOM 清理、下载中断；之后调用其他方法会抛错
`on(event, cb)` / `off(event, cb)`	订阅 / 取消订阅事件；`on` 返回取消函数

URL 打开选项 UrlOpenOptions

open(url, options) 的第二参数：

选项	类型	默认	说明
`format`	`string`	—	URL 无法识别格式时必传（如 `/download?id=123`）
`fileName`	`string`	自动	覆盖文件名；默认取 `Content-Disposition`，其次 URL 路径名
`signal`	`AbortSignal`	—	中断信号，中断后以 `fetch-aborted` 失败
`cache`	`boolean`	`true`	是否使用下载缓存（LRU，预算见 `urlCacheBudget`）

⚠ CORS URL 预览通过浏览器 fetch 下载，文件服务器必须允许跨域（Access-Control-Allow-Origin），否则报 fetch-failed。同域地址不受此限制。

事件

const off = preview.on('ready', ({ format, fileName }) => { /* ... */ })
off() // 取消订阅

事件	载荷	触发时机
`ready`	`{ format, fileName }`	文档渲染就绪
`error`	`{ code, title, detail }`	校验 / 下载 / 渲染失败（code 见错误码表）
`pagechange`	`{ page, total }`	翻页（PDF / OFD 等分页格式）
`progress`	`{ phase, loaded?, total? }`	`phase` 为 `download`（带字节进度）/ `inspect` / `render`
`statuschange`	`string`	会话状态机变化

错误码表

所有失败以结构化错误码通过 error 事件上报；文案可通过 setMessages 覆盖或国际化。

code	含义
`unsupported-extension`	文件格式不受支持
`legacy-doc`	检测到旧版 Word 文档（.doc）
`file-too-large`	文件超过 50 MB
`text-file-too-large`	文本文件超过 10 MB
`text-invalid`	文本内容无法安全解析
`invalid-package`	压缩包内容非法
`package-type-mismatch`	文件扩展名与内容不一致
`zip64-unsupported`	使用了暂不支持的 Zip64 格式
`unsafe-package`	文件未通过安全检查
`document-too-complex`	文档结构过于复杂
`layout-incompatible`	文档版式暂不兼容
`renderer-failed`	文档无法完成渲染
`url-scheme-unsupported`	仅支持 http/https 链接
`fetch-failed`	文件下载失败（网络 / CORS）
`fetch-aborted`	文件下载被中断
`url-format-unknown`	无法识别链接中的文件格式（请传 `format`）

registerFormat

注册自定义格式渲染器（内置格式不可重复注册）。script 标签接入时返回 Promise，打开对应格式文件前请先 await。

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

字段	类型	必填	说明
`format`	`string`	是	格式标识，全局唯一
`extensions`	`string[]`	是	关联扩展名（不含点号）
`loader`	`() => Promise`	是	渲染器懒加载入口，默认导出 Vue 组件，接收 `props: { source }`
`inspect`	`(file, signal) => Promise`	否	自定义内容检查器；省略时走默认 Office zip 结构检查

模块级 API

API	说明
`setDefaults(options)`	全局默认配置，实例选项优先
`setMessages(messages)`	覆盖 / 扩展错误文案：`{ [code]: { title?, detail? } }`
`supportedFormats()`	当前已注册格式列表
`preloadRenderers(...formats)`	模块级预热渲染引擎（不需实例）
`version`	SDK 版本号

提示 script 标签接入时，模块级方法（setDefaults / setMessages / supportedFormats / preloadRenderers / registerFormat）均返回 Promise；仅实例代理方法（open / close / destroy / on / off / preload）同步可用并自动排队。

返回接入指南查看在线演示