技术文章

在 Delphi 中合并 PDF 表单:重复字段规则

在一份刚合并的申请包的第 1 页 Applicant 框里输入名字,按下 Tab,在很多查看器里第 6 页的 Applicant 框会填上同样的文字。没有人把这两个控件连在一起。包的第 1 部分和第 3 部分出自不同作者之手,都把顶层字段命名为 Applicant,而 PDF 表单用完全限定名来标识字段。对文件格式来说,同名的两个字段就是被画了两次的同一个字段

解决办法是在合并发生之前就决定共享的名字意味着什么:拒绝、有意保留,还是给新来的改名。事后才做决定比听起来难得多

ISO 32000 对字段名的定义

字段名就是身份,规范明说了这一点。ISO 32000-1 §12.7.3.2 用字段及其每个祖先的部分名(T 条目)以句点连接构成完全限定名。同一节还允许多个字段字典共享一个完全限定名,并把它们描述为同一个底层字段的不同表示,彼此只应在外观上有差别。把两份独立创作的表单的 Fields 数组拼接起来,恰好就会意外产出这种布局

损害大小取决于相撞的字段装的是什么。一个表单上表示出生日期、另一个表单上表示签署日期的 Date,现在只有一个值槽,查看器定了哪个值就落在两处。费用表上的 Total 和押金单上的 Total,只要有一边参与计算就会立刻打架。签名字段是最坏的情形:不同页上的两个签名部件、一个名字,签署人到底认可了哪个部件没有干净的答案

大小写也重要。部分名是文本字符串,规范里没有任何折叠规则,所以 Total 和 total 是两个字段。比较前把名字转小写的冲突检查会报告根本不存在的冲突,而在改名策略下,它会给没人需要动的字段改名

在任何东西动起来之前检查名字

PDF Library for Delphi 把冲突处理放在 MergeDocumentEx(DocumentID, DuplicateFieldStrategy) 里,它把 DocumentID 标识的文档合并进当前选中的文档,并在任何一个对象被重新编号之前解决全部名称冲突。策略是一个 TPDFlibDuplicateFieldStrategy 值:dfsReject、dfsMerge 或 dfsAutoNumber。朴素的 MergeDocument 仍然原样拼接两份根字段数组——当你同时拥有两份表单、清楚它们的名称不相交时,这正是正确的选择

顺序就是整个设计。合并必须平移来源文档的对象编号以免与目标相撞,把它的页缝进目标的页树,再把它的字段附加到表单上。如果冲突在这些步骤之后才暴露,拒绝就不再是免费的了——目标已经吸收了页面,来源的对象带着两个文件原本都没有的编号,调用方除了把两个文件从磁盘重新加载之外没有任何状态可退。MergeDocumentEx 先把两份文档的顶层字段名收进一个有序、区分大小写的集合,再对着这个集合应用策略。在 dfsReject 下,冲突让调用返回 0,LastErrorCode 置为 705,两份文档保持加载时的原样:拒绝之后你立刻从来源文档读一个字段值,拿回来的仍是原文

扫描本身很便宜。目标 n 个名字、来源 m 个名字,把它们排成一个集合的代价是 (n + m) log(n + m) 量级的比较,几百个字段的包相对于解析文件的开销根本不构成可感知的增量

PDF Library for Delphi:操作顺序图:对比旧式合并——重编号和页面树拼接之后才发现重复字段名——与 MergeDocumentEx 先收集名称,因此拒绝时两个文档都保持原样
重新编号与页面树拼接发生在旧版合并检查字段名之前,届时已无法干净回滚。MergeDocumentEx 事先比较有序且区分大小写的名称集合,把拒绝变成一次干净的无操作

扫描有三条性质会出现在真实的表单包里:

  • 只比较顶层字段。在层级表单里这意味着父字段的部分名,所以两份各有一个叫 applicant 的父字段的表单即使子字段不同也会冲突,而自动编号改的是父字段的名字:新来的子字段随后读作 applicant_2.name 和 applicant_2.address
  • 来源名字在检查的同时加入集合。一份已经带着两个同名顶层字段的来源文档,会在第二个名字上触发策略,哪怕目标根本没有同名字段
  • 部分名为空的字段被跳过;任一文档没有 AcroForm 时无可比较,任何策略下合并都直接进行

加载侧有一个自己的陷阱。LoadFromFile 向库添加新文档并选中它,所以要留住的标识符是每次加载之后 SelectedDocument 返回的那个。加载之前先去拿,你手里握着的就是另一份文档,不是你以为要合并进去的那份

uses
  SysUtils, PDFlibrary;

procedure BuildPack(const Part1, Part2, OutFile: WideString);
var
  Lib: TPDFlib;
  TargetDoc, SourceDoc: Integer;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile(Part1, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part1]);
    TargetDoc := Lib.SelectedDocument;   // 在加载之后读,不要在之前

    if Lib.LoadFromFile(Part2, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part2]);
    SourceDoc := Lib.SelectedDocument;

    Lib.SelectDocument(TargetDoc);       // 被选中的文档接收合并
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // 顶层名称重复:两份文档都完好无损,
      // 所以 SourceDoc 可以直接用于第二次尝试
      WriteLn('Duplicate field names in ', Part2, ', retrying with auto-numbering');
      if Lib.MergeDocumentEx(SourceDoc, dfsAutoNumber) = 0 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
    end;

    Lib.SaveToFile(OutFile);
  finally
    Lib.Free;
  end;
end;

先严格后宽松。这个两步形态之所以成立,是因为拒绝让 SourceDoc 保持加载且完好;若合并走到一半才失败,回退分支就得从重新加载两个文件开始。专门检查 705 也很要紧,因为无效的文档标识符或越界的策略值会以别的错误码失败调用,换一个策略重试对这两种情况都无济于事

选策略:拒绝、共享还是重新编号

无人值守的流水线,把 dfsReject 设为默认,把 705 当成给来源表单责任方开的工单。上游改一次字段名,比几个月后才发现某个导出映射因为合并发明了 Total_2 而悄悄失配便宜得多。自动策略值得用的场景,是人已经看过这些表单、想清楚了共享名字的含义

dfsMerge 是有意保留共享名。在附加任何东西之前,目标字段的值和默认值会被复制进新来的字段,所以合并出的文件一开始就一致,按名字归组部件的查看器看到的是一个逻辑字段、一个值。两个字段字典仍是分开的对象,各自保留自己的页面、外观和动作。把它们折叠成一个字典会丢掉属于来源表单的格式和行为,为了一点外观上的简化做这种交换不值

dfsAutoNumber 给新来的重复名字追加数字后缀,从 _2 起找第一个空位。目标已有 Shared 和 Shared_2,新来的就成了 Shared_3。结果只取决于在场的名字,从不受对象编号影响,所以同样两个文件合并两次得到同样的名字——下游的 FDF 导入和数据库映射依靠的正是这条性质

PDF Library for Delphi:MergeDocumentEx 之后三种重复字段结果:dfsReject 返回错误 705 且两个表单完好,dfsMerge 将同名部件同步为一个逻辑值,dfsAutoNumber 追加可复现的 _2 后缀
dfsReject 保持两个文档原封不动以便知情重试,dfsMerge 把多个同名部件视为持有同步值的单个逻辑字段,dfsAutoNumber 则发放稳定的带后缀名称,外部映射必须预先考虑

两个自动策略之间的选择归结为一个问题:填一个控件该不该填另一个?签署人姓名在包的每个部分重复出现,该,dfsMerge 合适。每张表单各算各的合计,不该。这里选 dfsAutoNumber,或者更好,在来源表单里把字段改名,让后缀根本不出现

合并之后表单里有什么?

目标有一个顶层文本字段 Shared,值为 “Target value”;来源有自己的 Shared。dfsMerge 之后,FormFieldCount 数出两个字段,标题都是 Shared,值都报告 “Target value”。dfsAutoNumber 之后,同样的输入得到 Shared 和 Shared_2,新来的字段保留它在来源文件里的原值

dfsMerge 的结果有一道锋利的边,位置就在你自己的填写代码里。FindFormFieldByTitle 返回第一个标题匹配的索引,SetFormFieldValue 只写一个字段。一个查一次 Shared 就设置的例程,更新的是目标的副本,新来的副本还握着合并那一刻收到的值。保存的文件里从此有两个同名字段、两个不同的值,查看器显示哪个全看它心情。把每个匹配都写一遍:

// 设置所有名为 Title 的字段;返回写入的个数。
// dfsMerge 合并后,一个逻辑字段可能出现在多个索引上
function SetAllFieldsNamed(Lib: TPDFlib; const Title, Value: WideString): Integer;
var
  I: Integer;
begin
  Result := 0;
  for I := 1 to Lib.FormFieldCount do
    if Lib.GetFormFieldTitle(I) = Title then
    begin
      if Lib.SetFormFieldValue(I, Value) = 1 then
        Inc(Result)
      else
        WriteLn(Format('Field %d (%s) not written, error %d',
          [I, Title, Lib.LastErrorCode]));   // 只读字段会落到这里
    end;
end;

把合并出的包接进数据源之前,先把合并实际产出的东西倒出来看。两行循环就够了,它会在导入任务之前抓住被改名的父字段和 _2 后缀:

for I := 1 to Lib.FormFieldCount do
  WriteLn(Format('%3d  %-30s  %s',
    [I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));

实践中组装表单包

成功的合并会消耗来源文档。它从库的文档列表中移除,DocumentCount 减一,旧的 SourceDoc 标识符不得再用。合并后的文档取两个 PDF 版本中较高的那个:把 PDF 2.0 表单合进 1.7 文档得到 2.0 文件——如果下游的归档步骤要求特定版本,这一点就有分量

合并顺序决定哪些名字活下来。被选中的文档保住自己的每一个名字,改名和值复制只落在新来的字段上,所以 A 合进 B 和 B 合进 A 得到不同的自动编号结果。当包里有一份主表单——后台系统已经认识它的字段名的那份——让它当目标,把补充表单合进去

最后签名。签名覆盖的是它签署的那个修订版的字节,而合并会重写文件,所以组装前签署的部分不再携带与文档匹配的签名。先组装包、检查字段列表,再对完成的文件应用签名。如果任务只是把页面拼在一起、表单无关紧要,通过字节引用偏移实现的快速 PDF 合并是更快的路

把数据侧和合并一起规划。如果字段值来自一个按名字寻址字段的外部系统,选 dfsAutoNumber 之前先谈妥命名,因为 Shared_2 不会匹配期待 Shared 的映射。值的导入导出格式见FDF、XFDF 和 XFA 表单数据交换。按名字引用字段的计算脚本和动作受改名的影响完全一样,交互式表单动作与 JavaScript 展示了这些引用的位置

感知重复的表单合并、字段填写和数字签名都属于同一个库,服务 Delphi、C++Builder 和 Free Pascal 项目。PDF Library for Delphi 产品页列出了其余的表单与文档组装 API