表單

速覽

NextPDF Pro 會讀取並寫入互動式表單資料：AcroForm 欄位值、XFDF 資料檔，以及 XFA（XML Forms Architecture）範本所承載的資料。它以資料繫結、抽取與序列化，補足開源的 Core 表單讀取器。

供應與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權封套啟用。未持有該權利的部署不會載入此能力的類別。比較各版本並取得授權。

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 封包、串接這些 XML 片段，並將 template 與 datasets 封包剖析為結構化的欄位資料。

XFA 支援範圍

NextPDF Pro 中的 XFA 支援是以資料為導向，而非一個完整的 XFA 繪製或指令稿引擎。剖析器會抽取並結構化 template 與 datasets 封包，讓你能讀取欄位定義與值。它不執行 XFA 表單計算指令稿、不繪製動態 XFA 版面，也不會對每一種 XFA 封包型別進行來回轉換。在你針對某一組 XFA 表單依賴它之前，請先以你的特定文件測試剖析器。所有 XML 剖析皆停用外部實體載入（XXE-safe）。

為何如此設計

XFA 支援刻意限縮於資料，而非繪製。ISO 32000-2 在 PDF 2.0 中將表單字典的 XFA 條目標記為已棄用（§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-safe）。

Enterprise 邊界註記

Enterprise 不會改變 Form 的行為。Enterprise 新增更高等級的合規與封存功能，另行記載；它們對於 AcroForm 來回轉換、XFDF 讀寫或 XFA 資料抽取並非必要。

Core 回退/替代方案

NextPDF Core 的開源表單讀取器會讀取表單欄位。XFDF 讀寫、XFA 資料抽取，以及欄位繫結是 Pro 的新增功能。請參閱 /modules/form/。

發佈邊界

本頁僅記載外部可觀察的行為，以及受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及工單前綴皆不在範圍內。

另請參閱

• Interop —— 供外部系統使用的版本化表單資料 DTO。
• Core Form 模組 —— 開源表單讀取器。
• Form —— 深入參考 —— Pro 表單類別的方法層級參考。