THotPDF.AddXFAPacket / ClearXFAPackets / XFAPacketCount

THotPDF XFA forms container (v2.119.51)

註冊 named XFA（XML Forms Architecture）packet，以便輸出到檔案的 AcroForm /XFA entry 中。PDF 1.7 §12.7.6 + §12.7.8 允許 AcroForm 在 static /Fields array 旁邊（或取代它）攜帶 /XFA array，進而支援 hybrid AcroForm + XFA workflows 或純 dynamic XFA forms/XFA 項目。PDF 1.7 §12.7.6 + §12.7.8 允許 AcroForm 在靜態 /Fields 旁邊（或取而代之）攜帶 /XFA 陣列

Delphi 語法：

procedure AddXFAPacket(const PacketName: AnsiString; const XMLBytes: TBytes);

procedure ClearXFAPackets;

function XFAPacketCount: Integer;

說明

每次呼叫 AddXFAPacket 會註冊一個 named packet。典型名稱（依 XFA 3.3 specification 與 PDF 1.7 §12.7.8 Table 234）：

Each call to AddXFAPacket

template - form layout + scripts (the largest packet in most XFA documents).

datasets - data binding (the XML payload the template renders against).

config - viewer configuration.

connectionSet - external data connections.

localeSet - locale-specific formatting rules.

stylesheet - XSLT or CSS styling.

xfdf - XFDF form data overlay.

xmpmeta - XMP metadata.

signature - signature-related XFA data.

sourceSet - source-side data definitions.

在 EndDoc 時，每個已註冊 packet 會變成一個 indirect FlateDecode-compressed stream object，而 AcroForm /XFA array 會依註冊順序交錯 packet-name PDF strings 與 stream references，因此 layout 是 byte-deterministic。ClearXFAPackets 會移除所有已註冊 packets（適合跨多份檔案重用 THotPDF instance）。XFAPacketCount 回傳目前數量EndDoc 時,每個已註冊的 packet 都會成為一個間接的 FlateDecode 壓縮 stream 物件,AcroForm 的 /XFA 陣列會按註冊順序在 packet 名稱 PDF 字串與 stream 參照之間交替,布局因此是位元組確定的。ClearXFAPackets 移除所有已註冊的 packet（跨多份文件重用 THotPDF 實例時很有用）。XFAPacketCount

Container-level support only

HotPDF 不解析 XFA XML、不實作 XFA dynamic-layout engine、不執行 XFA template 內的 FormCalc 或 JavaScript，也不驗證 template structure。呼叫端自行撰寫 XFA XML（通常透過 Adobe LiveCycle Designer，或依 XFA 3.3 specification 手寫），HotPDF 會逐位元輸出這些 bytes

具備 XFA engine 的 consumer readers（舊版 Acrobat / Reader、FormsCentral、部分 kiosk products）會 render 表單；沒有 XFA engine 的 readers（2017 年後的 Adobe Reader DC、多數 open-source readers）若檔案是 hybrid AcroForm + XFA workflow，則會顯示 fallback AcroForm fields

PDF/A and PDF/X compliance gates

ISO 19005-1 §6.4.2 / ISO 19005-2 §6.4.2 / ISO 19005-3 §6.4.2 都明確禁止 XFA forms（dynamic-layout engine 無法確定性封存）。ISO 15930 prepress workflows 完全拒絕互動式表單。在任何非空 PDFACompliance 或 PDFXCompliance 下，AddXFAPacket 會立即以相關 spec reference raise。重複 packet names 會 raise。空 PacketName 或空 XMLBytes 會 raise。RequirePDFVersion(pdf15) 會自動提高檔案版本

ISO 19005-1 §6.4.2 / ISO 19005-2 §6.4.2 / ISO 19005-3 §6.4.2 all explicitly disallow XFA forms (the dynamic-layout engine is not deterministically archivable). ISO 15930 prepress workflows reject interactive forms entirely. AddXFAPacket 在任何非空的 PDFACompliance 或 PDFXCompliance 下會立即拋出例外,並附上相關規格參照。重複的 packet 名稱會拋出例外。空的 PacketName 或空的 XMLBytes 會拋出例外。RequirePDFVersion(pdf15)

AcroForm dictionary emission

只要 /Fields 至少有一個 entry，或至少註冊一個 XFA packet，就會輸出 AcroForm dict。未註冊 packets 的 pre-v2.119.51 呼叫端會維持 byte-identical /AcroForm output

The AcroForm dict is emitted when either /Fields 至少有一個項目,或至少註冊了一個 XFA packet。v2.119.51 之前不註冊 packet 的呼叫端,其 /AcroForm 維持位元組相同

Typical workflow (pure XFA dynamic form)

PDF.BeginDoc;

TemplateBytes := TFile.ReadAllBytes('form-template.xml');

DataBytes     := TFile.ReadAllBytes('form-data.xml');

PDF.AddXFAPacket('xdp:xdp', BytesOf('<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/">'));

PDF.AddXFAPacket('template', TemplateBytes);

PDF.AddXFAPacket('datasets', DataBytes);

PDF.AddXFASignaturePacket(SigBytes); { caller-generated XAdES }

PDF.AddXFAPacket('/xdp:xdp', BytesOf('</xdp:xdp>'));

PDF.EndDoc;

XDP wrapper, single-stream, dynamic, and signed XFA

The array /XFA form must open and close with xdp:xdp wrapper packets, as the example now shows (ISO 32000-1 §12.7.8). Related XFA APIs: SetXFADocument writes the whole XFA/XDP document as a single /XFA stream, mutually exclusive with AddXFAPacket; XFANeedsRendering sets the Catalog /NeedsRendering flag (ISO 32000-1 §7.7.2) so a viewer regenerates a dynamic XFA form on first open; AddXFASignaturePacket embeds a caller-generated XAdES / XML-DSig signature as the signature packet. HotPDF never generates or parses the signature - the caller produces it with an XML cryptographic library over the XFA datasets.

XFA-to-AcroForm flattening

ApplyXFAAsAcroForm 會將呼叫端提供的 XDP/XFA bytes 對應到目前頁面，成為 native AcroForm widgets 與簡單 page graphics。FlattenLoadedXFA 會對已載入且已攜帶 embedded /XFA packet 的 PDF 執行相同轉換。傳入 Editable=False 可讓產生的 widgets 變成 read-only，並檢查 XFAFlattenWarnings 了解無法對應的 elementsApplyXFAAsAcroForm 會把呼叫端提供的 XDP/XFA 位元組對映到目前頁面,成為原生 AcroForm widget 與簡單的頁面圖形。FlattenLoadedXFA 為已內嵌 /XFA packet 的已載入 PDF 執行相同轉換。傳入 Editable=False 可讓產生的 widget 變成唯讀,並檢視 XFAFlattenWarnings

請參閱： AcroForm 支援, THotPDF.RegisterAcroFormFont, THPDFPage.AddTextField