同一份合同,收到“原稿”“修改稿”“最终稿”三个版本。对方说只调整了日期,你还得确认金额、收款账户、页面内容有没有一起变动。
打开两个窗口来回切换,短文档还能应付。页数多了,金额只改一个数字、图片挪了一点位置、某一页插进了新内容,都很容易漏看。
做系统开发时也会遇到类似问题:模板改版后,正文是否一致?重新生成 OFD 后,哪些资源变了?页面看起来一样,为什么文件摘要不同?
这次介绍 zc310/ofd 项目中的一个工具:ofd-compare。
它以一份 OFD 为基准,比较其他版本的包内文件、XML 结构、页面文字和渲染画面,生成可以在浏览器中离线查看的报告。需要接入脚本或系统时,也可以输出 JSON、文本和 Markdown。
一、一条命令,把几个版本放到一起看 #
先看最常用的命令:
ofd-compare -o comparison.html original.ofd revised.ofd final.ofd默认以第一份 original.ofd 为基准,分别比较 revised.ofd 和 final.ofd。生成的 comparison.html 可以直接用浏览器打开,页面上有目标文件切换框。
这里的比较关系是“原稿与修改稿”“原稿与最终稿”。需要查看修改稿到最终稿之间的变化,可以把修改稿选为基准:
ofd-compare --baseline 2 -o comparison.html original.ofd revised.ofd final.ofd--baseline 使用位置参数中的文件序号,从 1 开始。
CLI 默认同时比较结构、文字和画面。HTML 默认内嵌预览图片,传递这一份报告文件,就能让对方看到文字修改、页面原图和视觉差异,无需另行安装 OFD 阅读器。
二、为什么要同时看文件、结构、文字和画面 #
OFD 通常用 ZIP 容器组织 XML、页面、字体、图片、附件和签名等内容。这个特点决定了“两个文件是否一样”有不同的观察角度。
重新压缩一次,ZIP 时间戳、压缩方式、条目顺序可能变化,整个文件的摘要就会不同,但包里的内容可以完全相同。
页面文字相同,图片、字号或位置却可能已经变化。页面 XML 没改,引用的共享图片被替换,也可能让画面发生变化。
ofd-compare 把几个角度放进同一份报告:
| 对比层面 | 主要回答什么问题 |
|---|---|
| 包内目录与文件 | 多了什么、少了什么,哪些文件修改或移动了 |
| XML 结构 | 元素、属性、文字和子元素顺序在哪里发生变化 |
| 页面文字 | 哪些文字删除、新增或替换了 |
| 页面画面 | 渲染后哪些像素发生变化,变化集中在哪些区域 |
包内文件按解压后的 SHA-256 比较,避免仅因 ZIP 重新打包就误报内容变化。
XML 则进一步区分原始字节变化和结构变化。例如,只改变命名空间前缀、属性顺序、注释或普通元素间的缩进,会与真正的内容变化分别展示;TextCode 中有意义的空白仍会保留。
这样,报告里的差异就有了可追查的上下文:能看到哪里变了,也能继续查看对应的内部文件。
三、先看文字,再放大页面上的变化 #
假设一次修订同时调整了金额、日期和账户:
原稿
合同金额:100 元
交付日期:10 月 20 日
收款账户:甲账户
修改稿
合同金额:120 元
交付日期:10 月 25 日
收款账户:乙账户报告会分别标出文字中的多处删除和新增。文字按 Unicode 字符比较,中文、表情和空白可以保留,方便核对细小的修改。
遇到大段重写,工具会在达到搜索上限时回退为完整变化段落对照,并给出提示,双方文字仍会保留。
接下来可以看视觉对比。成对页面发生画面变化时,会提供三幅图:基准页、目标页、差异图;新增或删除的页面,缺失一侧留空。
差异图支持多个区域框。点击区域框或区域按钮,可以查看局部放大,前后图和差异图同步滚动;也可以用“上一处差异”“下一处差异”依次检查。对于轻微的位置变化,还能打开透明叠加,调整目标页的不透明度。
这对“文字一样,但排版动了”的情况很有帮助。例如图片移动、边框变化、盖章位置调整,都可以结合原图和局部差异进一步确认。
需要提高显示精度时,可以调整 DPI:
ofd-compare --dpi 96 -o comparison.html original.ofd revised.ofd默认 DPI 为 72。提高分辨率会增加渲染工作量和报告图片体积,可以根据核对内容选择。
如果差异图里有一些不想逐个检查的小噪点,可以过滤较小的区域:
ofd-compare --min-region-pixels 4 -o comparison.html original.ofd revised.ofd这个选项只过滤区域展示,原始变化像素和页面相同判定仍然保留。
四、从一行文件差异,追到 XML 里的具体修改 #
排查生成器或模板问题时,内部文件清单往往比整页截图更容易提供线索。
报告里的“完整文件清单”采用逐行对照:同路径文件放在同一行,已识别为移动的文件将旧、新路径对齐。双方都显示文件大小和比较状态。
修改、新增、删除和移动的行会标红,缺失一侧显示 —。即使文件大小完全相同,只要内容摘要不同,也会标为修改;移动文件还会注明内容相同。
文件较多时,可以输入路径搜索,再组合“只看不同”、状态和文件类型筛选。比如先筛选修改过的 XML,再从中查找某个页面目录。
点击差异行或“查看详情”,会展开并定位到对应的文件详情,可以继续看 XML 差异或支持格式的小图片预览。看完后点击“返回文件清单”,可以回到原文件行,搜索和筛选条件也会保留。
XML 详情同时提供两种查看方式:
- 左右对照:规范化显示 XML,按行对齐变化,两侧变化分别标红、标绿;较长的相同片段默认折叠,可以逐段或统一展开。
- 字段差异:查看具体元素、属性或文字字段的路径与前后值,便于精确定位。
这里的行号属于格式化后的显示内容。XML 对照设有展示上限,超过时会说明原因,继续提供可用的结构分类和字段差异。
五、插了一页之后,先确认页面有没有配对正确 #
多版本文档对比,一个容易影响结果的问题是页面对应关系。
例如:
基准:第 1 页 A,第 2 页 B,第 3 页 C
目标:第 1 页 A,第 2 页新增,第 3 页修改后的 B,第 4 页 C如果直接拿两份文件的第 2 页比较,就会把 B 与新增页放在一起,后续差异也会变得难以阅读。
ofd-compare 默认使用自动配对:先在同一文档体内匹配相同页面内容、唯一相同的非空文字,再结合相邻匹配页和文字相似度关联修改页,最后对剩余页面按顺序补齐。
报告还会显示每组页面的配对依据,包括手工映射、内容摘要相同、唯一相同文字、文字相似度,以及顺序兜底或未匹配。
按顺序兜底的页面会提示复核。文字相似度分数用于解释配对依据,不代表匹配正确概率,也不表示画面相同。
扫描件、重复页面或大幅改写后的文档,仍可能需要人工调整对应关系。这时可以在报告中展开:
“调整页配对并导出 –page-map”。
编辑器预填当前配对,可以修改每个基准页对应的目标页。目标页重复、页码非法或超出本报告的选页范围时,会标红并禁止导出。调整完成后,可以复制参数,或下载为 .txt。
沿用前面的插页例子,确认基准第 2 页对应目标第 3 页、第 3 页对应目标第 4 页:
ofd-compare --page-match auto --page-map "2:3,3:4" \
-o remapped.html original.ofd revised.ofd手工映射优先,其他页面继续自动匹配。
导出的映射针对当前这份基准和目标,重新运行时把基准放在第一位、目标放在第二位。编辑器中的修改是配对草稿,需要重新运行后,才会生成新的文字和视觉差异。
另外,清空一行表示不固定该页,让它重新自动匹配,并不表示强制删除或新增这一页。
六、几种常用的运行方式 #
只关注部分页面 #
核对长文档中的关键章节,可以先缩小页面范围:
ofd-compare --pages "1-3,5" -o selected.html original.ofd revised.ofd页码从 1 开始,多文档体按文档顺序累计。页范围分别应用于每份输入,先选页再配对,报告保留原始页码。
选页只限制页面文字、配对和渲染,包内文件及 XML 仍按整包比较。 因此,未选中页面对应的文件有变化,仍会出现在文件差异里。
JSON 中的 pages_equal 表示所选页面的比较结果,equal 则同时检查整包差异。脚本可以根据业务目的选择判断哪一个。
报告图片较多时,使用外置图片 #
ofd-compare --external-images -o comparison.html original.ofd revised.ofdPNG 会保存到报告旁新建的 ofd-compare-images-* 目录中,HTML 使用相对路径引用。共享报告时,需要同时携带图片目录,并保持相对位置。
外置图片可以减少 HTML 体积和报告对象中累计的 base64 数据。渲染像素、预览图和报告体积仍有预算约束,超过时会明确返回错误,可以按文档情况调整 DPI 或相应限制。
接入脚本,发现差异时返回非零退出码 #
ofd-compare --visual=false --fail-on-difference \
-o comparison.json original.ofd revised.ofd这条命令比较结构与文字,不渲染页面,适合先做一轮检查。默认情况下,发现差异也可以正常生成报告并返回 0;加上 --fail-on-difference 后,有差异返回 1,参数错误返回 2,读取、解析、渲染或输出失败等运行错误返回 3。
需要把画面也纳入检查时,保留默认视觉比较即可:
ofd-compare --fail-on-difference \
-o comparison.html original.ofd revised.ofd使用 --pages 时,这个退出码仍按整份报告的差异判断。只想对所选页面做门禁,可以读取 JSON 中的 pages_equal。
七、怎样运行,怎样集成 #
获取包含 cmd/ofd-compare 的项目源码后,在仓库根目录可以直接运行:
go run ./cmd/ofd-compare -o comparison.html original.ofd revised.ofd也可以编译为命令行程序:
go build -o ofd-compare ./cmd/ofd-compare
./ofd-compare --helpGo 版本要求以源码中的 go.mod 为准。需要生成包含程序与说明文档的工具包,可以使用 make package-compare。
程序在本机读取、比较 OFD,默认 HTML 报告可以离线打开,适合在本地核对文档版本。
需要集成到 Go 程序时,可以使用 github.com/zc310/ofd/pkg/compare 下的 CompareFiles 和 WriteReport。API 的基准索引从 0 开始,CLI 的 --baseline 从 1 开始;API 的零值选项默认不渲染,启用画面对比需要显式设置 Visual: true。
开发验证中,已使用 1000 页、5000 页样例完成结构对比及四种报告输出,并检查大文件清单的搜索和页面过滤。这里的页数验证针对结构对比;视觉对比的开销还会受到页面内容、字体、图片和 DPI 的影响。
八、读报告时,把比较范围放在心里 #
页面文字来自正文和可用模板中的文字内容。目前不做 OCR,因此扫描图片中的文字变化,需要通过画面对比查看。
视觉结果采用本机渲染环境。缺失字体、字体替代和不同厂商的扩展内容,都可能影响呈现;比较时应关注字体环境与渲染器的支持范围。
附件、签章和历史版本文件的变化可以出现在包内差异中。签名是否有效,则需要结合 ofd-validator 或签章验证 API 单独核验。报告中的“文件相同”“页面相同”“画面相同”,各自对应不同的比较范围。
实际核对一份文档时,可以先查看概况和页面配对依据,再检查文字、逐个放大视觉区域,最后沿文件清单追查内部变化。遇到配对有歧义的页面,就调整映射、重新生成报告,把这次核对的对应关系也固定下来。