THotPDF.AddXFAPacket / ClearXFAPackets / XFAPacketCount

THotPDF XFA forms container (v2.119.51)

注册一个命名 XFA（XML Forms Architecture）包，用于写出到文档 AcroForm 的 /XFA 条目内。PDF 1.7 §12.7.6 + §12.7.8 允许 AcroForm 在静态 /Fields 数组之外（或取代它）携带 /XFA 数组，从而支持混合 AcroForm + XFA 工作流或纯动态 XFA 表单。

Delphi 语法:

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

procedure ClearXFAPackets;

function XFAPacketCount: Integer;

说明

每次调用 AddXFAPacket 注册一个命名包。典型名称见 XFA 3.3 规范与 PDF 1.7 §12.7.8 Table 234：

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 时，每个已注册的包都会成为一个间接的 FlateDecode 压缩流对象，AcroForm /XFA 数组按注册顺序交替排列包名 PDF 字符串和流引用，因此布局是字节确定的。ClearXFAPackets 移除所有已注册的包（在多个文档间复用 THotPDF 实例时很有用）。XFAPacketCount 返回当前计数。

Container-level support only

HotPDF 不解析 XFA XML，不实现 XFA 动态布局引擎，不执行 XFA template 中的 FormCalc 或 JavaScript，也不验证 template 结构。调用方自行编写 XFA XML（通常通过 Adobe LiveCycle Designer，或手写符合 XFA 3.3 规范的内容），HotPDF 按字节原样输出

带 XFA 引擎的阅读器（旧版 Acrobat / Reader、FormsCentral、部分 kiosk 产品）会渲染表单；没有 XFA 引擎的阅读器（2017 年后的 Adobe Reader DC 以及多数开源阅读器）会在 hybrid AcroForm + XFA 工作流中显示 fallback AcroForm 字段

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 表单（动态布局引擎无法确定性地归档）。ISO 15930 印前工作流则完全拒绝交互式表单。只要 PDFACompliance 或 PDFXCompliance 非空，AddXFAPacket 会立即带着相关规范引用抛出异常。重复的包名会抛出异常。空的 PacketName 或空的 XMLBytes 会抛出异常。RequirePDFVersion(pdf15) 自动提升文档版本。

AcroForm dictionary emission

只要 /Fields 至少有一个条目，或至少注册了一个 XFA 包，就会写出 AcroForm 字典。v2.119.51 之前未注册任何包的调用方，其 /AcroForm 输出保持字节一致。

典型工作流 (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

数组形式的 /XFA 必须以 xdp:xdp 包裹包开头和结尾,如示例现在所示(ISO 32000-1 §12.7.8)。相关 XFA API:SetXFADocument 将整个 XFA/XDP 文档写为单个 /XFA 流,与 AddXFAPacket 互斥;XFANeedsRendering 设置 Catalog 的 /NeedsRendering 标志(ISO 32000-1 §7.7.2),使阅读器在文档首次打开时重新生成动态 XFA 表单;AddXFASignaturePacket 将调用方生成的 XAdES / XML-DSig 签名作为 signature packet 嵌入。HotPDF 从不生成或解析签名——由调用方用 XML 加密库对 XFA datasets 生成。

XFA 到 AcroForm 扁平化

ApplyXFAAsAcroForm 会把调用者提供的 XDP/XFA 字节映射到当前页面，生成原生 AcroForm 控件和简单页面图形。FlattenLoadedXFA 对已加载且含有嵌入 /XFA 数据包的 PDF 执行同样转换。传入 Editable=False 可将生成控件设为只读，并可通过 XFAFlattenWarnings 查看无法映射的元素。

另请参阅: AcroForm 支持, THotPDF.RegisterAcroFormFont, THPDFPage.AddTextField