技術文章

PDFium XFA 存檔:換行、emoji 與 restoreState

XFA 理賠表單上一個空的 Comments 方框,重開後裡面躺著一個換行。再存檔重開一次,方框裡有兩個。用 U+1F642(微微一笑的臉)輸入的客戶名稱,回來變成 U+F642——一個大多數字體畫成空心矩形的私用區碼位。這三種現象全都活在 XFA 存檔寫進 datasets 封包的 XML 裡,而一條做對了的存檔路徑必須做到:別讓排版空白混進欄位值、把增補平面字元當成完整的代理對攜帶、寫入失敗要透過存檔結果回報而不是留下一個壞掉的檔案

哪個 PDFium 執行環境會存 XFA 值?

只有 pdfium.v8.dll 會存 XFA 值,因為它是唯一同時帶著 V8 JavaScript 引擎與 XFA 表單執行環境的 PDFium Component 建置。編輯一旦提交(欄位失焦,或 ClearFormFieldFocus 強制提交),這個執行環境就會在存檔時把活的 XFA 資料匯出進 datasets 封包,你的程式碼完全不用碰封包。每種 Windows 架構另外還附 pdfium.dll,不帶 V8 與 XFA,它把儲存的封包照讀進來的原樣寫回。欄位還有焦點時寫入的值會怎樣,在 XFA 欄位編輯為什麼存檔後消失一文有說明

Delphi 包裝器會試著替你選對函式庫。當 EnableV8Engine 還是 False、也還沒載入任何 PDFium 函式庫時,TPdf 會看一眼即將打開的檔案,如果找到 XFA 記號(AcroForm 字典裡的 /XFA 條目,或 catalog 裡的 /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 欄位會多出換行,是因為寫入器把 XML 排版成每個起始標籤後面補一個換行。一趟 XFA 存檔牽涉兩個寫入器——通用 XML 元素寫入器與表單封包序列化器——兩個都習慣這樣排版。在大多數 XML 文件裡這種空白只是美觀問題;在 XFA 資料裡它就是值:當 datasets 封包再次被剖析,<Comments> 與 </Comments> 之間的每個字元都屬於欄位,換行也不例外

PDFium Component 的 XFA 存檔循環示意圖:寫入器在起始標籤後補換行,重開的解析器把 Comments 標籤之間的 LF 當成欄位值讀回,每多存一次又追加一個換行,除非寫入器只移除它自己合成的空白
第一輪存檔重開種下第一個換行,之後每一輪再加一個——這正是走樣要到第二代才露出全貌的原因

所以空欄位重開後帶著一個 LF。之後每次存檔都圍著已經在那裡的 LF 排版,沒人碰過的欄位每過一輪審閱就多一行

載入時把值 trim 掉看似便宜的修復,其實會毀了真資料。人們會在 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,過濾落單代理的 serializer 則把 emoji 整個丟掉
Windows 的 wchar_t 只有 16 位元寬,需要代理對的純量值,要嘛丟掉前半、要嘛從 packet 消失,除非兩條路徑都讓成對的代理不分開

PDFium Component 的解碼器會把每個純量值完整吃掉、吐出正確的代理對,包括輸出緩衝區只剩一個碼元的空間、以及四位元組 UTF-8 序列橫跨兩個讀取區塊的情況。輸出端,表單匯出器讓合法的代理對不分家,數字字元參照也解碼成正確的代理對

Latin-1 測試資料永遠碰不到上述任何一條路徑。XFA 表單的 round trip 測試至少要在某個文字欄位裡放一個 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 的存檔可以重試、可以記 log、可以交給人處理;而被悄悄正規化掉的 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 處理器只從存好的 form 封包還原有限狀態,其餘交給表單自己的腳本。欄位值與重複子表單的實例數會回來;執行期設定的幾何屬性不會

設想一張三頁的表單,使用者填寫時腳本把某個子表單長到 h="450pt"。存好的 form 封包裡有新高度、欄位值與實例數。重開時,版面按範本高度重建,子表單縮回去,內容重排成兩頁。範本從未要求自動還原時,這正是 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 round trip

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;          // packet 陣列版面
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // 單一串流:一個未命名的 packet
      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 頁面通常沒有 widget 註解;那裡它會回傳 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 提供