在剛合併完的申請文件包第 1 頁的 Applicant 框裡打上姓名、按下 Tab,在許多檢視器裡,第 6 頁的 Applicant 框會自動填入同樣的文字。沒有人把這兩個控制項接在一起。文件包的第 1 部分與第 3 部分出自不同人之手,兩邊都把一個頂層欄位取名 Applicant,而 PDF 表單用完整限定名稱識別欄位。對檔案格式而言,兩個同名的欄位就是同一個欄位畫了兩次
解法是在合併發生之前就決定共用名稱該是什麼意思:拒絕它、刻意保留它,或替新來的改名。事後再決定,比聽起來難得多
ISO 32000 對欄位名稱的定義
欄位名稱就是身分,規範明說了這一點。ISO 32000-1 §12.7.3.2 由欄位與其各個祖先的部分名稱(T 項)以句點串接出完整限定名稱。同一節允許多個欄位字典共用一個完整限定名稱,並把它們描述為同一個底層欄位的不同呈現,彼此只應在外觀上有別。把兩份獨立撰寫的表單的 Fields 陣列串接起來,恰好就意外造出這種安排
損害程度取決於相撞的欄位裡裝了什麼。一個在一張表單指出生日、在另一張指出簽署日的 Date,現在只有一個值槽,檢視器最後採用的值會同時落在兩處。費用單上的 Total 與存款單上的 Total,任一邊一計算就會出現分歧。簽章欄位是最壞情況:不同頁的兩個簽章 widget、一個名稱,而簽署人實際核可的是哪個 widget 沒有乾淨的答案
大小寫也有影響。部分名稱就是文字字串,規範裡沒有任何折疊規則,所以 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) 次比較,幾百個欄位的文件包相較於剖析檔案本身,多出來的成本察覺不到
這個掃描的三個性質會在真實的表單文件包裡現身:
- 只有頂層欄位參與比對。在階層式表單裡,指的是父欄位的部分名稱,所以兩份各有一個叫
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 刻意保留共用名稱。在附加任何東西之前,目標欄位的值與預設值會被複製進傳入欄位,所以合併出的檔案一開始就是一致的,按名稱分組 widget 的檢視器看到的是一個邏輯欄位、一個值。兩個欄位字典仍是各自的物件,各留各的頁面、外觀與動作。把它們折疊成一個字典,會丟掉屬於傳入表單的格式與行為;為了表面的簡潔做這筆交易,不值得
dfsAutoNumber 以附加數字後綴的方式重新命名傳入的重複欄位,從 _2 起跳、取第一個空號。目標已有 Shared 與 Shared_2,新來的就成為 Shared_3。結果只取決於在場的名稱,從不取決於物件編號,所以同一對檔案合併兩次得到同樣的名稱——下游的 FDF 匯入與資料庫對應依賴的正是這個性質
兩個自動策略之間怎麼選,歸結為一個問題:填一個控制項該不該連帶填另一個?簽署人姓名在文件包每個部分都重複出現——該,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