Form

速览

NextPDF Pro 读取并写入交互式表单数据：AcroForm 字段值、XFDF 数据文件，以及由 XFA（XML Forms Architecture）模板所携带的数据。它在开源 Core 表单读取器之上，补充了数据绑定、提取和序列化能力。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）发布，并以一份 Pro 层级的授权信封（license envelope）激活。没有该权益的部署不会加载此能力的类。比较各版本并获取授权。

Form 是 Pro 版本的一部分。没有单独的按功能授权标志。

安装

composer require nextpdf/pro:^3

Form 能力需要一份有效的 NextPDF Pro 授权。参见可用性与授权。

概念概述

一份 PDF 交互式表单 —— 有时称为 AcroForm —— 按 ISO 32000-2 §12.7 的定义，将每个字段存储在一个字段字典中。NextPDF Pro 在 Core 表单读取器之上增加了三项能力：

• AcroForm 往返。 FormDataExtractor 从已解析的表单字段中读取字段名/值对，并产出一个 XfdfData 对象或一个普通的 name → value 映射。XfdfWriter 执行相反的操作，生成一份 XFDF 文档。
• XFDF 读取与写入。 XFDF 是由 ISO 19444-1:2019 描述的、用于表单值的 XML 数据交换格式。XfdfParser 将一份 XFDF 文件读入结构化数据；XfdfWriter 将字段值序列化为 XFDF，并可选地附带一个指回源 PDF 的引用。
• XFA 数据提取。 XfaParser 定位文档中的 XFA 包（packet），拼接其中的 XML 片段，并将 template 和 datasets 包解析为结构化的字段数据。

XFA 支持范围

NextPDF Pro 中的 XFA 支持是面向数据的，而不是一个完整的 XFA 渲染或脚本引擎。解析器提取并结构化 template 和 datasets 包，让你能读取字段定义和值。它不执行 XFA 表单计算脚本、不渲染动态 XFA 布局，也不对每一种 XFA 包类型进行往返。在依赖它处理某一套给定的 XFA 表单之前，请针对你的具体文档测试解析器。所有 XML 解析都禁用了外部实体加载（XXE 安全）。

为什么这样设计

XFA 支持被有意地限定在数据层面，而非渲染。ISO 32000-2 将表单字典的 XFA 条目在 PDF 2.0 中标记为已弃用（§12.7）。一个完整的 XFA 布局与脚本引擎会去追逐一个大多数工作负载已不再需要的遗留面。NextPDF Pro 转而提取 template 和 datasets 包 —— 持久的字段数据正存于其中 —— 并舍弃其余部分。同样的取向也驱动了 XXE 关闭解析和扫描上限，因为表单输入常常来自不受信任的一方。这让 Pro 表单面保持为 Core AcroForm 模型的一层薄而可预测的扩展。

设计背景：从可填写表单到冻结记录：AcroForm 填充与扁平化。

API 接口

类	职责
FormDataExtractor	将 AcroForm 字段值提取为 XfdfData 或一个数组。
XfdfParser	将一份 XFDF 文档解析为结构化数据。
XfdfWriter	将字段值序列化为 XFDF，可选 PDF 引用。
XfaParser	提取并解析 XFA template 和 datasets 包。
FormDataBinder	将一个数据映射绑定回表单字段。

完整的方法级参考见 Form 深度参考。

代码示例 —— 快速上手

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

代码示例 —— 生产环境

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

边界情况与注意事项

• XfaParser 会拒绝大于其扫描上限的 PDF 输入，而不是无界地读取数据。
• 一份文档可能同时携带交互式和非交互式表单；提取以终端字段字典为目标。
• XFDF 对扁平字段结构进行往返；深度嵌套的字段层次可能需要显式处理。

性能

提取和序列化随表单字段数量呈线性。XFA 解析开销随嵌入 XML 包的大小而扩展。

安全说明

所有 XML 解析都禁用外部实体解析以防止 XXE。请将来自不受信任来源的 XFDF 和 XFA 输入视为恶意内容，并在将所解析的字段集绑定回文档之前对其进行校验。

一致性

行为	引用	状态
交互式表单/字段字典模型	ISO 32000-2 §12.7	已对齐（释义）
XFDF 数据交换格式	ISO 19444-1:2019	已对齐

本表记录了 NextPDF Pro 所基于构建的规范。它不是一份正式认证声明。

行为契约

• FormDataExtractor 从已解析的终端字段字典中读取名/值对，并返回一个 XfdfData 对象或一个普通的 name → value 数组。
• XfdfParser 将一份 XFDF 文档解析为结构化数据；XfdfWriter 将字段值序列化为 XFDF，并可选地附带一个指回源 PDF 的引用。
• XfaParser 定位 XFA 包，拼接 XML 片段，并将 template 和 datasets 包解析为结构化的字段数据。它会拒绝大于其扫描上限的 PDF 输入，而不是无界地读取数据。
• XFA 支持是面向数据的：解析器提取并结构化 template 和 datasets 包。它不执行 XFA 表单计算脚本、不渲染动态 XFA 布局，也不对每一种 XFA 包类型进行往返。
• 所有 XML 解析都禁用外部实体解析（XXE 安全）。

Enterprise 边界说明

Enterprise 不改变 Form 的行为。Enterprise 增加了更高层级的合规与归档功能，单独编写文档；它们对于 AcroForm 往返、XFDF 读取/写入或 XFA 数据提取并非必需。

Core 回退/替代方案

NextPDF Core 的开源表单读取器读取表单字段。XFDF 读取/写入、XFA 数据提取和字段绑定是 Pro 的新增内容。参见 /modules/form/。

发布边界

本页仅描述外部可观察的行为以及受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀均不在范围之内。

另请参阅

• Interop —— 面向外部系统的带版本表单数据 DTO。
• Core Form module —— 开源表单读取器。
• Form —— 深度参考 —— Pro 表单类的方法级参考。