技术文章

合并进来的 PDF 页面会在目录里抬高 PDF 版本

一份 2004 年扫描的合同开头是 %PDF-1.3,朴素的合并往里加了两页宣传册——带着内嵌 OpenType 字体和一张 16 位照片——pdfinfo 报告的仍然是 PDF 1.3。正确的版本号应以 /Version /1.6 的形式写进附加修订的目录,ISO 32000-1 §7.5.6 允许这么做,HotPDF 的页面导入则根据它复制的对象自动写入

为什么增量保存不能改写 %PDF-1.3?

因为旧字节必须继续作为新文件的前缀。增量更新在最后一个 %%EOF 之后追加新的文件体、新的交叉引用节和新的 trailer,之前的每个字节都原样不动。签名校验器依赖这一点,因为已有签名的 /ByteRange 覆盖旧文件头。修订对比工具走得更远,直接把“原文文件是新文件的前缀”当作增量保存的定义。在偏移零处修补八个字节,所有交叉引用偏移依然有效,前缀却断了。规范早就料到这一手。自 PDF 1.4 起,写入方可以用目录的 Version 条目覆盖文件头,§7.5.6 的注记 4 说明该条目存在的意义就是让版本号能在增量更新中变化。表 28 补充了读取规则:值是名字对象(/1.6,不是数字 1.6);仅当它晚于文件头时才生效;文件头更晚或条目缺席时,文件头说了算。生效版本取两者中较晚的那个。只检查文件第一行的阅读器,会低估每一份增量升级过的文档

Delphi 中用 HotPDF 合并 PDF 的增量更新布局:原封不动的 1.3 文件头保持为前缀,附加的目录携带 Version 1.6
增量更新中文件头那一行不能变,所以附加的目录携带所需的 Version 名字,阅读器取两者中较晚者

抬高所需版本的被复制对象

所需版本来自功能特性,而不是源文件的文件头。THPDFHeadlessDocument.AppendImportedPages 遍历它克隆的页面字典和资源,记录所有被复制的非空条目所需的最高版本。这些标记与 带功能检查保存到指定 PDF 版本用的是同一套;在这里它们向上运行,抬高声明级别。每行把导入执行的一项检查与 ISO 32000-1 标在该条目旁的版本配对:

被复制的内容需要规范依据
透明度组、软掩码(/SMask)或透明的 ExtGState 参数PDF 1.4透明度模型,§11
XMP 元数据流(/Type /Metadata /Subtype /XML)PDF 1.4§14.3.2
以 JBIG2Decode 压缩的图像数据PDF 1.4§7.4.7
以 JPXDecode 压缩的图像数据PDF 1.5§7.4.9
16 位图像,无论是图像 XObject 还是内容流里的内联图像PDF 1.5表 89,§8.9.7
非空的 /PresSteps;或样式为 Fly、Push、Cover、Uncover、Fade,或带 /SS 或 /B 的 /TransPDF 1.5表 30、表 162
随页面一起带入的可选内容PDF 1.5§8.11
带 /Subtype /OpenType 的 /FontFile3PDF 1.6表 126
页面 /UserUnit、锁定的图层,或 OCMD 可见性表达式 /VEPDF 1.6表 30,§8.11

Dissolve、Wipe、Split 这类老式过渡效果源自 PDF 1.1,不抬任何版本,所以导入读的是过渡字典的 /S 值;/Trans 光凭出现证明不了什么。写入发生在遍历之后。当所需版本存在,且大于目标文件头版本、也大于目录里已有的任何 /Version 时,/Version 名字才会写进新修订;否则目录不加 /Version 条目。文件头永远不动。§7.5.6 同一段还要求写入方在更新增删开发者扩展时更新目录的 /Extensions 字典;页面导入只复制页面级对象,/Extensions 保持目标文件原样

Delphi 中 HotPDF 页面导入的版本阶梯:OpenType 字体、16 位图像和透明度把需求从 1.3 一路抬到附加目录里的 1.6
导入遍历记录被复制条目所需的最高版本,Version 名字只有在同时压过文件头和既有覆盖值时才落进新目录
uses
  SysUtils, HPDFHeadlessDocument;

procedure AppendBrochurePages(const ContractFile, BrochureFile, OutputFile: string);
var
  Target, Source: THPDFHeadlessDocument;
  Options: THPDFHeadlessPageImportOptions;
  Outcome: THPDFHeadlessPageImportResult;
begin
  Target := THPDFHeadlessDocument.Create;
  Source := THPDFHeadlessDocument.Create;
  try
    Target.LoadFromFile(ContractFile);   // 文件头:%PDF-1.3
    Source.LoadFromFile(BrochureFile);   // PDF 1.7 导出:/FontFile3 /OpenType + 16 位照片

    Options := THPDFHeadlessPageImportOptions.Default;
    // 页面索引从零起算:复制封面和规格页
    Outcome := Target.AppendImportedPages(Source, [0, 2], Options);

    // 以增量更新保存:旧字节保持为前缀。
    // 预期结果:新目录修订携带 /Version /1.6,
    // 且文件第一行仍是 %PDF-1.3
    Target.SaveToFile(OutputFile);
    WriteLn(Format('%d pages added, %d annotations flattened',
      [Outcome.AddedPages, Outcome.FlattenedAnnotations]));
  finally
    Source.Free;
    Target.Free;
  end;
end;

这对文件里,OpenType 字体程序把需求定在 1.6,光那张 16 位照片本会停在 1.5。源和目标必须是两个不同的已加载文档。已签名或已认证的目标会被拒绝,因为追加页面改变的是签名所证明的内容

内联图像活在内容流里

内联图像永远不是对象。ISO 32000-1 §8.9.7 把它定义为直接写进内容流的 BI … ID … EI 序列,用缩写键(如 /BPC 代表 /BitsPerComponent),且只推荐给 4 KB 以内的小图。这里的 16 位深度和图像 XObject 一样需要 PDF 1.5,但对象遍历永远碰不到它——那些字节搭了被复制 /Contents 的便车。于是导入还要解码每个被复制页面的内容流,以及它克隆的每个 Form XObject 和平铺图案的内容流,各扫描一遍寻找深度为 16 的 BI 头。文本搜索会误报:show-text 操作符的操作数里可以躺着一个字面量 (BI /BPC 16 ID),注释行里也可以出现 % BI /BPC 16。ID 之后一个空白字节,接着就是原始二进制样本,直到两侧都有空白的 EI 记号才结束——这些样本字节碰巧也能拼出 BI。所以扫描器要跨过字面量字符串、十六进制字符串、注释和内联样本数据,停在第一个货真价实的 16 位头上。8 位内联图像,或者只是提到 /BPC 16 的字符串,都不会动版本

Delphi 中 HotPDF 页面导入查找 16 位内联图像的内容流扫描流程,途中跨过注释、字符串与形似的二进制内容
内联图像藏在被复制的内容流里,扫描器跨过注释、字符串和样本字节,直到真正的 16 位头现身

源文件的文件头决定版本吗?

不。是选中的页面决定它。把宣传册的 1.7 盖到合并结果上,只要那些页面用的没超出 PDF 1.3 绘图操作符,就是虚报。虚报的版本会让一份普通文档在按版本分流的打印工作流或归档网关里走错道。只对键名不对值犯的是同一个方向的错:/Mask null、/PresSteps null 和带 /S /Dissolve 的 /Trans 字典都含有那个惹眼的键,没有一个需要更新版本,而对键名起反应的扫描器会替从不需要它的文件抬高版本

PDF 1.2 文件里的 PDF 1.3 特性声明为 1.4

微妙的情况在版本区间的底部。显式图像掩码和色彩键图像掩码(表 89 的 /Mask)标记为 PDF 1.3。把这样一张图像复制进 %PDF-1.2 文档,严格需求是 1.3。可 /Version 机制 PDF 1.4 才有。往 1.2 文件里写 /Version /1.3,用的是声明级别根本没有的机制,严格的阅读器没有理由买账。HotPDF 在这种情况下声明 1.4:图像掩码进入文件头低于 1.3 的文档,需求直接抬到 1.4——覆盖机制合法的第一个版本。文件头已是 1.3 的目标,同一张图像根本不需要覆盖

如何读回生效版本?

取文件头版本,找目录的 /Version 名字,谁晚用谁。完整的解析器经由 trailer 的 /Root 到达目录。批处理里做个快速门禁,字节扫描通常够用,但有一条要事先说清:只有最新目录修订以普通对象形式写、不在任何 压缩对象流里时,扫描才找得到该条目。从文件末尾往前找。增量更新过的文件可以每个修订都有一份目录:原始的一份,之后每次更新一份完整的替换副本。阅读器对每个对象都用最近的副本(§7.5.6),所以文件里最后一个 /Version 通常属于活着的目录。结果为空意味着这次扫描没找到明文覆盖;解析器仍可能在对象流里找到一个。函数以字符串形式返回生效版本(如 1.6),紧随其后的门禁保护一条 PDF/A-1 通道,其基础标准 ISO 19005-1 建立在 PDF 1.4 上:

uses
  SysUtils, IOUtils;

function EffectivePdfVersion(const FileName: string): string;
const
  Key: RawByteString = '/Version';
var
  Bytes: TBytes;
  Text: RawByteString;
  P, Q: Integer;
  Declared: string;
begin
  Result := '';
  Bytes := TFile.ReadAllBytes(FileName);
  if Length(Bytes) < 8 then
    Exit;                                     // 长度不足,放不下 '%PDF-1.x'
  SetString(Text, PAnsiChar(@Bytes[0]), Length(Bytes));
  if Copy(Text, 1, 5) <> '%PDF-' then
    Exit;
  Result := string(Copy(Text, 6, 3));        // '%PDF-1.3' -> '1.3'

  // 最新修订在文件末尾,所以反向搜索
  P := Length(Text) - Length(Key) + 1;
  while (P > 0) and (Copy(Text, P, Length(Key)) <> Key) do
    Dec(P);
  if P = 0 then
    Exit;                                     // 未找到明文覆盖

  Q := P + Length(Key);
  while (Q <= Length(Text)) and (Text[Q] in [#0, #9, #10, #12, #13, #32]) do
    Inc(Q);
  if (Q < Length(Text)) and (Text[Q] = '/') then
  begin
    Declared := string(Copy(Text, Q + 1, 3)); // 名字对象:/1.6
    if Declared > Result then                 // 文件头更晚时文件头赢
      Result := Declared;
  end;
end;

procedure RequirePdfA1Channel(const FileName: string);
var
  Version: string;
begin
  Version := EffectivePdfVersion(FileName);
  if Version > '1.4' then
    raise Exception.CreateFmt(
      '%s declares PDF %s; the PDF/A-1 channel takes PDF 1.4 at most',
      [ExtractFileName(FileName), Version]);
end;

字符串比较行得通,因为已发布的每个 PDF 版本号的小数部分都只有一位,而 2.0 仍然排在所有 1.x 之上。注意门禁放过了什么:它不剥离 /Version 让文件蒙混过关,也从不单凭文件头下判断。只查文件头的检查会让合并后的合同通过——文件里装的仍是 PDF 1.6 的字体格式

面向仅限 1.4 的管线:拒绝或降级

删掉覆盖值是错误的修法。需要 1.6 的对象还在文件里,版本感知的阅读器会看到一个用着 1.6 字体格式的 1.3 文档,preflight 工具也会报告这种不一致。真正被限死在 1.4 的通道有两个像样的选项:在保存之前拒绝合并,拿生效版本当判据;或者先把源页面降到目标级别——在创作工具里转换字体和图像内容,再导入结果。早拒绝是更好的默认:作业还在跑时报错就指名文件和版本,比一周后谁也解释不了的校验失败省下太多的支持成本。有一项需求可以在导入时丢掉:Options.RemovePresentationSteps := True 让被复制的页面不带 /PresSteps,子页面导航于是不再抬高所需版本。决策属于保存时刻的场合,保存前的版本预检会在写出任何字节之前拦下作业

对 2004 年那份合同,要找的数字是 1.6。在运行 HotPDF Delphi PDF component 的 AppendImportedPages 的同一个服务里,对合并输出调用 EffectivePdfVersion。仅限 1.4 的通道由此可以拒收作业,而报错时还能点名抬版本的正是哪几页宣传册