技术文章

PDFium Component XFA:换行、emoji 与 restoreState

XFA 索赔表单上一个空的备注框,重开时多了一条换行;再保存重开一次,变成两条。用 U+1F642(微微笑脸)输入的客户名字回来成了 U+F642——一个大多数字体画成空心方框的私用区码点。这三种效果都住在 XFA 保存写进 datasets 包的 XML 里,要把它们全做对的保存路径,必须不让排版空白混进字段值、把增补平面字符按完整的代理对携带,并通过保存结果而不是损坏的文件来报告一次失败的写入

哪个 PDFium 运行时能保存 XFA 值?

只有 pdfium.v8.dll 能保存 XFA 值,因为它是唯一同时携带 V8 JavaScript 引擎和 XFA 表单运行时的 PDFium Component 构建。编辑一旦提交(字段失焦,或 ClearFormFieldFocus 强制提交),该运行时就会在保存时把活动的 XFA 数据导出进 datasets 包,你的代码不需要对包动手术。每种 Windows 架构还附带一个不带 V8 和 XFA 构建的 pdfium.dll,它把存储的包按读取时的原样写回。字段仍有焦点时写入的值会怎样,见为什么 XFA 字段编辑在保存时消失

Delphi 包装层会替你挑合适的库。当 EnableV8Engine 还是 False、且尚未加载任何 PDFium 库时,TPdf 会看它即将打开的文件,一旦发现 XFA 标记(AcroForm 字典里的 /XFA 条目,或目录里的 /NeedsRendering true)就在加载前把 EnableV8Engine 打开。这个开关每个进程只生效一次。如果会话的第一份文档是普通 PDF、普通的 pdfium.dll 已经驻留,进程就认定了它,之后来了 XFA 文档时 TPdf.OnXfaRuntimeMissing 触发

默认搜索顺序是问题的另一半。LibraryName 里没有目录时,加载器从应用程序目录或其某个父目录下的 DLLs\Win32 或 DLLs\Win64 文件夹找起,于是旧版 pdfium.v8.dll 可能先被找到。含目录的 LibraryName 精确钉住那个文件,文件缺失时加载直接失败

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // LibraryName 里的目录钉死这个文件;
  // 文件缺失时 LoadLibrary 直接报错,不另寻别处
{$IFDEF WIN64}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win64\pdfium.v8.dll';
{$ELSE}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win32\pdfium.v8.dll';
{$ENDIF}
  PDFium.EnableV8Engine := True;
  PDFium.LoadLibrary;  // 在启动时失败,而不是在第一次 XFA 保存时
end;

文档打开后,TPdf.XFA 说明文件含 XFA,TPdf.XfaRuntimeAvailable 说明加载的库真能为这份文档启动 XFA 引擎。静态与动态表单经 TPdf.FormType 区分,动态表单返回 ftXfaFull,静态表单返回 ftXfaForeground。在没有 V8 运行时的机器上做包级探测,是在 Delphi 里检测 XFA 表单并提取 XFA 包的主题

保存后的 XFA 字段为什么会多出换行?

当写出器为了美化而在每个起始标签后加换行时,保存的 XFA 字段就会多出换行。一次 XFA 保存涉及两个写出器——通用 XML 元素写出器和表单包序列化器——两者都习惯那样格式化输出。在多数 XML 文档里这种空白是装饰性的;在 XFA 数据里它就是值:datasets 包再次被解析时,<Comments> 与 </Comments> 之间的每个字符都归字段所有,换行也不例外

PDFium Component XFA 保存周期示意图:写出器在开始标签后加换行,重开时的解析器把 Comments 标签之间的 LF 当作字段值读入,除非写出器只删掉自己合成的空白,否则每多保存一次就再追加一个换行
一轮保存重开种下第一个换行,此后每轮再加一个——所以偏差要到第二代才显出全貌

于是空字段重开时带着一个 LF。每多一次保存都在已有的 LF 周围格式化,所以一个没人碰过的字段,每过一轮审阅就多长一行

加载时修剪值看起来是廉价的修复,却会损坏真实数据。用户会往 XFA 字段里输入前导空格、尾随空格和刻意的换行;地址块必须保住行结构,定宽参考代码必须逐字节存活。PDFium Component 的 XFA 写出器改为只丢弃序列化器自己在标签周围合成的空白;用户值、文件里本来就有的文本节点和 CDATA 段原样通过," indented" 保持缩进,刻意留空的字段保持为空

emoji、代理对与 16 位 wchar_t

当某条解码路径把完整的 Unicode 标量值塞进单个 wchar_t——在 Windows 上是 16 位宽——emoji 回来时就变了字符。XFA 加载里有两个落点:UTF-8 流解码器,以及 &#x1F642; 这类数字字符引用的解析器。U+1F642 需要 17 位,塞进 16 位后最高位掉落,留下私用区里的 U+F642

表单序列化器可能朝相反方向出错。一次一个 wchar_t 地过滤字符时,它看到两个代理码元 D83D 和 DE42,各自孤立时都非法,于是把两个都丢掉。emoji 从表单包里消失,连替换字符都不剩

PDFium Component 代理处理示意图:U+1F642 以 UTF-16 对 D83D DE42 到达,两条天真路径都能损坏它——16 位 wchar_t 解码器把标量截断成私用区里的 U+F642,而过滤孤立代理的序列化器会把 emoji 整个丢掉
Windows 的 wchar_t 是 16 位宽,需要代理对的标量要么丢掉高半段、要么从包里消失——除非两条路径都把代理对保持在一起

PDFium Component 里,解码器完整消费每个标量值并产出正确的代理对,包括输出缓冲只剩一个码元空间时,以及四字节 UTF-8 序列被两个读块切断时。输出方向上,表单导出器把合法代理对保持在一起,数字字符引用也解码成正确的代理对

Latin-1 测试数据永远碰不上这些路径。XFA 表单的往返测试至少要在某个文本字段里放一个 U+FFFF 以上的字符,而检查保存字节里有没有四字节 UTF-8 序列 F0 9F 99 82,比看渲染出来的字段更能说明问题

单流 XFA 与保存结果

单流 XFA 文档只有在保存路径能原地重写一条 XDP 流时才保得住编辑,而任何它重写不了的输入都必须让保存失败。ISO 32000-1 §12.7.8 允许交互式表单字典的 /XFA 条目要么是包名与流交替的数组,要么是承载整个 XDP 文档的单一流。只为数组写的保存路径会拒绝单流,如果调用方又无视那个结果,PDF 就带着旧值的表单数据被写出

PDFium Component 的 V8 运行时分三步处理一个有明确界定的单流子集。它把两个活动包 datasets 和 form 导出到暂存区并验证,然后才替换原 XDP 里对应的包,保留其他包和根命名空间声明。暂存失败时,持久化的 XFA 流绝不会被碰,文档保留修改标记,之后的保存可以再试

PDFium Component 的单流 XFA 保存管线:活动的 datasets 与 form 包导出到暂存、校验,然后带着经标记保留的注释替换进原 XDP;暂存失败与 DTD、XMLDSig 之类输入显式拒绝保存
暂存导出先校验、后替换,保存失败于是动不了持久的 XFA 流,文档保留修改标记

XML 注释和处理指令需要额外小心,因为重写用的解析器会把它们丢掉。每一条都在解析前被换成一个唯一标记、之后放回原位,且只有每个标记都恰好出现一次时才写出流,所以活动包之外的注释保住了文本和顺序

有些输入会被直接拒收,每一次拒收都以保存失败的形式到达你这里:

  • 活动 datasets 或 form 包内部的注释或处理指令,因为它们原本的位置无法映射进新导出的内容
  • DTD 声明和 XMLDSig 签名,因为重写 XDP 保不住 XML 签名的有效性
  • 无效的 UTF-8 或 UTF-16、未闭合标签、无效字符引用、未知实体和畸形的处理指令——被拒收,而不是当场修好

在这里,拒收是更好的取舍。返回 False 的保存可以重试、记日志或交给人处理,而被悄悄归一化的 XDP 可能几周后在远离改动它的代码的地方弄坏一个签名或一个下游导入器。单流路径保住的是 XML 内容模型,以 UTF-8 写出;源流的原始字节布局和编码声明不随行

最后一块缓冲

最后一个陷阱在 XFA 之下、通用 PDF 写出器里。以固定大小块缓冲输出的文件写出器,必须在收尾时把最后一块不完整的缓冲推出去。如果这发生在文档写出器已经报告成功之后的清理代码里,最后一块上的磁盘满或 I/O 错误就到不了调用方,磁盘上的文件是短的。两个 PDFium Component 运行时里,最终刷写都是保存结果的一部分,XFA 修改标记只在写入真正成功之后才清除

Delphi 侧再加一层。TPdf.SaveAs 先写到目标旁边的临时文件,只有流保存返回 True 才把它移到目标上。False 结果让旧文件原封不动,最后的替换失败会抛操作系统错误而不是安静返回

动态 XFA 表单为什么重开时页数变少?

动态 XFA 表单在根子表单没有声明 restoreState="auto" 时重开页数变少,而这个决定属于表单作者。XFA 3.3 里,根子表单的 restoreState 默认是 manual。manual 之下,XFA 处理器只从保存的表单包恢复有限状态,其余交给表单自己的脚本。字段值和重复子表单的实例数会回来;运行时设置的几何属性不会

设想一张三页表单,脚本在用户填写时把一个子表单长到 h="450pt"。保存的表单包里装着新高度、字段值和实例数。重开时布局按模板高度重建,子表单缩回去,内容回流成两页。模板从未要求自动恢复时,这正是 XFA 规范要求的行为。在根子表单上声明它,重开就变了:

<template xmlns="http://www.xfa.org/schema/xfa-template/3.3/">
  <subform name="form1" layout="tb" restoreState="auto">
    <pageSet>
      <pageArea name="Page1">
        <contentArea x="0.25in" y="0.25in" w="8in" h="10.5in"/>
        <medium stock="letter"/>
      </pageArea>
    </pageSet>
    <subform name="Details" layout="tb" w="7.5in">
      <!-- 字段;脚本可能在运行时改 h 或增加实例 -->
    </subform>
  </subform>
</template>

模板不归你管,就别动它:为 manual 模式构建的表单,指望自己的初始化脚本来重建状态,把它们脚下的模式一换,脚本围绕编写的那些假设就变了。用户打字时的实时重排版是另一个机制,见PDFium Component 如何跟踪动态 XFA 页数与迁移字段

从 Delphi 检查一次 XFA 往返

验证一次 XFA 保存,要在一个全新的 TPdf 实例里重开保存后的文件、把存下的数据读回来,因为 SaveAs 的 True 只说明文件写出来了。TPdf.GetXfaDatasets 返回文档里存储的 datasets 包,不是活动的数据模型,所以保存之前读它看到的是上一次加载的值;重开之后读它,看到的就是写进去的东西。单流文档没有单独命名的包:PDFium 把整个 XDP 报成一个空名包,于是 GetXfaPacketByName('datasets') 和 GetXfaDatasets 都返回空数组,下面的代码回退到 GetXfaFormPackets 的完整流

uses
  System.SysUtils, PDFium, FPdfXfa;

function ReadSavedXfaData(const FileName: string): string;
var
  Pdf: TPdf;
  Packets: TXfaPacketList;
  Bytes: TBytes;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    Bytes := Pdf.GetXfaDatasets;          // 包数组布局
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // 单流:一个未命名包
      if Length(Packets) = 1 then
      begin
        SetLength(Bytes, Length(Packets[0].Content));
        if Length(Bytes) > 0 then
          Move(Packets[0].Content[0], Bytes[0], Length(Bytes));
      end;
    end;
    Result := TEncoding.UTF8.GetString(Bytes);  // 存出的 XDP 输出是 UTF-8
  finally
    Pdf.Free;
  end;
end;

保存例程提交挂起的编辑、检查 SaveAs 结果、再比对重开后的值。TPdf.ClearFormFieldFocus 移除表单焦点,那正是 PDFium 提交焦点字段编辑缓冲的时刻。TPdf.SetFocusedFormFieldText 能从代码填充焦点字段,但它依赖经 widget 注释跟踪的焦点,而动态 XFA 页面通常没有;在那里它返回 False,文字通常经 TPdfView 的键盘输入到达

// XmlText 是你自己加的辅助函数;它不是 PDFium Component 的一部分
function XmlText(const S: string): string;
begin
  Result := StringReplace(S, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [rfReplaceAll]);
end;

procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
  Expected: string);
var
  Saved: string;
begin
  // 可选的脚本化填充;False 表示没有受跟踪字段持有焦点
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // 提交编辑缓冲
  if not Pdf.SaveAs(FileName) then      // False:旧文件原地不动
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // 在全新的 TPdf 里重开,找那个精确的元素文本
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

子串测试只是冒烟测试。空元素可能写成 <Tag/>,数据元素可以带属性,& 和 < 之外的转义由序列化器做主,所以生产检查该交给真正的 XML 解析器。同一个输入连跑两遍这个例程,因为换行漂移要到第二代才显出全貌

直接驱动 XFA 运行时的宿主应用还需要它期望的回调布局,那是Delphi 里的 FPDF_FORMFILLINFO version 2 与 XFA ABI 的主题。Win32 与 Win64 两个 Windows 运行时、Delphi 和 C++Builder 包装层以及 TPdfView 查看器控件,都随 PDFium Component for Delphi and C++Builder 交付