↓ 跳过正文
  1. 文章/

不装软件、不上传文件:一个纯前端 OFD 工具箱,把转换、校验、发票抽取全塞进了浏览器

目录

同事甩给你一个 .ofd 文件——发票、合同、电子证照,现在越来越多是这种格式。你双击,打不开;想转成 PDF 发给客户,搜到的工具要么让你先注册账号,要么让你上传到它的服务器再下载。

发票里有税号、金额、开票方,合同里有公章和签署信息。这些东西你敢往陌生网站上贴吗?

装个桌面软件?平台、安装和升级都要考虑,而且有的工具只做“转 PDF”一件事。想校验一下文件结构、看看到底有哪些资源、批量把几十张发票的金额汇总出来,还需要更多工具配合。

今天聊的这个开源项目就是冲这些痛点来的:zc310/ofd-toolbox——一个用 Go 编译成 WebAssembly 的纯前端 OFD 工具箱。文件不上传,没有处理文档的服务端,也没有账号,打开网页就能用。

在线使用:OFD 工具箱。

本文按原稿所述功能与体积整理,工具数量、模块大小和可选功能可能随版本变化,以项目文档与线上界面为准。只想快速了解功能,可先看工具箱简要介绍。

一、它到底是什么
#

一句话概括:

把一整套 OFD 文档处理能力,编译成一个 WebAssembly 模块,放进浏览器里跑。所有文件的理解与改写都在你这台机器上完成。

底层能力来自 zc310/ofd 这个 Go 工具包,ofd-toolbox 负责把它包成浏览器能用的形态:WASM 构建、Worker 调度、流式产物传输、Service Worker 缓存和界面。

原稿介绍的界面一共 7 个工具 Tab:

Tab 做什么
转换 OFD 转 PDF、图片、SVG、EPS、TeX、HTML、Markdown、Word、纯文本;PDF、图片、Markdown 转 OFD
校验 校验 ZIP、XML、引用关系与 XSD,报告可导出 JSON / Markdown / 纯文本
分析 页面对象、文字、资源、附件、注解、签名与引用关系概览
发票 批量读取增值税电子发票 OFD,汇总金额、按销售方/票种/月份分组,导出 JSON / CSV / XLSX
水印 在指定页添加、替换或删除文字/图片水印,支持布局、旋转、透明度、字体
合并 ZIP 级合并产出多文档包,或模型级拼页产出单文档
长期保存 按 GB/T 42133 第 6 章预检与执行,含删除无人引用条目

输入格式(浏览器里能直接用的):OFD、PDF、PNG、JPG、TIFF、Markdown。

二、最有价值的点:文件不上传
#

许多在线转换工具采用“上传 → 服务器处理 → 下载”的流程。OFD 常常是发票、合同、证照,文档能否外传,需要先考虑清楚。

ofd-toolbox 采用另一种架构:

  • 能力来自 Go 工具包,编译成一个 .wasm 模块。
  • 模块在浏览器 Worker 里运行,计算全在本机。
  • 没有处理文档的后端接口,没有文件上传这一步。
  • 首次加载后由 Service Worker 缓存,后续可在所需资源已缓存的情况下离线使用。

你可以在开发者工具的 Network 面板里检查:网页会加载静态资源,但文档处理不需要把所选文件上传到服务器。浏览器扩展、操作系统与设备本身的安全仍需另外考虑,不能把“本地处理”理解为完整的安全认证。

三、工程上几个“不显眼但很关键”的决定
#

一个纯前端工具最难的不是“能跑”,而是大文件处理、错误隔离和行为边界。这个项目在这几件事上做了不少取舍。

1. WASM 跑在 Worker 里,主线程负责交互
#

模块有 50 MB 量级。如果装载和计算都在主线程,页面可能长时间不可交互——进度条卡住、取消按钮点不动、滚动条卡死。

所以整个引擎跑在 Web Worker 里,主线程只负责界面。进度、取消、产物分块全部走消息传递。

2. 产物分块下发,Worker 内部确认(ACK)
#

WASM 回调给出一块产物,写进接收端后立刻确认,下一块才生成。

少了确认,中间产物可能在 WASM 内存里累积。模块、文档与尚未写出的产物叠加,会增加浏览器内存压力,严重时可能导致标签页被终止。

ACK 特意不经过主线程,避免多一次消息投递延迟。

3. 命令边界统一兜 panic
#

第三方库里可能崩溃的地方之一是“找不到系统字体”,例如 font.FindSystemFonts 在无字体目录环境中的空指针问题。这类错误不是返回 error,而是直接 panic,调用方写不了 if err != nil。

不在边界上兜住的话,一次未恢复的 panic 就可能终止整个 WASM 实例:已打开的文档、缓存的报告和正在跑的任务一起丢失,只能整页刷新。

所以在每个导出的 JS 命令外面套了一层 safe(),把 panic 转成错误结果。

4. Service Worker 缓存名由内容哈希算出
#

页面的 HTML、JS 与 WASM 通过同一套资源版本管理,减少“新 JS 调旧 WASM”的问题。换版时需要刷新页面以完成接管,因此界面上有一条“已有新版本”的提示。

5. 字体只取本机或用户上传的文件,不联网取字体
#

浏览器里没有可随意读取的系统字体目录。OFD 没内嵌字体时,中文可能变成方块。工具允许你选本机字体或上传字体文件兜底,候选列表还会标出哪些能补齐文档缺字、哪些已注册。

6. 界面由能力清单驱动
#

转换 Tab 的格式卡片、参数面板显隐,校验 Tab 的可选项,全部由 WASM 侧的 capabilities 清单驱动。库侧增删格式时界面自动跟随,不需要两处同步。

四、几个值得留意的细节
#

真正影响使用体验的,往往是错误信息和小开关的设计。

发票金额用十进制字符串传递。 1130.00 一旦变成数字 1130 再转回文本,就可能少了小数位。金额通过 Decimal 类型处理,序列化成字符串,避免这类表示差异。

合并默认保留签名条目,但保留不等于有效。 加水印会改动页面内容,可能使已有签名摘要验证失败。工具保留签名相关条目并把警告透传给界面,不能据此认定修改后的文件仍具备有效签名;输出文件应另行验证,原件也应保留。

长期保存拆成两步走。 预检(Plan)只读,算出计划改动;执行(Apply)才写文件。其中一类动作是不可逆的删除,让用户先看到“会发生什么”再决定。

生成汇总页需要一个中文字体,没有就不让生成。 而不是让它生成一页空白——空白页比报错难发现得多,用户会以为汇总就是空的。

内存诊断区分“堆”和“线性内存”。 WASM 线性内存增长后通常不会随 Go 堆回收而立即缩小,不能仅凭它没有下降就判断泄漏。诊断时还需要结合 Go 存活堆、任务状态和浏览器整体内存观察。

五、自己跑一遍
#

在仓库根目录执行:

make build-wasm
python3 -m http.server 8080 --directory cmd/toolbox-wasm/web

然后打开 http://localhost:8080。注意浏览器不能直接通过 file:// 加载此应用的 WASM,需要使用 HTTP 服务。

make build-wasm 会编译 toolbox.wasm、按需用 wasm-opt 优化、从 GOROOT 复制 wasm_exec.js,最后按各资源的内容哈希重算 service-worker.js 里的缓存名。找不到 wasm-opt 时会告警并改用未优化版本,不让构建直接失败。

原稿对应的主要目录结构:

cmd/toolbox-wasm/
├── *.go            WASM 侧命令,每个文件带 //go:build js && wasm
└── web/            页面资源(无框架、无构建步骤,直接就是浏览器要的东西)
    ├── index.html  单页,7 个工具 Tab
    ├── app.js      主线程:界面、状态、Worker 消息
    ├── worker.js   Worker:WASM 装载、命令分发、流式产物接收
    └── toolbox.wasm  构建产物,50MB 量级,不入库

没有前端框架,没有前端打包步骤——页面资源就是浏览器最终要加载的东西,少了一层工具链的复杂度;WASM 本身仍需按上述命令构建。

六、已知边界
#

  • Office 与 HTML 输入不可用。 docx/odt/rtf/wps/pptx/xlsx 和 html/mhtml 依赖 LibreOffice 或 Chrome 命令行,浏览器里没有。界面会说明缺少的能力。
  • 校验与分析报告不提供 XLSX 与 PDF。 原稿所述版本中,两者可导出 JSON / Markdown / 纯文本。发票报表不受此限。
  • 原稿记录的 WASM 体积为 63 MB。 发票 XLSX 导出要引入 excelize,单独贡献约 12.6 MB。首次加载需要下载模块,之后由 Service Worker 缓存;具体体积随构建版本变化。
  • OFD 支持范围以 zc310/ofd 的文档为准。 不同厂商的 OFD 存在扩展差异。

七、适合谁?
#

适合
#

  • 手里有 OFD,需要在不上传文件的前提下转成 PDF、图片、Word 或 Markdown。
  • 需要校验 OFD 包结构、排查引用关系与签名问题。
  • 财务、审计要把成批的增值税电子发票金额汇总出来,导出成 Excel。
  • 要给合同、文档批量加水印,或把多份 OFD 合并。
  • 做数字档案,需要按 GB/T 42133 做长期保存预检与处理。
  • 想使用一个在本机浏览器内处理文档、不需要注册账号的工具。

不适合
#

  • 需要处理 Office / HTML → OFD:浏览器环境里缺少 LibreOffice / Chrome 命令行。
  • 需要 OCR:图片转 OFD 不会因此自动获得文字层。
  • 对电子签名的法律有效性做最终认定:工具不保证合规结论,签章有效性需要另行核验。

八、最后说点判断
#

OFD 是国标版式文档格式,在电子发票、电子证照、政务档案等场景里经常能遇到。除了桌面软件和服务器转换,ofd-toolbox 提供了另一种处理方式:

用 WebAssembly 把处理能力搬到本机浏览器里,支持转换、校验、发票汇总、水印、合并与长期保存处理,不需要上传文档、不需要安装桌面软件、不需要账号。

Worker 隔离、分块 ACK 背压、panic 边界、内容哈希缓存、capabilities 驱动的界面、两步式不可逆操作,以及金额的小数位处理,都是实际使用中值得关注的工程细节。

同样重要的是看清边界:不能处理的输入、首次加载体积、字体和签名问题,都需要在正式使用前确认。技术选型里最怕的不是能力有限,而是踩坑后才知道边界在哪。

如果你经常和 OFD 打交道,可以用自己的代表性文件试一遍,再决定是否加入日常工作流程。

项目与相关内容
#

相关文章

ofd-compare:从文字、结构到画面,核对 OFD 文档版本差异

同一份合同,收到“原稿”“修改稿”“最终稿”三个版本。对方说只调整了日期,你还得确认金额、收款账户、页面内容有没有一起变动。 打开两个窗口来回切换,短文档还能应付。页数多了,金额只改一个数字、图片挪了一点位置、某一页插进了新内容,都很容易漏看。 做系统开发时也会遇到类似问题:模板改版后,正文是否一致?重新生成 OFD 后,哪些资源变了?页面看起来一样,为什么文件摘要不同? 这次介绍 zc310/ofd 项目中的一个工具:ofd-compare。 它以一份 OFD 为基准,比较其他版本的包内文件、XML 结构、页面文字和渲染画面,生成可以在浏览器中离线查看的报告。需要接入脚本或系统时,也可以输出 JSON、文本和 Markdown。

OFD 与 PDF 互转实测:最快的不一定能用,99% 相似也不代表文字没丢

数据快照:2026 年 11 月 16 日。本文基于 zc310/ofd-benchmark 仓库的双向测试结果,具体版本与原始报告见文末。 收到一张 OFD 发票,想转成 PDF,方便预览、打印和分享。 业务系统里有一批 PDF,又需要转成 OFD,对接归档流程。 听起来像同一件事的两个方向:找个库,换一下输入和输出就好了。 真正接入系统后,问题却一个接一个:文件生成了,页面为什么少了字?画面看着一样,复制出来为什么是乱码?转换只花几十毫秒,得到的内容真的完整吗? 这次,我们不只看“支持转换”四个字,而是把 OFD→PDF 的 9 种方案、PDF→OFD 的 6 种方案放进同一套基准,比较速度、体积、画面和文本。 先说最重要的结论: 生成文件、画面对、文字对,是三件不同的事。选型时,顺序应该是先验质量,再比性能。

OFD 操作库推荐:按开发语言与业务场景选择开源库和商业 SDK

OFD(Open Fixed-layout Document)是中国国标版式文档格式(GB/T 33190—2016),广泛应用于电子公文、电子发票、电子证照等场景。以下按开源库(按编程语言分类)和商业 SDK两大类整理候选方案,说明核心特点与适用场景。 选型时请区分 **OFD(中国国标版式文档)**与 ODF(OpenDocument 办公文档格式)。二者是不同的文档标准,大量名为 odf-* 的开源库仅支持 ODF,不可混用。

go ofd 转 pdf

·1 分钟
这周 把去年计划用go写个ofd 阅读器的代码补上了转pdf或png ,代码 https://github.com/zc310/ofd 还差实现简单阅读器 看看用 gioui.org 实现一个简单的类似 MuPDF 那种效果的。