要从 Delphi 把一份源文件挂到 PDF/A-3 文档上,PDFium Component 写出的是 PDF 2.0 的关联文件链:一条带 MIME /Subtype 的嵌入文件流,一个携带 /AFRelationship 的文件规格,以及挂在 catalog 或页面上的 /AF 数组。InjectAssociateFiles 和 TPdf.SaveAsWithAssociateFiles 用一次增量更新搭起这条链,MIME 类型序列化为单个转义正确的 PDF 名称。本文其余部分讲验证器查什么、那个弄坏 text/plain 的一字符陷阱,以及防止一次笔误或一个读不了的 trailer 产出错误文件的种种检查
PDF/A-3 关联文件到底需要什么?
一份 PDF/A-3 附件要通过验证,需要三个对象彼此咬合:嵌入文件流声明 /Type /EmbeddedFile 加一个 MIME /Subtype;文件规格字典(ISO 32000-2 §7.11.3)带有 /F、/UF、/EF 和 /AFRelationship;文档里有东西经 /AF 数组(ISO 32000-2 §14.13)引用那份文件规格。经 /Names /EmbeddedFiles 树的普通内嵌——也就是 TPdf.CreateAttachment 做的——压根不设置任何关联字段。一次 PDF/A-3b 验证能把依赖关系变得具体:只改 /AFRelationship 键名,文件恰好挂掉 ISO 19005-3 第 6.8 条里的一条规则;只删 MIME /Subtype,挂掉的是 6.8 里另一条;把同一附件塞进 PDF/A-1b 候选文件,则被直接拒收——PDF/A-1 禁止嵌入文件,元数据再整洁也没用
关系值是最容易靠猜的部分。FPdfAssocFiles 里的 TPdfAFRelationship 把每个枚举成员映射到注入器能发出的名称令牌,其中只有前五个属于 ISO 19005-3 认可的子集:
afSource→/Source:PDF 由之产出的原件,比如文字处理文件或电子表格afData→/Data:可见内容由之推导或所代表的机器可读数据afAlternative→/Alternative、afSupplement→/Supplement、afUnspecified→/UnspecifiedafEncryptedPayload、afFormData、afTemplate:PDF 2.0 新增,落在 PDF/A-3 子集之外,归档输出请避开
/Subtype /text/plain 为什么会弄砸验证?
这是分词错误,不是合规缺口。把调用方的字符串直接拼在斜杠后面,得到的就是 /Subtype /text/plain。按 PDF 语法,第二个斜杠开启一个新的 name 对象(ISO 32000-1 §7.3.5),于是流字典里突然出现键 /Subtype、名称 /text,外加一个让键值对失衡的多余名称 /plain。独立的 PDF/A 验证器在解析 EmbeddedFile 字典时就会拒收这种文件,根本走不到任何 PDF/A 规则——所以这次失败看起来像文件损坏,而不是少了个附件属性
PDFium Component 让 MIME 值过一遍 EscapePdfName,产出 /text#2Fplain:一个名称,解码后的值是 text/plain。转义刻意比斜杠本身更广。每个小于等于 32 的字节(空格、制表、CR、LF)、每个大于等于 127 的字节、分隔符 ()<>[]{}/% 以及 # 转义字符自己,统统变成 #XX。只转义斜杠会留下另一个洞:含 >> 或空白字符的 MIME 字符串可能提前闭合字典,或者注入额外的键
// MIMEType = 'text/plain'
// 想当然的拼接: /Type /EmbeddedFile /Subtype /text/plain (两个名称)
// 注入器输出: /Type /EmbeddedFile /Subtype /text#2Fplain (单个名称)
//
// 调用方一律传普通的 MIME 值。自己先转义一遍
// 会把 '#' 二次编码,把 'text#2Fplain' 变成 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';
用 InjectAssociateFiles 构建 PDF/A-3 文件
产出 PDF/A-3 时,先用 TPdf.SaveAsPdfAToStream 生成合规的基础文档,再对那份流调 InjectAssociateFiles;能通过 PDF/A-3b 验证的正是这条两步管道。TPdf.SaveAsWithAssociateFiles 是便捷包装,但它走普通的 SaveAs 路径(带 saRemoveSecurity),不走 PDF/A 写出器,所以不会添加 PDF/A 要求的 XMP 标识与输出意图。注意记录类型住在 FPdfAssocFiles 和 FPdfPdfa 里,两个单元都得进你的 uses 子句。自 v3.121.3 起,FileName 和 Description 不再限于纯 ASCII:/UF 与 /Desc 按 PDF 文本字符串写出——可打印 ASCII 原样,其余按带字节序标记的 UTF-16BE;而老式 /F 名称永远是可移植的可打印 ASCII,其余字符一律替换成 _,于是用自家代码页解码 /F 的阅读器看到的是下划线而不是乱码
uses
System.SysUtils, System.Classes, System.IOUtils,
PDFium, FPdfPdfa, FPdfAssocFiles;
procedure SaveWithSourceData(Pdf: TPdf; const XmlPath, OutPath: string);
var
PdfAOptions: TPdfASaveOptions;
Options: TAssocFilesOptions;
Base: TMemoryStream;
Output: TFileStream;
begin
PdfAOptions := TPdfASaveOptions.Default;
PdfAOptions.Conformance := pac3b;
Options := TAssocFilesOptions.Default; // TargetPage = 0:catalog 级 /AF
SetLength(Options.Files, 1);
Options.Files[0].FileName := 'invoice-data.xml';
Options.Files[0].Description := 'Structured invoice data';
Options.Files[0].Content := TFile.ReadAllBytes(XmlPath);
Options.Files[0].Relationship := afData;
Options.Files[0].MIMEType := 'application/xml'; // 写成 /application#2Fxml
Base := TMemoryStream.Create;
try
if not Pdf.SaveAsPdfAToStream(Base, PdfAOptions) then
raise Exception.Create('PDF/A-3 base save failed');
Output := TFileStream.Create(OutPath, fmCreate);
try
InjectAssociateFiles(Base, Output, Options); // 回卷 Base;失败抛 EPdfAssocFilesError
finally
Output.Free;
end;
finally
Base.Free;
end;
end;
catalog 还是页面:/AF 数组落在哪?
TAssocFilesOptions.TargetPage 决定 /AF 数组归谁:0 把它挂到 catalog 上作为文档级关联,1..N 挂到对应页字典,从 1 起数。注入器把一切作为单个增量更新按固定布局追加(先嵌入流,再文件规格,再 /AF 数组,最后重写的 catalog 或页对象),既有对象保持原偏移,任何东西都不重新压缩。目标字典上既有的 /AF 条目是替换而非合并,这让重复保存幂等,也意味着第二次调用换一份文件清单就由它说了算。TargetPage 受严格检查:TargetPage 超出 0..PageCount 时 SaveAsWithAssociateFiles 与 SaveAsWithAssociateFilesToStream 抛 EPdfError;TargetPage 为负或指向不存在的页面时 InjectAssociateFiles 抛 EPdfAssocFilesError,目标流保持原样——所以一个笔误没法悄悄把页面级关联变成文档级。TargetPage 指的是文档页序中该位置上的页。自己代码里要避的坑,是按文件顺序扫保存后的字节找 /Type /Page 字典:页面一旦重排或插入,页对象的存储顺序可以与显示顺序不同,文件就落到另一页上
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
const CsvBytes: TBytes; const OutPath: string);
var
Options: TAssocFilesOptions;
begin
// 越界的 TargetPage 会抛 EPdfError;先检查一下,
// 错误信息就能指出页号
if (PageNumber < 1) or (PageNumber > Pdf.PageCount) then
raise EArgumentOutOfRangeException.CreateFmt('No page %d', [PageNumber]);
Options := TAssocFilesOptions.Default;
Options.TargetPage := PageNumber;
SetLength(Options.Files, 1);
Options.Files[0].FileName := 'chart-data.csv';
Options.Files[0].Content := CsvBytes;
Options.Files[0].Relationship := afSource;
Options.Files[0].MIMEType := 'text/csv';
if not Pdf.SaveAsWithAssociateFiles(OutPath, Options) then
raise Exception.Create('Associated-file save failed');
end;
怎么可靠地读回 AFRelationship?
TPdf.AttachmentRelationship[Index] 经原生导出 FPDFAttachment_GetAFRelationship 返回附件的 /AFRelationship 名称,但空字符串有两种可能的含义,所以先调 AttachmentRelationshipFeaturesAvailable。绑定是宽容加载的:PDFium DLL 缺这个导出时,所有关系都读成空,这与一份「干脆没有 /AFRelationship」的文件规格无法区分。该属性还与 AttachmentCount 共用索引,后者数的是 /Names /EmbeddedFiles 树里的条目。注入器只写 /AF 链、不加名称树条目,所以经 InjectAssociateFiles 挂上的文件在这个索引之外;要确认注入的链,请检查保存后的字节或跑一个 PDF/A 校验器。那棵名称树的内部结构在用 PDFium Component 在 Delphi 中处理 PDF 附件里有讲
procedure ReportRelationships(const FileName: string);
var
Pdf: TPdf;
I: Integer;
Rel: string;
begin
if not AttachmentRelationshipFeaturesAvailable then
begin
Writeln('This PDFium build cannot report /AFRelationship');
Exit; // 空答案有歧义,所以干脆别问
end;
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
for I := 0 to Pdf.AttachmentCount - 1 do
begin
Rel := Pdf.AttachmentRelationship[I];
if Rel = '' then
Rel := '(no /AFRelationship)';
Writeln(Pdf.AttachmentName[I], ': ', Rel);
end;
finally
Pdf.Free;
end;
end;
SaveAsWithAssociateFiles 不保证什么?
TPdf.SaveAsWithAssociateFiles 保证的是文件格式外壳与请求的文件确实注入了,而不是合规性。保存的字节没有可读 trailer、或找不到 catalog 字典时,InjectAssociateFiles 在写任何东西之前就抛 EPdfAssocFilesError,SaveAsWithAssociateFiles 返回 False;由于该方法在打开目标之前先在保存存储里搭好完整输出,被拒或失败的保存不会碰既有文件。空的 Files 数组按设计原样复制文档。载荷内容也是你的责任:注入器不检查 XML 是否良构、MIME 类型与字节是否匹配、基础文档究竟是不是 PDF/A。在验证器看过之前,把成品当未验证对待——与PDFium Component 与 PDF/A 归档合规一文讲的是同一套纪律。若你还要自己解析来路字典,同一套 #XX 名称规则反过来照样适用,见解析 PDF 字典时的名称记号陷阱
关联文件、PDF/A 输出、附件元数据与校验都在同一个组件里交付,上面的管线不需要构建里出现第二个 PDF 库。API 参考、试用下载与授权选项见PDFium Component 产品页