在 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 所描述的挑戰封套。