@ycsx/ofdjs

一个用于读取和渲染OFD（开放式文档格式）文件的JavaScript库。

功能特性

📄 OFD 文档解析 - 完整支持OFD格式文件的解析和加载
🎨 文档渲染 - 支持多种渲染模式（Template、PathContent）
📐 缩放控制 - 灵活的页面缩放功能
✍️ 签名验证 - 支持OFD电子签名的验证
🖼️ JBIG2支持 - 支持JBIG2压缩图像
🔧 丰富的API - 提供灵活的编程接口

安装

使用npm安装：

npm install @ycsx/ofdjs

或使用yarn：

yarn add @ycsx/ofdjs

快速开始

基础使用

import { parseOfdDocument, renderOfd } from '@ycsx/ofdjs';

// 1. 解析OFD文件
parseOfdDocument({
  ofd: 'path/to/file.ofd',  // 文件路径、File对象或ArrayBuffer
  success: (ofdDocument) => {
    console.log('解析成功', ofdDocument);
    
    // 2. 渲染文档到页面
    const screenWidth = window.innerWidth;
    const pages = renderOfd(screenWidth, ofdDocument[0]);
    
    // 3. 添加到DOM
    pages.forEach(pageDiv => {
      document.getElementById('container').appendChild(pageDiv);
    });
  },
  fail: (error) => {
    console.error('解析失败', error);
  }
});

使用缩放功能

import { parseOfdDocument, renderOfdByScale, setPageScale, getPageScale } from '@ycsx/ofdjs';

// 设置缩放比例（1.0 = 100%）
setPageScale(1.2);

parseOfdDocument({
  ofd: file,
  success: (ofdDocument) => {
    // 根据设置的缩放比例渲染
    const pages = renderOfdByScale(ofdDocument[0]);
    document.getElementById('container').appendChild(...pages);
  }
});

// 获取当前缩放比例
console.log('Current scale:', getPageScale());

原生 HTML 中使用

仓库里的 examples/basic.html 就是一个完整的原生浏览器示例。它演示了：

选择本地 OFD 文件
调用 parseOfdDocument() 解析文档
使用 renderPage() 渲染当前页
使用 calPageBox() 计算页面尺寸
手动实现分页与缩放

如果你是直接引用源码入口，推荐这样写：

<script type="module">
  import { parseOfdDocument, renderPage, calPageBox } from '../index.js';

  let currentDocument = null;
  let currentPageIndex = 0;
  let currentScale = 1;

  function getOFDDocument() {
    return currentDocument?.document || currentDocument;
  }

  function getRenderWidth() {
    const container = document.getElementById('ofdContainer');
    return Math.max((container.clientWidth || 1024) * currentScale, 320);
  }

  function renderCurrentPage() {
    const container = document.getElementById('ofdContainer');
    container.innerHTML = '';

    if (!currentDocument?.pages?.length) return;

    const doc = getOFDDocument();
    const page = currentDocument.pages[currentPageIndex];
    const box = calPageBox(getRenderWidth(), doc, page);

    const pageDiv = document.createElement('div');
    pageDiv.style.cssText = `
      position: relative;
      width: ${box.w}px;
      height: ${box.h}px;
      background: white;
    `;

    renderPage(
      pageDiv,
      page,
      currentDocument.tpls,
      currentDocument.fontResObj,
      currentDocument.drawParamResObj,
      currentDocument.multiMediaResObj
    );

    container.appendChild(pageDiv);
  }

  document.getElementById('ofdInput').addEventListener('change', (event) => {
    const file = event.target.files?.[0];
    if (!file) return;

    parseOfdDocument({
      ofd: file,
      success: (ofdDocument) => {
        currentDocument = ofdDocument;
        currentPageIndex = 0;
        currentScale = 1;
        renderCurrentPage();
      },
      fail: (error) => {
        console.error('文件解析失败', error);
      }
    });
  });

  document.getElementById('scaleInput').addEventListener('input', (event) => {
    currentScale = Number(event.target.value) / 100;
    if (currentDocument) renderCurrentPage();
  });
</script>

如果你想直接使用打包后的 dist/ofd.min.js，则不要用 import，而是用普通 <script> 引入后从全局对象取 API：

<script src="../dist/ofd.min.js"></script>
<script>
  const { parseOfdDocument, renderPage, calPageBox } = window.OFD;
</script>

在 Vue 3 中使用

仓库里的 examples/vue/3/src/vue-viewer.vue 是一个 Vue 3 的集成示例。组件方式的核心思路是：

用 ref 保存加载状态、错误信息、文件信息和页面容器
在 change 事件里调用 parseOfdDocument()
解析成功后使用 renderOfd() 生成页面 DOM
把生成的页面元素挂到 ref 容器里

示例代码如下：

<template>
  <div class="ofd-viewer">
    <div class="controls">
      <input
        type="file"
        accept=".ofd"
        @change="handleFileChange"
        :disabled="loading"
      />
      <button v-if="fileInfo" @click="handleClear">清空文档</button>
    </div>

    <div v-if="loading">正在加载...</div>
    <div v-if="error">{{ error }}</div>

    <div v-if="fileInfo">
      <p><strong>文件名:</strong> {{ fileInfo.name }}</p>
      <p><strong>页数:</strong> {{ fileInfo.pageCount }}</p>
      <p><strong>大小:</strong> {{ formatSize(fileInfo.size) }}</p>
    </div>

    <div ref="containerRef" class="viewer">
      <div ref="pageRef"></div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { parseOfdDocument, renderOfd } from '@ycsx/ofdjs';

const loading = ref(false);
const error = ref(null);
const fileInfo = ref(null);
const containerRef = ref(null);
const pageRef = ref(null);
const pageElements = ref([]);

const formatSize = (bytes) => {
  if (bytes === 0) return '0 B';
  const k = 1024;
  const sizes = ['B', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
};

const handleFileChange = (event) => {
  const file = event.target.files?.[0];
  if (!file) return;

  pageElements.value = [];
  pageRef.value.innerHTML = '';
  loading.value = true;
  error.value = null;

  parseOfdDocument({
    ofd: file,
    success: (ofdDoc) => {
      const screenWidth = containerRef.value?.offsetWidth || 1024;
      pageElements.value = renderOfd(screenWidth, ofdDoc[0]);
      pageElements.value.forEach((element) => pageRef.value.appendChild(element));
      fileInfo.value = {
        name: file.name,
        pageCount: ofdDoc[0]?.pages?.length || 0,
        size: file.size,
      };
      loading.value = false;
    },
    fail: (err) => {
      error.value = err.message || '文件加载失败';
      loading.value = false;
    },
  });
};

const handleClear = () => {
  pageElements.value = [];
  fileInfo.value = null;
  error.value = null;
  pageRef.value.innerHTML = '';
};
</script>

说明：Vue 3 示例目前以“加载后一次渲染页面”为主，后续如果需要分页、缩放、单页预览等交互，可以在这个模板基础上继续扩展。

React 和 Vue 2 的示例会在后续补充。

API 文档

parseOfdDocument(options)

解析OFD文档文件。

参数：

参数	类型	描述
`options`	Object	配置对象
`options.ofd`	string \| File \| ArrayBuffer	OFD文件源（文件路径、File对象或二进制数据）
`options.success`	Function	成功回调，接收解析后的文档对象
`options.fail`	Function	失败回调，接收错误对象

返回值： 无

示例：

parseOfdDocument({
  ofd: fileInput.files[0],
  success: (document) => {
    console.log('页数:', document.pages.length);
  },
  fail: (error) => {
    console.error('错误:', error);
  }
});

renderOfd(screenWidth, ofdDocument)

根据指定宽度渲染OFD文档，返回DOM页面数组。

参数：

参数	类型	描述
`screenWidth`	number	页面显示宽度（像素）
`ofdDocument`	Object	通过 `parseOfdDocument` 获得的文档对象

返回值： Array<HTMLDivElement> - 页面DOM元素数组

示例：

const pages = renderOfd(1024, ofdDocument);
pages.forEach(pageDiv => {
  // 每个pageDiv包含一个页面
  console.log('页面ID:', pageDiv.id);
  container.appendChild(pageDiv);
});

renderOfdByScale(ofdDocument)

根据设置的缩放比例渲染OFD文档。需先使用 setPageScale() 设置缩放值。

参数：

参数	类型	描述
`ofdDocument`	Object	通过 `parseOfdDocument` 获得的文档对象

返回值： Array<HTMLDivElement> - 页面DOM元素数组

示例：

setPageScale(1.5);  // 150%
const pages = renderOfdByScale(ofdDocument);

setPageScale(scale)

设置全局页面缩放比例。

参数：

参数	类型	描述
`scale`	number	缩放比例（1.0 = 100%，可设置0.5-2.0之间的值）

返回值： 无

示例：

setPageScale(0.8);   // 80%
setPageScale(1.2);   // 120%

getPageScale()

获取当前设置的缩放比例。

参数： 无

返回值： number - 当前缩放比例

示例：

const currentScale = getPageScale();
console.log(`当前缩放: ${currentScale * 100}%`);

calPageBox(screenWidth, document, page)

计算页面在指定屏幕宽度下的尺寸。

参数：

参数	类型	描述
`screenWidth`	number	屏幕宽度（像素）
`document`	Object	OFD文档对象
`page`	Object	页面对象

返回值： Object - 包含 w（宽度）和 h（高度）的对象

示例：

const box = calPageBox(1024, ofdDocument.document, ofdDocument.pages[0]);
console.log(`页面尺寸: ${box.w}x${box.h}`);

calPageBoxScale(document, page)

根据设置的缩放比例计算页面尺寸。

参数：

参数	类型	描述
`document`	Object	OFD文档对象
`page`	Object	页面对象

返回值： Object - 包含 w（宽度）和 h（高度）的对象

示例：

setPageScale(1.2);
const box = calPageBoxScale(ofdDocument.document, ofdDocument.pages[0]);
console.log(`缩放后页面尺寸: ${box.w}x${box.h}`);

renderPage(pageDiv, page, templates, fonts, drawParams, multiMedia)

在指定的DOM元素中渲染单个页面。（高级API，通常无需直接调用）

参数：

参数	类型	描述
`pageDiv`	HTMLDivElement	页面容器DOM元素
`page`	Object	页面对象
`templates`	Object	页面模板资源
`fonts`	Object	字体资源
`drawParams`	Object	绘制参数
`multiMedia`	Object	多媒体资源

返回值： 无

错误处理

parseOfdDocument({
  ofd: file,
  success: (document) => {
    console.log('解析成功');
  },
  fail: (error) => {
    // 常见错误类型
    if (error.message.includes('not a valid zip')) {
      console.error('不是有效的OFD文件');
    } else if (error.message.includes('XML parse')) {
      console.error('文档结构错误');
    } else {
      console.error('未知错误:', error);
    }
  }
});

支持的OFD版本

OFD 1.0
OFD 1.2

浏览器兼容性

浏览器	最低版本	备注
Chrome	50+	✅ 完全支持
Firefox	45+	✅ 完全支持
Safari	10+	✅ 完全支持
Edge	15+	✅ 完全支持
IE	不支持	❌ 需要使用polyfills

注：需要支持 ES6 Module 和 Promise。如需支持IE11，请使用相应的polyfills。

依赖项

jszip - ZIP文件解析
@xmldom/xmldom - XML解析
jsrsasign - 数字签名验证
js-sha1 - SHA1哈希算法
js-md5 - MD5哈希算法
@lapo/asn1js - ASN.1编码/解码
ofd-xml-parser - OFD XML解析
@sharp9/ofdjs - OFD格式处理
web-streams-polyfill - Stream API polyfill

常见问题

Q: 如何在Node.js中使用？

A: 由于该库依赖于浏览器DOM API，暂不支持Node.js环境。未来可能提供Headless实现。

Q: 支持大文件吗？

A: 支持，但建议文件不超过100MB。对于特别大的文件，可能需要分页加载。

Q: 可以修改渲染样式吗？

A: 可以。通过CSS修改返回的页面DOM元素的样式。

Q: 支持导出功能吗？

A: 当前版本仅支持渲染和查看。导出功能建议使用html2pdf等库。

Q: 可以获取文本内容吗？

A: 可以通过遍历文档对象的内容节点获取。具体方法请参考源代码或提出Issue。

版本历史

请查看 CHANGELOG.md 了解版本更新信息。

许可证

本项目采用 Apache License 2.0 许可证。

修改版本： 2026 Ycsx

详情请见 LICENSE 文件。

贡献

欢迎提交Issue和Pull Request！

在贡献前，请：

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建Pull Request

联系方式

如有问题或建议，欢迎：

提交 GitHub Issues
发送邮件至: 4081360972qq.com

最后更新： 2026年6月26日

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
__tests__		__tests__
dist		dist
examples		examples
scripts		scripts
src		src
tests		tests
.babelrc		.babelrc
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
BROWSER_COMPATIBILITY.md		BROWSER_COMPATIBILITY.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MODULE_IMPORT_SOLUTION.md		MODULE_IMPORT_SOLUTION.md
README.md		README.md
index.d.ts		index.d.ts
index.js		index.js
jest.config.js		jest.config.js
package.json		package.json
webpack.config.cjs		webpack.config.cjs

Latest commit

History

Folders and files

Repository files navigation

@ycsx/ofdjs

功能特性

安装

快速开始

基础使用

使用缩放功能

原生 HTML 中使用

在 Vue 3 中使用

API 文档

parseOfdDocument(options)

renderOfd(screenWidth, ofdDocument)

renderOfdByScale(ofdDocument)

setPageScale(scale)

getPageScale()

calPageBox(screenWidth, document, page)

calPageBoxScale(document, page)

renderPage(pageDiv, page, templates, fonts, drawParams, multiMedia)

错误处理

支持的OFD版本

浏览器兼容性

依赖项

常见问题

Q: 如何在Node.js中使用？

Q: 支持大文件吗？

Q: 可以修改渲染样式吗？

Q: 支持导出功能吗？

Q: 可以获取文本内容吗？

版本历史

许可证

贡献

相关资源

联系方式

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages