HotPDF 說明
首頁 目錄 總覽

AcroForm 支援

總覽

自 HotPDF v2.5.0 起，程式庫即可依 PDF 1.7 ISO 32000-1 第 12.7 節輸出互動式表單（AcroForm）。每個表單欄位都會建立成與 field dictionary 合併的 widget 標註，並自動註冊到檔案，因此在 EndDoc 收尾檔案時，整體 /AcroForm 項目會加入 Catalog/AcroForm 項目會在 EndDoc 收尾文件時加入 Catalog

支援的欄位類型

  • 透過 THPDFPage.AddTextField 建立文字欄位（/FT /Tx），並透過 THPDFFormFieldFlags 支援單行、多行、密碼、comb、檔案選擇、rich-text、捲動與拼字檢查等選項
  • 透過 THPDFPage.AddCheckBox 建立核取方塊（/FT /Btn，不含 Pushbutton/Radio 位元），匯出值名稱與初始勾選狀態都可設定
  • Radio buttons（/FT /Btn /Ff Radio）透過 THPDFPage.AddRadioButton 建立。多次呼叫若使用相同 group name，會合併到共用 parent field 下並具有 /Kids array，完全符合 12.7.4.2 要求/FT /Btn /Ff Radio）,透過 THPDFPage.AddRadioButton 使用。以相同群組名稱重複呼叫會合併到共用的父欄位,並以 /Kids
  • 透過 THPDFPage.AddComboBox 建立下拉組合框（/FT /Ch /Ff Combo），以開放陣列傳入選項
  • 透過 THPDFPage.AddListBox 建立清單框（/FT /Ch），ffMultiSelect 可啟用多選
  • Push buttons（/FT /Btn /Ff Pushbutton）透過 THPDFPage.AddPushButton 建立，並可選擇 caption（/MK /CA）。自 HotPDF v2.31.0 起，THPDFPage.AddPushButtonWithAction 會將 PDF action dictionary 附加到 widget，因此按下按鈕時可執行 /SubmitForm（將欄位值 post 到 URL，PDF 1.2 12.7.5.2）、/ResetForm（PDF 1.2 12.7.5.3）、/JavaScript（執行 JS snippet，PDF 1.3 12.6.4.16）或 /URI（在系統瀏覽器開啟 URL，PDF 1.1 12.6.4.7）/FT /Btn /Ff Pushbutton）,可透過 THPDFPage.AddPushButton 附加選用的標題（/MK /CA）。自 HotPDF v2.31.0 起,THPDFPage.AddPushButtonWithAction 會把 PDF 動作字典附加到 widget,點擊按鈕即可執行 /SubmitForm（把欄位值 POST 到 URL,PDF 1.2 12.7.5.2）、/ResetForm（PDF 1.2 12.7.5.3）、/JavaScript（執行 JS 片段,PDF 1.3 12.6.4.16）或 /URI
  • Signature placeholder fields (/FT /Sig）,自 HotPDF v2.12.0 起可透過 THPDFPage.AddSignatureField 使用。AcroForm 字典會自動取得 /SigFlags 3
  • In-place signing workflow via THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex

已載入表單欄位的檢視與更新

自 HotPDF v2.121.9 起，應用程式可使用 THotPDF.LoadFromFile 載入既有 AcroForm PDF、列舉其欄位、讀取名稱、類型與值、變更欄位值、切換唯讀旗標，並透過 THotPDF.SaveLoadedDocument 儲存已載入的物件圖。此路徑用於對已載入檔案做持久化編輯；不要只為了儲存已載入欄位值變更而呼叫 BeginDoc / EndDocTHPDFPage.CreateTextField、CreateCheckBox、CreateRadioButton、CreateComboBox 與 CreateListBox 輔助方法會建立與既有 Add... 方法相同的 AcroForm widget,並回傳輕量的 THPDFAcroFormField

Since HotPDF v2.292.26, THotPDF.SetFormFieldTooltip 會以欄位名稱為透過既有 Add... 方法建立的欄位指定 PDF /TU 使用者提示,對應包裝層級的 THPDFAcroFormField.SetTooltip 工作流程

自 HotPDF v2.298.0 起,建立時期的欄位 API 與已載入文件的欄位建立 API 會在任何 widget 註冊之前,以診斷例外拒絕重複的根欄位名稱。以相同群組名稱重複呼叫 AddRadioButton 仍然有效,因為它們共用一個父欄位,並在其 /Kids 陣列下新增子 widget

包裝層提供鏈式 setter,涵蓋 /TU 提示、常見欄位旗標（SetReadOnly、SetRequired、SetNoExport）、/DA 預設外觀字串、欄位層級的其他動作（如 /AA /K、/AA /F、/AA /V、/AA /C）,以及透過 THPDFActionBuilder 設定的 widget 滑鼠或焦點動作

已載入欄位的 Pascal 範例

HPDF.LoadFromFile('InputForm.pdf');
for I := 0 to HPDF.GetFormFieldCount - 1 do
  Writeln(HPDF.GetFormFieldName(I), ' = ', HPDF.GetFormFieldValue(I));

HPDF.SetFormFieldValue('CustomerName', 'Bob');
HPDF.SetFormFieldValue('Plan', 'Premium');
HPDF.SetFormFieldReadOnly('CustomerName', True);
HPDF.SaveLoadedDocument('UpdatedForm.pdf');

欄位附加動作

AttachFieldKeyStrokeAction、AttachFieldFormatAction、AttachFieldValidateAction 與 AttachFieldCalculateAction 這幾個 wrapper 會把 JavaScript 附加到欄位的 /AA 字典，對應 PDF 的 /K、/F、/V 與 /C 觸發時機。建立或載入欄位之後，若按鍵過濾、顯示格式化、驗證或計算欄位更新必須隨欄位存在（而不是作為按鈕動作），請使用這些 wrapperTHotPDF.LoadFromFile,列舉其欄位,讀取名稱、型別與值,變更欄位值,切換唯讀旗標,再用 THotPDF.SaveLoadedDocument 儲存已載入的物件圖 這條路徑適合對已載入文件做持久化編輯;不要為了儲存已載入的 欄位值變更而呼叫 BeginDoc / EndDoc。

欄位輔助方法包括 GetFormFieldCount、 GetFormFieldName、GetFormFieldType、 GetFormFieldValue、SetFormFieldValue 與 SetFormFieldReadOnly。欄位查詢接受零基 欄位索引或完整限定的欄位名稱。回傳的 THPDFLoadedFormFieldType 值為 lfftText、 lfftButton、lfftChoice、 lfftSignature 或 lfftUnknown。

已載入欄位的 Pascal 範例

HPDF.LoadFromFile('InputForm.pdf');
for I := 0 to HPDF.GetFormFieldCount - 1 do
  Writeln(HPDF.GetFormFieldName(I), ' = ', HPDF.GetFormFieldValue(I));

HPDF.SetFormFieldValue('CustomerName', 'Bob');
HPDF.SetFormFieldValue('Plan', 'Premium');
HPDF.SetFormFieldReadOnly('CustomerName', True);
HPDF.SaveLoadedDocument('UpdatedForm.pdf');

外觀產生

預設輸出的 /AcroForm dictionary 會設定 /NeedAppearances true，並將 appearance-stream rendering 委派給 consuming viewer（Adobe Reader、Foxit、Chrome、瀏覽器、Apple Preview）。加入欄位前將 THotPDF.AutoFormAppearances 設為 true，HotPDF 會為每個 text field、push button、choice（combo / list）以及每個 checkbox / radio kid 的 Yes / Off states 預先建立 /AP /N Form XObjects（PDF 1.7 8.10）。接著 AcroForm dictionary 會帶有 /NeedAppearances false，以及參照 standard 14 base fonts（Helv Helvetica、ZaDb ZapfDingbats）的 /DR default resources entry，因此即使 renderers 忽略 /NeedAppearances，仍能正確繪製欄位內容。自 HotPDF v2.28.0 起提供AttachFieldKeyStrokeAction、AttachFieldFormatAction、AttachFieldValidateAction 與 AttachFieldCalculateAction 會把 JavaScript 附加到欄位的 /AA 字典，分別對應 PDF /K、/F、/V 與 /C 觸發器。同一觸發器需要執行可重用的動作鏈（JavaScript、ResetForm、SubmitForm、URI、Hide、ImportData 或鏈結的 /Next 動作）時，請使用 SetFormFieldAdditionalAction 或其具名的 THPDFActionBuilder 包裝。以欄位名稱安裝 widget 層級的滑鼠與焦點觸發器，則可透過 SetFormFieldAnnotationAction 與具名的滑鼠 / 焦點輔助方法；對應的 clear 輔助方法只移除單一觸發器，不會動到 /AA 字典的其餘內容

外觀產生

預設情況下，輸出的 /AcroForm 字典會設定 /NeedAppearances true，把外觀 stream 的轉譯交給 消費端的檢視器（Adobe Reader、Foxit、Chrome、瀏覽器、Apple Preview）。在加入欄位 之前把 THotPDF.AutoFormAppearances 設為 true, HotPDF 就會為每個文字欄位、按鈕、下拉 / 清單選單，以及每個 checkbox / radio 子項的 Yes / Off 狀態，預先建構 /AP /N Form XObject（PDF 1.7 8.10）。此時 AcroForm 字典 會帶有 /NeedAppearances false 與 /DR 預設 資源項目，參照標準 14 種基礎字型（Helv Helvetica、ZaDb ZapfDingbats），讓忽略 /NeedAppearances 的轉譯器也能正確顯示

欄位旗標對照（THPDFFormFieldFlags）

  • ffReadOnly, ffRequired, ffNoExport — 適用於所有欄位類型的 Table 227 共通旗標
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — Tx 專用（Table 228）
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — Ch 專用（Table 230）

Pascal 範例

HPDF.BeginDoc;
HPDF.AddPage;
HPDF.CurrentPage.AddTextField('Name', '', Rect(50, 100, 250, 120));
HPDF.CurrentPage.AddCheckBox('Agree', 'Yes', Rect(50, 130, 70, 145), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Red',   Rect(50, 160, 70, 175), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Green', Rect(80, 160, 100, 175));
HPDF.CurrentPage.AddRadioButton('Color', 'Blue',  Rect(110, 160, 130, 175));
HPDF.CurrentPage.AddComboBox('Country', 'CN',
                             ['CN', 'US', 'JP'], Rect(50, 190, 250, 210));
HPDF.EndDoc;

限制

  • AutoFormAppearances 產生器目前只能排版 ASCII / WinAnsi 可編碼的值；若欄位的 /V 含多位元組（UTF-8）文字，儲存的 /AP 會轉譯成空矩形，直到檢視端重新產生外觀AutoFormAppearances 產生器目前只排版可編碼為 ASCII / WinAnsi 的值;欄位的 /V 含多位元組（UTF-8）文字時,儲存的 /AP
  • Down (/D）與滑入（/R）子狀態不會產生;只產生一般（/N）
  • 欄位名稱的唯一性由呼叫端自行把關；HotPDF 不強制檢查

請參閱