用Folio生成PDF/A合规文档:如何让你的PDF轻松通过归档级验证
用Folio生成PDF/A合规文档:如何让你的PDF轻松通过归档级验证
Folio 是一款 Go 语言的 PDF 生成库,覆盖布局引擎、HTML 转 PDF、表单、数字签名、条形码和 PDF/A 合规 等能力。它内置的 SetPdfA 接口让你用一行代码生成 PDF/A 归档级文档,自动补齐 XMP 元数据、ICC 色彩配置与字体嵌入等合规要件,让你的 PDF 轻松通过 veraPDF 等验证工具的归档级检查。📦
为什么你的 PDF 需要"归档级"身份?
普通 PDF 几年后可能打不开、缺字体、颜色失真。而 PDF/A(ISO 19005 系列标准)是为"长期保存"设计的档案级格式,它要求:
- 📌 所有字体必须嵌入——不依赖阅读者电脑上的字体;
- 📌 必须携带 XMP 元数据,其中含
pdfaid合规标识; - 📌 必须声明 OutputIntent 和 ICC 色彩配置文件;
- 📌 禁止加密(加密会在档案系统中造成无法解析的风险)。
Folio 在 document/pdfa.go 中完整实现了这些要求,并在写出文件前执行自检,把问题挡在"验证失败"之前。
三步开启 PDF/A 模式
第一步:设置文档信息——Title 是 PDF/A 的硬性要求:
doc := document.NewDocument(document.PageSizeA4)
doc.Info.Title = "年度归档报告"
第二步:调用 SetPdfA 指定合规级别:
doc.SetPdfA(document.PdfAConfig{Level: document.PdfA2B}) // 归档级
第三步:正常写入,Folio 自动完成 XMP 元数据流、OutputIntent(默认 sRGB ICC 配置)、PDF 版本号等全部配套工作:
doc.Save("archive.pdf")
就这么简单。元数据构建逻辑见 document/pdfa.go,文档信息字段定义见 document/info.go。
选哪个 PDF/A 级别?一张表看懂
| 级别 | 常量 | 特点 | 典型场景 |
|---|---|---|---|
| PDF/A-1b / 1a | PdfA1B / PdfA1A |
基于 PDF 1.4,禁止透明度 | 老旧归档系统 |
| PDF/A-2b | PdfA2B |
基于 PDF 1.7,允许透明度 | 通用归档首选 ✅ |
| PDF/A-3b / 3a | PdfA3B / PdfA3A |
允许嵌入附件文件 | 电子发票、数据载体 |
| PDF/A-4 / 4f / 4e | PdfA4 / PdfA4F / PdfA4E |
基于 PDF 2.0,最新标准 | 电子发票继任者、工程档案 |
级别差异由 document/pdfa.go 中的 PdfALevel 类型统一管理。
自动校验:写文件前先"体检"
Folio 提供 ValidatePdfA 方法,在 WriteTo 之前就能发现问题;写文件时也会再次强制执行。常见拦截项包括:
- 字体未嵌入——使用 Helvetica 等"标准字体"而未嵌入子集会直接报错;
- 缺少 Title——元数据不完整;
- Level A 级别缺少语言声明——需设置
Info.Language(如"zh-CN"); - PDF/A-1 使用透明度、在禁止附件的级别上附加文件等。
💡 好消息:通过 HTML 转换器(
doc.AddHTML)生成的内容会自动嵌入字体,天然满足 PDF/A 的字体要求。
各检查项的行为都有测试用例覆盖,见 document/pdfa_test.go。
进阶玩法:用 ZUGFeRD 生成 PDF/A-3B 电子发票
需要"人在左边看、机器在右边读"的混合发票?Folio 的 ZUGFeRD 模块(zugferd/)一条 invoice.Attach(doc, profile) 就能同时完成三件事:
- 开启 PDF/A-3B(唯一允许附件的常用级别,ISO 19005-3 §6.4);
- 写入 Factur-X 的 XMP 扩展模式(
XMPSchemas); - 把机器可读的 CII XML 嵌入为关联文件(
AFRelationship)。
完整可运行的发票示例见 examples/zugferd/main.go,相关设计说明在 docs/design-zugferd.md。
总结:归档合规交给 Folio
| 你担心的事 | Folio 的做法 |
|---|---|
| XMP 元数据手写容易出错 | 自动生成 pdfaid:part / conformance,Level A 自动开启 Tagged PDF |
| ICC 配置文件没有现成的 | 内置完整 sRGB ICC 配置(9 个必需 tag),无需外部文件 |
| 验证工具报错难定位 | ValidatePdfA 提前报错,错误信息含页码与具体原因 |
核心关键词回顾:Folio、PDF 库、Go、PDF/A 合规、PDF/A-2B、归档级验证、XMP 元数据、字体嵌入、电子发票。
从 go get github.com/carlos7ags/folio 到生成第一份通过验证的 PDF/A 文档,你只需要几行代码。🚀
