技术文章

在 Delphi 中用 PDFium VCL 做 PDF/VT 可变数据打印

一家交易型打印厂退回了你 80,000 页的对账单批次,只给了一行拒收理由:“不是 PDF/VT,RIP 无法缓存”。这份文件在你桌上的每个查看器里都打开正常,颜色正确,数据合并无误。但这些都不是数字印刷机要的东西。高速可变数据打印的成败,取决于印刷机能否认出第 1 页的客户标志块与第 40,000 页的块在字节层面是同一个对象,渲染一次然后复用。PDF/VT 正是让这个承诺可以被机器检查的标准,而“看起来正确”恰恰是陷阱,因为 RIP 读取的结构在屏幕上看不见

PDFiumPas 通过 TPdf 上的一小组接口暴露这层结构:SaveAsPdfVT 负责写入,ValidatePdfVT 负责检查。本文讲的是这两个方法实际写到磁盘上、实际检查了什么,ISO 16612-2 在哪些地方比乍看之下更严格,以及哪些部分只是诚实的结构锚点,而不是可以拿去向客户收费的完整预检

PDF/VT 标准化了什么,为什么 PDF/X 排在第一位

PDF/VT(ISO 16612-2:2010)不是一种全新的文件格式。它是钉在 PDF/X 文件上的一层优化元数据,而且这个先后顺序是承重的。标准定义了三个合规级别,但其中只有两个用来给 PDF 文件命名:PDF/VT-1,单一的自包含文档;以及 PDF/VT-2,页面引用共享外部资源的文件集模型。你可能见到的第三个标记 PDF/VT-2s 根本不是文件级的值;它住在附录 A 描述的 MIME 流头部里。如果你发现有代码把 GTS_PDFVTVersion = "PDF/VT-2s" 盖进文档的 XMP,那段代码是错的

对单一文件来说,没有商量余地的是 PDF/X 基座。ISO 16612-2 §6.2.1 要求每个 PDF/VT-1 文件同时是一个有效的 PDF/X-4 文件;按 §6.2.2,PDF/VT-2 的文件集则必须坐在 PDF/X-4p、PDF/X-5g 或 PDF/X-5pg 之上。这就是 PDF/VT 写入器不能只附加几个标识符键的原因:它必须携带整套 PDF/X-4 标记,这意味着一个 OutputIntent、一个内嵌的 ICC 目标特性文件、相互一致的 XMP 与文档 Info 条目、一个 trailer /ID,还有不加密。缺了任何一项,你就得到一份自称 PDF/VT 的文件,而合规的消费方一检查基座它就露馅。PDFiumPas 把 PDF/X-4 层当作 PDF/VT 保存的一部分,所以你不用先单独调用 SaveAsPdfX;注入器一次写完两层

示意图:Delphi 中构建的 PDF/VT 栈——优化元数据坐在强制的 PDF/X-4 基座上;PDF/VT-1、PDF/VT-2 精确配对一致性,PDF/VT-2s 则只是 MIME 标记
PDF/VT 元数据只有在完整的 PDF/X 基座之上才承重

用 SaveAsPdfVT 写文件

最简调用只需要一份活动文档,因为 TPdfVTSaveOptions.Default 自带内建 sRGB ICC 特性文件和 pvc1 合规级别。保存内部跑三步:去掉任何安全设置(往加密对象流里注入明文标记会把它弄坏),把文档已有的 Info 字典和 trailer /ID 桥接进标记集,让 XMP 与 Info 值保持一致,然后通过增量更新附加上 PDF/X-4 与 PDF/VT 对象

var
  Pdf: TPdf;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'statements-merged.pdf';
    Pdf.Active := True;
    // Default options: built-in sRGB OutputIntent, PDF/VT-1, synthesised DPart
    if Pdf.SaveAsPdfVT('statements-pdfvt.pdf') then
      Writeln('PDF/VT-1 written')
    else
      Writeln('Save failed (document not active?)');
  finally
    Pdf.Free;
  end;
end;

真正的生产输出,你几乎总是想用印刷机的特征化文件覆盖 OutputIntent,而不是通用的 sRGB 兜底。通过 TPdfVTSaveOptions 提供 ICC 字节和条件标识符:

var
  Pdf: TPdf;
  Opt: TPdfVTSaveOptions;
  Icc: TBytes;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'directmail-merged.pdf';
    Pdf.Active := True;
    Icc := LoadIccProfile('GRACoL2013_CRPC6.icc');  // 你自己的加载器

    Opt := TPdfVTSaveOptions.Default;
    Opt.Conformance := pvc1;            // 写入时 pvc2 会规范化为 pvc1
    Opt.IccProfileData := Icc;
    Opt.OutputConditionIdentifier := 'CGATS21_CRPC6';
    Opt.OutputCondition := 'Commercial print, coated, CRPC6';
    Opt.RegistryName := 'http://www.color.org';
    Opt.Title := 'Spring 2026 Direct Mail Run';
    Opt.Trapped := ptvFalse;           // PDF/X Info /Trapped state

    Pdf.SaveAsPdfVT('directmail-pdfvt.pdf', Opt);
  finally
    Pdf.Free;
  end;
end;

那段代码里有个细节是刻意设的护栏,不是可以跟你讨价还价的限制。设 Opt.Conformance := pvc2 并不会产出 PDF/VT-2 文件。写入器会把任何非 pvc1 的请求归一化回 pvc1,因为 PDF/VT-2 是文件集格式,一个只附加一份输出文档的单文件写入器在物理上就组装不出 §6.2.2 要求的外部资源集。pvc2 这个值是为读取路径存在的,让 ValidatePdfVT 能识别并报告一个已有的文件集文档;它不是写入目标

DPart 树:RIP 真正读取的结构

PDF/VT 的核心是文档部分(DPart)层级。它让印刷机能把一个长印批次切成记录,把记录分组为收件人或邮件捆,并附上文档部分元数据,让下游设备能按件路由和计费。ISO 16612-2 §6.5 给出了布线方式:catalog 携带 /DPartRoot,根 DPart 节点携带 /DPartRootNode 和为每个层级命名的 /NodeNameList,叶 DPart 覆盖页面树的一段范围,而属于某个部分的每一页都通过页面级 /DPart 条目指回它的叶节点

PDFium Component 图:供 RIP 消费的 PDF/VT DPart 层次——catalog 的 DPartRoot、根节点的 NodeNameList、覆盖页面范围的叶 DPart,以及页面级 DPart 回指引用
DPart 树是 RIP 用来划分记录并缓存共享内容的结构

当源文档已经带有可用的层级时,SaveAsPdfVT 会保留它。没有时,写入器会合成一个最小的:一个按顺序跨越当前页面树的单个文档级 DPart,每个活动页面对象都附加一个 /DPart 反向引用,外加一个单层级的 /NodeNameList [/Document]。对这个最小树是什么,要对自己诚实。它是满足 §6.5 形状要求的结构锚点,不是业务元数据。它变不出收件人、邮件件边界或产品批次,因为这些信息本来就不在源里。如果你有按收件人的数据,你应该自己建一棵更深的 DPart 树,并扩展 /NodeNameList 与你创建的层级匹配

超出键存在性检查的验证

ValidatePdfVT 返回一个 TPdfVTValidationResult 记录,带三样东西:检测到的 Conformance、一个 Issues 集合,以及只有当合规级别是真实级别且问题集为空时才为 true 的 IsCompliant 辅助属性。问题枚举刻意做得具体,所以失败结果会告诉你漏的是哪一条,而不只是“无效”:

示意图:Delphi 加 PDFium VCL 的 PDF/VT 验证管线——精确基座配对、递归 DPart 遍历、PDF/X-4 标记与 XMP 日期检查共同汇入 TPdfVTValidationResult 记录
ValidatePdfVT 报告具体哪一条不合,而不是笼统的“无效”判定
var
  Pdf: TPdf;
  Res: TPdfVTValidationResult;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'statements-pdfvt.pdf';
    Pdf.Active := True;
    Res := Pdf.ValidatePdfVT;

    if Res.IsCompliant then
      Writeln('PDF/VT compliant: ', VTLevelName(Res.Conformance))
    else
    begin
      if pvviMissingDPartRoot in Res.Issues then
        Writeln('DPart hierarchy missing or unusable');
      if pvviMissingPdfXIdentifier in Res.Issues then
        Writeln('PDF/X-4 base identifier absent');
      if pvviMissingOutputIntent in Res.Issues then
        Writeln('OutputIntent / ICC profile missing');
      if pvviEncryptionPresent in Res.Issues then
        Writeln('Encrypted - PDF/X forbids this');
    end;
  finally
    Pdf.Free;
  end;
end;

值得深入理解的两个检查是合规配对和 DPart 遍历,因为两者都很容易写得过于宽松。配对方面,验证器做精确匹配,不是“随便哪个 PDF/X 都行”:PDF/VT-1 文件只被接受在 PDF/X-4 基座上,PDF/VT-2 文件只在 PDF/X-4p、PDF/X-5g 或 PDF/X-5pg 上。坐在 PDF/X-1a 基座上的 PDF/VT-1 标记会被报告出来,而不是被挥手放行

DPart 遍历是大部分严格性所在的地方。catalog 有 /DPartRoot 键还不够,因为一个伪造的空对象或没有页面链接的对象照样没法用。HasValidDPartHierarchy 和递归的 ValidateDPartNode 会追整棵结构:跟随父链接,拒绝重复的子节点和环,强制 /Start 与 /DParts 互斥,并要求叶页面范围按深度优先顺序覆盖页面树、每一页的 /DPart 指向包含它的叶节点。所有这些内部错误都归并为单个 pvviMissingDPartRoot 问题位,而不是扩展公开枚举,所以请把这个标志理解为“DPart 层级不可用”,而不是字面的“根键缺失”

验证器强制执行的三个语法陷阱

§6.5 表 4 排除了几种乍看之下很合理的形状。这些正是手工搭的 DPart 树容易弄错的地方,值得明确点出来:

  • /DParts 是数组的数组,不是扁平数组。外层数组的每个元素本身必须是一个间接引用数组。扁平的 /DParts [9 0 R] 会被拒绝;合规形状是 /DParts [[9 0 R] [10 0 R]]。这挡住了非层级结构伪装成有效层级
  • /End 只标记真正的多页范围。叶 DPart 只有在同时有 /Start 时才能带 /End,且 /End 在页面树顺序里必须落在 /Start 之后。退化的 /Start 3 0 R /End 3 0 R 会让层级不可用,而不是被读成单页部分
  • /NodeNameList 的名称必须在做 PDF 名称反转义后仍是有效的 XML NMTOKEN。像 /Bad#20Name 这样的名称会展开出带空格的字符串,不是有效标记。实现做了一个轻量 ASCII 检查(字母、数字、.、-、_、:,加上非 ASCII 字节),能抓住空格和分隔符错误,又不拒绝合法的本地化或供应商专属名称

XMP 标记:写同一个属性的两种方式

PDF/VT 标识住在 XMP 的 pdfvtid 命名空间下,具体是 GTS_PDFVTVersion 和 GTS_PDFVTModDate,与标准的 xmp:CreateDate、xmp:ModifyDate 并排。一个会让天真的阅读器发出假“缺失”报告的微妙之处:这些条目中的任何一个都有两种序列化方式——元素文本(<pdfvtid:GTS_PDFVTVersion>PDF/VT-1</pdfvtid:GTS_PDFVTVersion>)或 description 元素上的 RDF 属性。PDFiumPas 两种形式都读,所以别的工具用属性风格写的文件不会被亏待。它还强制 §6.3 的一致性规则:GTS_PDFVTModDate 必须等于 xmp:ModifyDate;不匹配会抛 pvviModDateMismatch

同一条款还有一条规则:未知的 GTS_PDFVTVersion 值会保留为 pvcUnknown,而不是被折回 pvcNone。这个区分在操作上很重要。pvcNone 的意思是“根本没有 PDF/VT 标记,这是一份普通 PDF”,而 pvcUnknown 的意思是“有东西盖了一个这个验证器不认识的版本戳”(PDF/VT-2s 的情况包括在内)。把两者混为一谈,会把一份畸形文件藏进与普通文件相同的桶里

结构检查覆盖什么

把这些方法承诺的边界说清楚是值得的,因为可变数据打印的合规挂着真金白银。DPart 与配对检查是字节级的结构验证:确认优化骨架、PDF/X-4 基座标记、OutputIntent 和 XMP 都在且内部一致。内容层的 PDF/X-4 预检 — 颜色对照声明的输出条件、字体嵌入、透明度混合 — 是单独的一层。对要上合约印刷机的活,把 PDFiumPas 的结构验证与专门的 PDF/X 预检引擎和试印搭配起来,就像你对任何其他合规声明做 sanity check 一样。结构层抓的是那些悄悄破坏 RIP 缓存的失败;它是完整检查的一半,不是全部

如果你要把这些检查接进更宽的发布门禁,同样的字节级扫描方法也是这个库其他标准工作的地基,包括在文件抵达预检之前就验证对象流与交叉引用流,以及让文档天生对 RIP 友好的共享对象纪律——用 Form XObjects 做可复用页面戳背后讲的就是它。这里描述的 PDF/VT 与 PDF/X 保存和验证 API 属于面向 Delphi 和 C++Builder 的 PDFium VCL component,其产品页载有完整的合规参考