技术文章

用 PDFium Component 构建带 AF 关联文件的 PDF/A-3

要从 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 禁止嵌入文件,元数据再整洁也没用

PDFium Component 里 PDF/A-3 关联文件的三对象链:一条带 MIME Subtype(如 application xml)的 EmbeddedFile 流,一个设了 F、UF、EF 且 AFRelationship 为 Data 的文件规格,以及来自 catalog 或页面的指向它的 AF 数组——ISO 19005-3 第 6.8 条通过前验证器查的就是这三个对象
流、文件规格与 AF 数组必须彼此咬合;TPdf.CreateAttachment 的普通名称树内嵌按设计不设置任何关联字段

关系值是最容易靠猜的部分。FPdfAssocFiles 里的 TPdfAFRelationship 把每个枚举成员映射到注入器能发出的名称令牌,其中只有前五个属于 ISO 19005-3 认可的子集:

  • afSource → /Source:PDF 由之产出的原件,比如文字处理文件或电子表格
  • afData → /Data:可见内容由之推导或所代表的机器可读数据
  • afAlternative → /Alternative、afSupplement → /Supplement、afUnspecified → /Unspecified
  • afEncryptedPayload、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 字符串可能提前闭合字典,或者注入额外的键

MIME 子类型 text slash plain 为何会弄坏 PDFium Component 里的 PDF/A-3 解析:把值直接拼在斜杠后产出两个 name 对象——值 /text 加一个让 EmbeddedFile 字典失衡的悬空 /plain——而 EscapePdfName 写出单个名称 /text#2Fplain,解码即 text/plain
失败看着像文件损坏,因为它发生在解析器里、任何 PDF/A 规则之前;转义后的名称保住键值对平衡,验证器才能继续读
// 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 字典:页面一旦重排或插入,页对象的存储顺序可以与显示顺序不同,文件就落到另一页上

PDFium Component 里 /AF 数组的去处:TargetPage 为 0 挂到 catalog,1 到 N 挂到页字典,越界值抛异常;注入器把一切按固定布局作为单个增量更新追加,保持既有偏移并替换既有的 /AF 条目
越界的 TargetPage 抛异常,而不是悄悄变成文档级关联;第二次调用换一份文件清单就由它说了算
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 产品页