Form：AcroForm 交互式表单字段与扁平化
Form 模块用于创建 PDF 交互式表单。它可以创建文本、复选框、单选按钮、选择（列表/下拉）、按钮与签名字段，将这些字段组织成 parent/child 层级，并写入为带有外观流的 PDF 对象。它也可以将表单扁平化为静态页面内容。
composer require nextpdf/core:^3概念总览
标题为“概念总览”的章节PDF 交互式表单即 AcroForm：它是文档级的字段层级，终端字段会与页面上的部件注释配对。ISO 32000-2 §12.7 定义了这种表单及其字段字典，包括 AcroForm 根节点与字段层级。本模块就是引擎为其提供的编码器。
FormFieldManager 是主要接口。它提供 textField()、checkBox()、radioButton()、button() 与 signatureField() 构建器，跟踪这些字段，并通过 writeFields() 将其序列化。它会依 §8.10 要求，为每个部件发出一份 Form XObject 外观流（/Subtype /Form、/BBox）。FormField 是字段值对象。FormFieldDictionaryBuilder 会将字段转换为对应的 PDF 字典，并套用类型专属的条目与标志位（文本、复选框、选择、按钮）。管理器与 FormField 为 @since 1.0.0。字典构建器为 @since 1.1.0。
FormFieldHierarchy 用于建立 parent/child 字段树模型：addChild()、getRootFieldNames()、getChildren()、getParent()，以及 walkDepthFirst() 访问器。完整限定的字段名称，就是沿着该层级形成的点分路径，这正是 §12.7 为嵌套字段指定的模型。
FormFlattener 会将表单渲染为静态页面内容——flatten() 会返回 FlattenResult——让已填妥的表单可以冻结并用于归档。FieldMDP 与 FieldMdpAction 会建立字段锁定转换的模型。已签署的文档可以锁定一组具名字段，防止其被进一步修改。FieldMdpAction 会枚举锁定范围。其 requiresFieldList() 会指出何时必须提供明确的字段列表。FieldMDP 为 @since 2.0.0。
API 接口
标题为“API 接口”的章节| 类 | 主要成员 | 角色 |
|---|---|---|
FormFieldManager | textField()、checkBox()、radioButton()、button()、signatureField()、addChildField()、getHierarchy()、writeFields() | 字段构建器＋序列化器（@since 1.0.0） |
FormField | 字段值对象 | 一个 AcroForm 字段（@since 1.0.0） |
FormFieldDictionaryBuilder | buildFieldDictionary()、applyTextFieldOptions()、applyCheckBoxOptions()、applyChoiceFieldOptions()、applyButtonOptions() | 字段转字典构建器（@since 1.1.0） |
FormFieldHierarchy | addChild()、getRootFieldNames()、getChildren()、getParent()、walkDepthFirst() | Parent/child 字段树（@since 2.0.0） |
FormFlattener | flatten(array $fields, array $pages): FlattenResult | 将表单扁平化为静态内容（@since 1.0.0） |
FieldMDP | toTransformParams() | 字段锁定（FieldMDP）转换（@since 2.0.0） |
FieldMdpAction（枚举） | requiresFieldList() | 字段锁定范围（@since 2.0.0） |
执行 composer docs:generate-api-php -- --module=Form 以获取完整的 PHPDoc 表格。
代码示例——快速上手
标题为“代码示例——快速上手”的章节来源：examples/30-form-fields.php。
<?php
declare(strict_types=1);
require_once __DIR__ . '/../vendor/autoload.php';
use NextPDF\Form\FormFieldManager;
$form = new FormFieldManager();
$form->textField(name: 'applicant_name', x: 50, y: 700, w: 200, h: 18);$form->checkBox(name: 'agree_terms', x: 50, y: 660, size: 12);$form->radioButton(name: 'plan', x: 50, y: 620, size: 12 /* + option set */);
// The Writer invokes $form->writeFields(...) during document serialization.代码示例——正式环境
标题为“代码示例——正式环境”的章节创建一组用于已签署文档的字段，并使用 FieldMDP 锁定已签署的字段。
<?php
declare(strict_types=1);
require_once __DIR__ . '/../vendor/autoload.php';
use NextPDF\Form\FieldMDP;use NextPDF\Form\FieldMdpAction;use NextPDF\Form\FormFieldManager;
$form = new FormFieldManager();$form->textField(name: 'contract_value', x: 50, y: 700, w: 160, h: 18);$form->signatureField(name: 'approver_sig', x: 50, y: 600, w: 200, h: 60);
// Lock only the named fields after signing.$lock = new FieldMDP( action: FieldMdpAction::Include, fields: ['contract_value'],);
$transformParams = $lock->toTransformParams();// $transformParams is attached to the signature's transform method by the signing layer.边界情况与陷阱
标题为“边界情况与陷阱”的章节- 字段名称是穿越
FormFieldHierarchy的完整限定点分路径。在查看器中，两个具有相同完整限定名称的终端字段就是同一个逻辑字段——确保唯一性是调用方的责任。 FieldMdpAction::requiresFieldList()会告诉你何时必须提供字段列表。如果Include/Exclude动作未附带所需列表，就会形成格式错误的锁定；请检查该标志。FormFlattener::flatten()按设计会破坏交互性——其结果是静态内容。如果日后仍需要交互式来源，请将其保留。- 外观流会按每个部件发出。没有外观的字段在不同查看器之间可能渲染不一致；请让管理器生成外观，而不要略过它。
signatureField()只会创建字段占位符。生成实际签名是 Security/签署层的职责，而非本模块的职责。
字段创建与序列化相对于字段数量为 O(n)，另外每个部件还会产生一份 Form XObject 外观流。扁平化成本随渲染内容而非字段数量增长。默认参考工作负载位于 1500 ms 挂钟时间/64 MB 峰值预算之内。可重现性配置文件为 structural：对象编号与尾部 /ID 会在不同次执行之间有所不同。两份具有相同表单的文件在结构上相等，但并非逐字节完全相同。
安全性说明
标题为“安全性说明”的章节表单字段值是用户输入。本模块会为 PDF 序列化转义字符串值（PdfStringEscaper），使字段值无法跳出其 PDF 字符串并注入结构。当表单经过加密时，字段内容会被文档的 AES-256 加密覆盖。FieldMDP 是一项安全控制：它会锁定具名字段，防止签署后的修改。如果字段锁定与已签署的字段集不相符，就会削弱这项控制——请审慎设定锁定范围。请将任何从已填妥表单中提取的值视为不可信输入。请参阅 /modules/core/security/ 中的引擎安全模型。
符合性
标题为“符合性”的章节本模块发出的表单结构遵循 ISO 32000-2 §12.7 中的交互式表单模型——AcroForm 根节点与字段字典，以及文档字段层级。依 §8.10，各部件的外观会以 Form XObject 形式发出，并以内嵌方式记录在 src/Form/ 中。这些是由 tests/Unit/Form/ 验证的实现事实，并非端到端 PDF 2.0 符合性声明。完整文档的符合性由 /modules/core/conformance/ 中的 oracle 与黄金测试套件验证。
另请参阅
标题为“另请参阅”的章节- Navigation 模块——与字段配对的部件注释。
- Security 模块——签署与 FieldMDP 信任模型。
- Accessibility 模块——用于 PDF/UA 的表单字段标记。
- 符合性总览