在 NextPDF Connect 中填写 PDF 表单（Pro）

概览

在 NextPDF Connect 中，通过 XFDF（XML Forms Data Format）填写交互式 PDF 表单字段。用于签署与表单的工具是 fill_form。Pro 工具提供程序会注册 new FillFormTool()，其协议名称为 fill_form。fill_form 是 Pro 层级工具。 启动时，服务器会通过 class_exists() 探测 Pro 软件包，只有在软件包存在时才注册此工具。如果只安装 Core，fill_form 不会出现在注册表中。

安装

composer require nextpdf/server
composer require nextpdf/pro

绑定一种传输方式。通过 diagnostic.capabilities 确认该工具存在（参阅 environment-diagnostics）。请勿假设工具集是固定的。

概念概述

XFDF 使用 <field> 元素将字段名称映射到值。每个名称都必须对应目标文件中已定义的 AcroForm 字段。交互式表单字段字典保存每个字段（ISO 32000-2 §12.7），所提供的值会成为该字段的值（ISO 32000-2 §12.7）。无法对应任何字段的名称会被跳过，而不是被视为错误。此工具会返回已填写和已跳过的字段数量。

API 接口

工具	层级	角色	风险层级
`create_pdf`	Core	开启会话	安全
`fill_form`	Pro	将 XFDF 值应用到 AcroForm 字段	谨慎
`output_pdf`	Core	渲染并返回 PDF	需要批准/审查（base64）

工具名称就是注册表中的协议名称。工具目录是权威目录。可用工具集取决于已安装的层级。Pro 工具仅在已安装 Pro 软件包时出现。

代码示例 — 快速开始

create_pdf（或加载一份已包含表单字段的模板）。
fill_form，通过 xfdf_data 将字段名称映射到值。
output_pdf → base64。

结果会返回 fields_filled、fields_skipped，以及匹配字段的名称。

代码示例 — 生产环境

使用一份你可以控制 AcroForm 字段名称的模板。提交前，先用 XFDF schema 验证该 XFDF。检查 fields_skipped 与返回的名称列表，以便发现名称不匹配（名称区分大小写）。对于批量填写，请确保 XFDF 保持在大小上限以内，必要时分批处理数据。

边界情况与陷阱

XFDF 格式错误。 解析错误会指出有问题的位置。请转义 XML 实体，并包含 xmlns。
名称不匹配。 不匹配的字段会被静默跳过，且 fields_skipped 会递增。名称区分大小写。
没有表单字段。 不含 AcroForm 的文件会产生零个已填写字段。
XFDF 过大。 服务器会拒绝超过大小上限的数据。请分批处理，或修剪空白字符。
Pro 不存在。 如果只有 Core，fill_form 不会被注册，调用它会返回未知工具错误。请先通过 diagnostic.capabilities 探测。

性能

与渲染相比，填写速度很快。输出大小从数 KB 到数十 KB 不等，取决于字段数量与字体嵌入情况。其配置文件为 structural。

安全性注意事项

字段值属于文件内容。如果你随后会通过不可信通道返回该 PDF，请勿在表单字段中放置机密数据。base64 路径不会产生文件系统副作用。文件输出受到管控。

合规性

陈述	规格	条款	reference_id
表单字段保存在交互式表单字段字典中。	ISO 32000-2	§12.7
所提供的数据会成为该字段的值。	ISO 32000-2	§12.7

商业背景

fill_form 是 Pro 层级工具。服务器只有在启动时解析到 Pro 软件包（即通过 class_exists() 探测）时，才会注册它。Core 部署不会暴露它。

传输可用性

传输	可用	备注
MCP（stdio）	是（Pro）	仅在已安装 Pro 时存在。
REST	是（Pro）	相同。
gRPC	是（Pro）	相同。

HITL 风险层级

fill_form 属于「谨慎」，因为它是一种可逆的内容更改。output_pdf 属于「需要批准」，在 base64 模式下降级为「审查」（HITL 风险层级）。

确认门槛 JSON 封套

Base64 输出：

{ "allowed": true }

文件输出会返回 output-approval 中描述的挑战封套。