ofdkit

ofdkit

Vue 3 的 OFD 版式文档预览工具包：左侧目录导航、缩略图侧栏、页面水印、字体兜底、按页懒渲染、文本搜索，功能全部可插拔。渲染内核为 DLTech21/ofd.js（Apache-2.0，源码内置于包内），零外部静态资源、零全局污染。

• 开箱即用：一个 <OfdPreview> 组件就是完整阅读器
• 按页懒渲染：只画视口附近的页，大文档不卡界面
• 左侧栏：图标列常驻（目录 / 缩略图 / 书签 / 文档信息），点图标展开对应面板，再点一次收起；缩略图懒渲染、滚远卸载、当前页高亮、点击跳页
• 目录导航：层级树、可折叠、点击跳页；来源 = ofd:Outlines（书签 ofd:Bookmarks 是独立侧栏面板，不并入目录树，两源并存不重复），条目透出目标视图模式 items[].dest（tooltip 可见），无目录时显示空态
• 文本搜索：全文索引 + 命中高亮 + 上/下一个命中跳转
• 签章透出：每枚章的签名值原始字节 / 签署者证书 / 签名算法值，宿主可验签（onVerifySignature）、可下载
• 链接注释：URI 外链 / Goto 跳页 / GotoA 等动作可点，外链打开方式可接管
• 页面水印：文字/图片、平铺/居中，随内容滚动、可打印
• 主题：亮色 / 暗色 / 跟随系统（只翻外壳，纸张始终白底）
• 可插拔：每个功能都能用 controls 关掉、用 toolbarItems 重排、用插槽替换

目录

• 安装
• 产物形态（默认 / light）
• 快速开始
• Props
• controls 细项开关
• 键盘快捷键
• 文档信息与签章
• 链接注释交互
• 导出当前页 PNG
• 加密 OFD 文件
• 权限控制（permission）
• 工具条编排（toolbarItems）
• 侧边栏（目录 / 缩略图）
• 状态栏编排（statusItems）
• 事件
• 插槽
• 命令式 API
• TypeScript
• 水印
• 全局配置（configureOfdkit）
• 文案定制（messages）
• a11y（无障碍）
• 组合式 API（不依赖完整组件）
• 引擎与许可
• 常见问题

安装

npm install ofdkit
#  运行时依赖：仅 jszip（随包自动安装）
#  peer 依赖：vue ^3.3.0（随宿主项目安装）

包内不依赖任何图标库：内置图标的路径数据已内联（lucide，ISC，见 NOTICE）， 安装时不会把 vue 传递安装给宿主（vue 由宿主自备）。

样式是单独文件，二选一引入：

import 'ofdkit/style.css';

<link rel="stylesheet" href=".../node_modules/ofdkit/dist/ofdkit.css" />

产物形态

dist/ 里有两种形态，默认入口是单文件（zip/XML 解析的 Web Worker 以内联方式打进包内，零配置可用）：

light 形态把两个解析 worker 独立成伴生文件，与 ofdkit.js 同目录、相对定位——把整个 dist/light/ 一起部署即可，无需配置；worker 加载失败（如文件没拷齐）会自动回退主线程解析，功能不损失、只是大文件解析会阻塞 UI。

⚠️ 通过打包器（vite / webpack）使用时请选默认入口：light 的伴生 worker 文件不会被宿主 构建自动带上（除非自行把 worker 文件拷贝到部署根目录），解析会退回主线程（功能不损失， 大文件解析会阻塞 UI）。CDN / 静态部署不受影响。

// light 形态（CDN / 静态部署）
import { OfdPreview } from 'ofdkit/light';
// 样式复用主包的即可（内容一致）：import 'ofdkit/style.css';

快速开始

全局注册 + 按 URL 加载：

// main.js
import { createApp } from 'vue';
import { configureOfdkit, OfdPreview } from 'ofdkit';
import 'ofdkit/style.css';

configureOfdkit({ theme: 'light' }); // 可选：全局默认主题

const app = createApp(App);
app.component('OfdPreview', OfdPreview);
app.mount('#app');

<template>
  <div style="height: 100vh">
    <OfdPreview src="/files/report.ofd" watermark="内部资料" @load="onLoad" />
  </div>
</template>

<script setup>
const onLoad = ({ pageCount, parseMode }) => {
  console.log(`共 ${pageCount} 页，解析路径：${parseMode}`);
};
</script>

按需局部注册（推荐，tree-shaking 更干净）：

<script setup>
import { OfdPreview } from 'ofdkit';
import 'ofdkit/style.css';
</script>

<template>
  <OfdPreview src="/files/report.ofd" />
</template>

加载本地文件（File / ArrayBuffer）：

<template>
  <OfdPreview ref="viewer" />
  <button @click="pick">打开 OFD</button>
</template>

<script setup>
import { ref } from 'vue';
import { OfdPreview } from 'ofdkit';

const viewer = ref();

function pick() {
  const input = document.createElement('input');
  input.type = 'file';
  input.accept = '.ofd';
  input.onchange = async () => {
    const file = input.files?.[0];
    if (file) await viewer.value.openBytes(await file.arrayBuffer(), file.name);
  };
  input.click();
}
</script>

src 需要同源 URL（或目标服务端已开 CORS）。拖拽打开（controls.dragDrop）默认开启。

Props（<OfdPreview>）

controls 细项开关

默认值取向是「库形态」：渲染相关都开，诊断类默认关。宿主只传差异项：

<OfdPreview :controls="{ print: false, diagnostics: true }" />

开关对命令式入口同样生效：api.print() / api.openFile() 在被对应开关关闭时不执行任何操作并 console.warn（不再是「UI 隐藏了但 api 仍能执行」）。print / openFile 是数据与输出入口，属安全相关。

controls 里的未知键会被丢弃并告警（防 :controls="{ serach: false }" 这类拼错静默失效）。

源地址默认脱敏：状态栏 source 段与 getState() 里的源地址只保留 origin + 文件名， 去掉可能携带 ?token= / ?sign= 的 query；需要完整 URL 用 configureOfdkit({ exposeSourceUrl: true })。

键盘快捷键

内置一套文件级快捷键。监听在 document 上，但只在「焦点在本查看器内」时生效 —— 同页多个查看器只有被点过的那个响应。输入框里的按键一律不劫持。

快捷键走静默门控：对应开关关掉时按键无反应，不 console.warn、不抛 @capability-denied （长按不会刷屏）。不劫持纯方向键 —— 本组件是滚动容器，↑↓←→ 的原生滚动必须保留。

文档信息与签章

左侧栏第 4 个图标「文档信息」（受 controls.documentInfo 门控）：面板内是元数据 + 签章卡片 （印章图、验签标签、签署时间、签名方式、覆盖页、签名值/证书原始字节大小）； 也可用 api.showDocumentInfo() / api.showDocInfo() 打开、getState().documentInfo / .signatures 读数据。

<OfdPreview :controls="{ documentInfo: false }" />   <!-- 整块关掉（状态栏段与面板都不出现） -->
<OfdPreview :controls="{ docinfoMeta: false }" />    <!-- 只关元数据块，签章块保留 -->
<OfdPreview :controls="{ docinfoSignatures: false }" /> <!-- 只关签章块（头部计数与验签提示一并隐藏） -->

面板整体也可用 #docinfo 插槽替换（作用域：documentInfo / signatures / downloadSignature / state / api）：

<OfdPreview :controls="{ documentInfo: true }">
  <template #docinfo="{ documentInfo, signatures }">
    <MyDocInfoPanel :info="documentInfo" :sigs="signatures" />
  </template>
</OfdPreview>

侧栏版签章卡是上下布局：印章大图（92px 高、按原始比例完整呈现）居中在上，印章名与验签标签居中， 明细行（提供方 / 签署时间 / 签名方式 / 覆盖页 / 字节大小）左对齐铺满整行。

• 元数据来自 Document.xml 的 DocumentInfo：标题 / 作者 / 主题 / 生成工具 / 创建与修改时间 / 自定义标签。 ⚠️ 多数业务文件没有该节点 ⇒ 字段可能全空，这不代表文件异常，面板会给兜底文案。
• 签章列出每枚章的印章名、印章图片、签署时间、签名方式与覆盖页，并给出签名值原始字节： signedValue（逐字节等于 zip 内的 SignedValue.dat 全文）、签署者证书 signerCert 与签名算法值 signatureValue（三份都是 Uint8Array）。签章卡上显示字节数并提供下载按钮（复用 controls.download 门控，同时抛 @download-signature）；命令式入口 api.getSignatures() / api.downloadSignature(id)。
• ⚠️ 库内不做验签（与「不做鉴权」同一条线）：引擎的 verificationStatus 恒为 not-verified， 但宿主可以接入自己的验签——configureOfdkit({ onVerifySignature })，回调签名 (record, originalBytes) => { status, detail }，record 即上面那条含三份原始字节的记录。 返回的 status 会替换面板上的「未验签」标签（'valid' / 'invalid' 有内置样式，其余原样显示）； 不配置 / 返回空 ⇒ 维持「未验签」。换文档后迟到的结论一律丢弃，结论同步进 getState().signatureVerifications（{ id, status, detail }）。

宿主自定义：读 getState().signatures（含三份原始字节）自行渲染；#toolbar-info 插槽可以放自己的验签结论。

链接注释交互

OFD 里的 Link / Action 注释（挂在正文图元或注释容器上的 URI / Goto / GotoA / Sound / Movie / Goto→Bookmark 动作）默认可点。引擎把带动作的图元/注释摊平成 data-ofd-* 标记挂到页面 DOM 上， 并提供可枚举的 annotations() 契约（宿主不必刮 DOM）；点击由壳侧在页面容器上统一委托处理。

• 只认 Event="CLICK"：DO / PO（打开文档 / 页面时自动触发的动作）会出现在 annotations() 清单里， 但不挂手势、不静默执行。
• ⚠️ 具名 Bookmark 跳转暂不支持（点击只抛事件）。@annot-activate 在默认行为之外抛出，载荷 { kind, pageIndex, pageId, annotType, element, uri?, target?, dest?, bookmarkName? }，宿主可观测 / 审计 / 整体接管。
• 视觉只加 cursor:pointer 与 title，不改 appearance（版式保真优先）。

<!-- 只读标记、不挂手势（DOM 上仍有 data-ofd-* 属性） -->
<OfdPreview :controls="{ linkAnnotations: false }" />

<!-- 审计或接管外链 -->
<OfdPreview @annot-activate="({ kind, uri }) => track(kind, uri)" />

configureOfdkit({
  // 函数 = 宿主接管（自建跳转 / 审计 / 兜底浏览器）；false = 一律禁止跳转（只抛事件）
  openExternalLink: (uri, target) => myRouter.open(uri, target),
});

导出当前页 PNG

把任意一页离屏光栅化为 PNG（100% 基准 × scale），两条入口：

// ① 命令式：index 0 起；返回 { blob, width, height, name } 或 null（文档未开 / 门控拒绝 / 渲染失败）
const out = await viewer.value.exportPage(0, { scale: 2 });   // scale 默认 2，护栏 [0.25, 8]
// out.blob 是 image/png Blob；name 形如 '51637-p1.png'

// ② save: false = 只出 Blob 不存盘、不抛事件（宿主自己决定怎么用）
const raw = await viewer.value.exportPage(4, { save: false });

工具条「导出当前页 PNG」按钮（受 controls.export 门控）存盘当前页并抛 @export-page （{ index, name, width, height, byteLength }，1 起页码）——库已自行存盘，宿主可换成 自己的保存方式（入库 / 走服务端）：

<OfdPreview @export-page="({ name, byteLength }) => track(name, byteLength)" />

实现要点与边界：

加密 OFD 文件

打开加密 OFD 时（jszip 不支持加密 zip，解析在 loadAsync 阶段即失败），库明确分类而不是 落进通用的「打开失败」：主体区显示加密态卡片（#encrypted 插槽可整体替换），不抛 @error。

• 库内不做密码学：没有密码框、不存密码、不弹对话框（与「不做鉴权」同一条线）。
• 解密由宿主接入：configureOfdkit({ decryptProvider }) —— (bytes) => plainBytes，把加密字节 解成明文 zip 字节（ArrayBuffer / Uint8Array / Blob 均可）返回；返回 null / 抛错 = 解锁失败（卡片内联提示，可重试）。成功后原地重开，无感衔接。

configureOfdkit({
  decryptProvider: async (bytes) => {
    const plain = await myServer.decrypt(bytes);   // 解密放服务端 / 专用 SDK，别在前端放密钥
    return plain;                                   // 明文 zip 字节；失败返回 null 或抛错
  },
});

没有配置 decryptProvider 时只显示加密提示，不给解锁按钮（宿主可在 #encrypted 插槽里 自建任何解锁 UI，作用域参数：file-name, reason, error, busy, can-unlock, unlock）。

权限控制（permission）

⚠️ 本包不做鉴权：库内不认用户身份、不调权限服务、不存 token，也无法阻止用户直接访问原始 URL。 真正的准入必须在服务端（文件接口鉴权 / 签名 URL）。permission 解决的是客户端这一侧必须做对的三件事： ① 无权时不发出请求（省一次注定 403 的往返，也不泄露「这个 URL 存在」）；② 无权时不把数据搬进内存与 DOM； ③ 权限在运行中变化（异步到位 / 被回收）时，界面与内存同步收敛。

<!-- 全放行（默认，与不传等价） / 全拒绝 -->
<OfdPreview src="/f/a.ofd" :permission="true" />
<OfdPreview src="/f/a.ofd" :permission="false" />

<!-- 只写要拒的能力键（其余放行）；可带展示文案与异步裁决器 -->
<OfdPreview :permission="{ print: false, reason: '当前角色无打印权限' }" />
<OfdPreview :permission="{ resolver: () => authApi.check(), fallback: 'deny' }" />

能力 id 与 controls 键同名（另有主闸门 view）：view / toolbar / sidebar / openFile / download / dragDrop / outline / outlineCollapse / thumbnails / watermark / zoom / search / paging / print / documentInfo / linkAnnotations / statusBar / diagnostics。合成是 controls ∧ permission （deny-wins：任一来源说「不」就是「不」），只需改一处，工具条 / 侧栏 / 搜索 / 打印全部自动跟随。

三态：pending（异步裁决中，渲染骨架屏 —— 还没裁决就报无权限 = 误伤）/ denied（无权限态）/ allowed。 pending 期间不发请求；裁决为 allowed 后自动续跑被挂起的加载。view 被拒时整壳替换为无权限态 （#denied 插槽可整体替换），此时数据入口已全部拦下（无请求、无解析、无页面 DOM）。

<OfdPreview :permission="perm">
  <template #denied="{ permission, reason, retry, requestAccess }">
    <MyDeniedCard :reason="reason" @retry="retry" @apply="requestAccess" />
  </template>
</OfdPreview>

被回收（allowed → denied）时：清空本实例的 DOM 与数据（调度器 / 页面 / 目录 / 搜索 / 统计）， 但不清理同页多实例共用的解析缓存与 worker —— 清理属宿主决策。 重新授权（denied → allowed）默认不自动加载；无权限卡上的「重试」会重跑裁决并在放行后补一次加载。

不做：库内鉴权 / token 存储刷新 / 401 拦截 / 页级·行级权限 / 新增 provide-inject 或全局 store。

工具条编排（toolbarItems）

内置项用 key 引用，可局部覆盖（只改标题/图标，不动行为）；自定义项用 type: 'custom'；另支持 spacer（弹性占位，把后续项推到右侧）与 separator（分隔线）：

<OfdPreview
  :toolbar-items="[
    { key: 'open-file' },
    { type: 'spacer' },
    { key: 'zoom', title: '缩放' },
    { type: 'separator' },
    { key: 'print' },
    { type: 'custom', key: 'sign', title: '验签', icon: 'shield', onClick: () => verify() },
  ]"
/>

内置 key：open-file / search / zoom-out / zoom / zoom-in / first / prev / page-info / next / last / print。 自定义项可传 icon（内置图标名）或 component（Vue 组件），点击后同时广播 action 事件，方便统一埋点。

侧栏交互（目录 / 缩略图）不走工具条：侧栏左侧有一列常驻图标，点图标展开对应面板、再点一次收起。整栏的显隐与面板切换见下文「侧边栏」。 水印同样不占工具条位：它是宿主配置驱动的（:watermark），运行期开关用 api.toggleWatermark() / api.setWatermark()。

侧边栏（目录 / 缩略图）

左侧栏采用 WPS 式图标列：最左一列常驻图标，点图标展开对应面板，再点一次同一个图标收起面板区（图标列不消失）；展开态点另一个图标 = 切换面板。

侧栏是三层可插拔，宿主可以逐层控制：

侧栏任何显隐/切换都会广播 sidebar-change 事件（{ open, panel }），方便宿主同步状态或持久化用户偏好：

<OfdPreview
  :default-sidebar-tab="'thumbnails'"
  :default-sidebar-open="false"
  @sidebar-change="({ open, panel }) => save({ open, panel })"
/>

缩略图面板本身：每页一张小图 + 页码角标、懒渲染（只画视口附近的）、滚远自动卸载、当前页高亮并自动滚进视野、点击跳页。面板常驻 DOM（v-show），切走再切回保留滚动位置。

状态栏编排（statusItems）

内置段 id：page-count / document-info / render / outline / page-map / fonts / engine / page-metrics / zoom / parse-cost / source / notice / warnings。

其中 page-count 与 document-info 不受 controls.diagnostics 门控（前者是页数、后者是签章与元数据，都是业务读者要看的），document-info 另有自己的 controls.documentInfo。

<OfdPreview :status-items="['page-count', 'zoom', 'source']" />

事件

插槽

区域级插槽一律给全量 state + api（与模板 ref 的公开面同源）；面板内的分段插槽额外附加该段的参数：

命令式 API

通过模板 ref 调用（也可从任意插槽的 api 作用域参数取得同一对象）：

const viewer = ref();

viewer.value.goToPage(5);
viewer.value.search('合计');          // 打开搜索条并执行
viewer.value.setWatermark({ text: '新水印' });
viewer.value.toggleWatermark(false);  // 临时关闭
const { pageIndex, pageCount } = viewer.value.getState();

模板 ref 的公开面与 api 一致：下表所有方法（含 openFile / reload / zoomIn / collapseAll …） 都可直接挂在 ref 上调用，viewer.value.openFile() 与 viewer.value.api.openFile() 等价。 另有 getState() / getMainEl() 两个不在 api 里的辅助方法。

TypeScript

包内自带类型声明（dist/types/），exports 的 types 条件已接好，import { OfdPreview } from 'ofdkit' 开箱有补全：

import OfdPreview from 'ofdkit';
import type { OfdPreviewApi, OfdViewerState, OfdSignature, OfdControls } from 'ofdkit';

const viewer = ref<InstanceType<typeof OfdPreview>>();
const api: OfdPreviewApi = viewer.value!.api;
const state: OfdViewerState = viewer.value!.getState();
const seals: OfdSignature[] = state.signatures;

• props 有约束（含 theme / defaultSidebarTab 这类字面量联合）、事件有载荷类型（@load / @download …）、 模板 ref 上的 api 与 getState() 都有类型。
• 导出类型：OfdControls / OfdPreviewProps / OfdPreviewEmits / OfdPreviewApi / OfdViewerState / OfdSignature / OfdSignatureVerification / OfdAnnotActivatePayload / OfdDocumentInfo / OfdPermissionInput，以及各独立组件的 XxxProps / XxxEmits。
• ⚠️ 插槽作用域参数不会被 h() / JSX 自动推导（Vue 的类型机制所限），需要时用导出的 OfdPreviewSlots 等接口显式标注。

水印

三种写法，语义是「宿主叠加的水印」——OFD 文件自带的那个水印由引擎从文档注释渲染，本包不碰它：

<OfdPreview :watermark="'内部资料'" />                      <!-- 快捷文字水印 -->
<OfdPreview :watermark="{ text: '内部资料', opacity: 0.2, rotate: -30 }" />
<OfdPreview :watermark="false" />                          <!-- 关闭 -->

要完全自定义 page 水印的形态，用 render 回调自建节点（页面 DOM 由引擎创建，不支持 Vue 插槽）：

:watermark="{ text: '内部资料', render: (pageEl, ctx) => { /* 返回 HTMLElement */ } }"

全局配置（configureOfdkit）

基础预览不需要任何配置。需要时在应用启动早期调用一次：

import { configureOfdkit } from 'ofdkit';

configureOfdkit({
  theme: 'auto',
  workerParse: true,
  fontBase: '/static/ofd-fonts',
  fontSlots: [
    { id: 'xiaobiaosong', label: '小标宋',
      system: ['FZXiaoBiaoSong-B05S', '方正小标宋简体'],
      keywords: ['xiaobiaosong', '小标宋'] },
  ],
});

文案定制

库的全部用户可见 UI 文案（工具条 / 搜索条 / 目录 / 状态栏与诊断 / 文档信息与签章 / 空态加载错误 / 加密态 / 权限态等约 110 键）都集中在默认文案表，可逐键覆盖、不做 i18n （OFD 是国标、受众中文，真实需求是术语可换而非多语言）：

// 全局层：所有实例生效
configureOfdkit({ messages: { 'toolbar.print': '打印文档', 'outline.empty': '本文件没有目录' } });
// 组件层（优先于全局层）
<OfdPreview :messages="{ 'outline.title': '书签' }" />

• 占位符 {n} 形式（如 'outline.pageLabel': '第 {n} 页'），覆盖时保留占位符即可；
• 未知键丢弃 + 控制台告警（同键只告警一次）；
• 三层优先级：messages prop > configureOfdkit({ messages }) > 默认表。

a11y（无障碍）

• 翻页区 role="region"（可聚焦，PageUp/PageDown 与方向键翻页见「键盘快捷键」）；
• 目录树 role="tree" / treeitem，当前项 aria-current，禁用项 aria-disabled；
• 诊断抽屉与文档信息浮层 role="dialog" + aria-modal + 焦点圈定（打开移焦、Tab 循环、关闭归还）；
• 工具条与侧栏图标列支持方向键移动焦点（roving）。
• 上述区域语义标签同样走文案表（a11y.* 键）。

组合式 API（不依赖完整组件）

以下能力可单独引入，用于自建界面：

import {
  parseOfdOutline,      // 目录解析（worker 优先，失败自动回退主线程）
  createPageScheduler,  // 按页懒渲染调度器
  OfdToolbar,           // 工具条组件（可被 OfdPreview 的 #toolbar 插槽复用）
  OfdOutlinePanel,      // 目录面板组件
  OfdIcon,              // 图标组件（内置图标名 + 宿主原始 SVG 字符串）
  normalizeWatermark,   // 水印配置归一化
  applyWatermarkToPages,// 往页面节点批量挂水印
  ENGINES,              // 引擎注册表
} from 'ofdkit';

开发 / 贡献

源码、测试与开发文档在仓库内（不随 npm 包发布）。

引擎与许可

• 本库代码 MIT；渲染内核 DLTech21/ofd.js 为 Apache-2.0（源码内置，声明见包内 NOTICE）； 图标图形来自 lucide（ISC），仅内联其路径数据，不随包引入 lucide 依赖。
• 当前内置唯一引擎 dltech。ENGINES 注册表开放扩展：实现引擎契约即可换成自己的渲染内核。
• 已知边界：JPX（JPEG2000）内嵌图与 OFD 内嵌字体文件暂不支持解码（终端系统字体齐全时无感知）；跨 TextObject / 跨行的连续选择与搜索暂不支持；多 Document 文件只渲染第 1 个（状态栏会明示）。

常见问题

文件在服务端被更新后，重新打开还是旧内容？ 库内对目录解析只做「在途去重」（并发加载共享一次解析，完成后即弃），不做跨次打开的持久缓存； src 加载走协商缓存（有 ETag 时 304 省流量，否则回源）。api.reload() 会真正重新拉取解析。 若仍看到旧内容，检查服务端 / CDN 的缓存策略（或给 URL 加版本参数）。

文字显示不正确 / 缺字？ OFD 引用的是「宋体 / 黑体 / 楷体」等逻辑字体名，实际显示取决于终端系统字体。内网 Windows 一般齐全；缺字体时用 fontBase 指向自备字体目录，或用 fontSlots 注入内部字库。

搜索不到跨行的内容？ 搜索基于引擎抽取的文本段（按行合并）。跨 TextObject、跨行的连续文本暂不在索引范围内。

打印样式与屏幕不一致？ 打印会先渲染全部页再克隆 DOM，-webkit-font-smoothing 等观感项在不同浏览器可能有差异；打印走独立打印窗口，字体栈为行内样式不受影响。

一个页面放两个查看器？ 支持。组件不写 window、不注入全局 CSS、类名统一 ofd- 前缀，多实例互不干扰。