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> 之間的每個字元都屬於欄位,換行也不例外
所以空欄位重開後帶著一個 LF。之後每次存檔都圍著已經在那裡的 LF 排版,沒人碰過的欄位每過一輪審閱就多一行
載入時把值 trim 掉看似便宜的修復,其實會毀了真資料。人們會在 XFA 欄位裡輸入前導空白、尾端空白和刻意換行;地址區塊必須保住它的分行結構,固定寬度的參考編號必須逐位元組存活。PDFium Component 的 XFA 寫入器改成只丟掉序列化器自己圍著標籤合成的空白。使用者輸入的值、檔案裡本來就有的文字節點與 CDATA 區段原樣通過,所以 " indented" 保持縮排,刻意留空的欄位保持空白
emoji、代理對與 16 位元的 wchar_t
當某條解碼路徑把完整的 Unicode 純量值塞進單一 wchar_t(在 Windows 上是 16 位元寬),emoji 回來就會變成另一個字元。XFA 載入有兩處暴露在這個風險下:UTF-8 串流解碼器,以及 🙂 這類數字字元參照的剖析器。U+1F642 需要 17 個位元。硬擠進 16 個位元,最高位元就掉了,剩下私用區的 U+F642
表單序列化器可能往反方向失敗。一次一個 wchar_t 地過濾字元時,它看到兩個代理碼元 D83D 和 DE42,各自單獨存在都算非法,於是兩個都丟掉。emoji 就從表單封包裡消失了,連替代字元都不留
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 串流分毫不動,文件保留修改標記,之後的存檔還能再試
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, '&', '&', [rfReplaceAll]);
Result := StringReplace(Result, '<', '<', [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 提供