เอกสาร HotPDF
หน้าแรก สารบัญ ภาพรวม

AcroForm Support

ภาพรวม

ตั้งแต่ HotPDF v2.5.0 library สามารถ emit interactive forms (AcroForm) ตาม PDF 1.7 ISO 32000-1 section 12.7 แต่ละ form field ถูกสร้างเป็น Widget annotation ที่ merge กับ field dictionary และ register กับ document อัตโนมัติ เพื่อให้ global /AcroForm entry ถูกเพิ่มใน Catalog เมื่อ finalize document ใน EndDoc

field types ที่รองรับ

  • text fields (/FT /Tx) ผ่าน THPDFPage.AddTextField รองรับ single-line, multi-line, password, comb, file-select, rich-text, scroll และ spell-check options ผ่าน THPDFFormFieldFlags
  • check boxes (/FT /Btn โดยไม่มี Pushbutton/Radio bits) ผ่าน THPDFPage.AddCheckBox พร้อม export value name และ initial checked state ที่กำหนดได้
  • radio buttons (/FT /Btn /Ff Radio) ผ่าน THPDFPage.AddRadioButton การเรียกหลายครั้งด้วย group name เดียวกันจะ merge ใต้ shared parent field ที่มี /Kids array ตรงตามที่ 12.7.4.2 กำหนด
  • combo boxes (/FT /Ch /Ff Combo) ผ่าน THPDFPage.AddComboBox โดยส่ง open array ของ options
  • list boxes (/FT /Ch) ผ่าน THPDFPage.AddListBox และ ffMultiSelect เปิด multi-select
  • push buttons (/FT /Btn /Ff Pushbutton) ผ่าน THPDFPage.AddPushButton พร้อม optional caption (/MK /CA) ตั้งแต่ HotPDF v2.31.0 THPDFPage.AddPushButtonWithAction attach PDF action dictionary เข้ากับ widget ได้ ทำให้เมื่อ click button สามารถรัน /SubmitForm (post field values ไป 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 ใน system browser, PDF 1.1 12.6.4.7)
  • signature placeholder fields (/FT /Sig) ผ่าน THPDFPage.AddSignatureField ตั้งแต่ HotPDF v2.12.0 AcroForm dictionary จะได้ /SigFlags 3 (SignaturesExist + AppendOnly) อัตโนมัติเมื่อมี signature field อย่างน้อยหนึ่งรายการ field จะถูกปล่อย unsigned เพื่อให้ external tools เช่น Adobe Acrobat, Foxit, หรือ dedicated CMS / PKCS#7 signing libraries attach cryptographic signature จริงหลังจาก save file แล้ว
  • in-place signing workflow ผ่าน THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex ตั้งแต่ HotPDF v2.23.0 call แรก reserve /V signature dictionary ที่มี /ByteRange และ /Contents placeholders หลังจาก save document แล้ว host application เรียก PreparePDFForSigning เพื่อ patch /ByteRange และทราบช่วง file ที่ต้อง hash หลังจากสร้าง CMS / PKCS#7 detached signature ภายนอก เช่น Windows CryptoAPI, OpenSSL, หรือ dedicated signing libraries แล้ว ให้เรียก InsertSignatureHex เพื่อใส่ signature hex ลง placeholder โดยไม่รบกวน byte อื่นใน file

การตรวจสอบและอัปเดต loaded form fields

ตั้งแต่ HotPDF v2.121.9 applications สามารถ load AcroForm PDF ที่มีอยู่ด้วย THotPDF.LoadFromFile, enumerate fields, อ่าน names, types และ values, เปลี่ยน field values, toggle read-only flag, และ save loaded object graph ด้วย THotPDF.SaveLoadedDocument path นี้มีไว้สำหรับ persisted edits ต่อ document ที่โหลดแล้ว อย่าเรียก BeginDoc / EndDoc เพียงเพื่อ save loaded field-value changes

field helpers คือ GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue, และ SetFormFieldReadOnly field lookup รับได้ทั้ง zero-based field index หรือ fully qualified field name ค่า THPDFLoadedFormFieldType ที่ return คือ lfftText, lfftButton, lfftChoice, lfftSignature, หรือ lfftUnknown

Loaded-field Pascal example

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');

Field additional actions

wrappers AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction, และ AttachFieldCalculateAction attach JavaScript เข้ากับ /AA dictionary ของ field สำหรับ PDF triggers /K, /F, /V, และ /C ใช้หลังจากสร้างหรือโหลด field เมื่อ keystroke filtering, display formatting, validation, หรือ calculated-field updates ต้องอยู่กับ field แทน button action

Appearance generation

ตามค่าเริ่มต้น /AcroForm dictionary ที่ emit จะตั้ง /NeedAppearances true และมอบ appearance-stream rendering ให้ consuming viewer เช่น Adobe Reader, Foxit, Chrome, browsers, Apple Preview ตั้ง THotPDF.AutoFormAppearances เป็น true ก่อนเพิ่ม fields แล้ว HotPDF จะ pre-build /AP /N Form XObjects (PDF 1.7 8.10) สำหรับทุก text field, push button, choice (combo / list) และ Yes / Off states ของ checkbox / radio kid ทุกตัว จากนั้น AcroForm dictionary จะมี /NeedAppearances false และ /DR default resources entry ที่อ้างถึง standard 14 base fonts (Helv Helvetica, ZaDb ZapfDingbats) เพื่อให้ renderers ที่ ignore /NeedAppearances ยังวาด field content ได้ถูกต้อง มีตั้งแต่ HotPDF v2.28.0

อ้างอิง field flags (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — common Table 227 flags ที่ใช้ได้กับทุก field type
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — เฉพาะ Tx (Table 228)
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — เฉพาะ Ch (Table 230)

Pascal example

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;

Limitations

  • generator AutoFormAppearances ปัจจุบันวาง layout เฉพาะ values ที่ encode ได้เป็น ASCII / WinAnsi เท่านั้น สำหรับ fields ที่ /V มี multi-byte (UTF-8) text ค่า /AP ที่ stored จะ render เป็น empty rectangle จนกว่า host viewer จะ regenerate appearance
  • sub-states Down (/D) และ rollover (/R) ไม่ถูก generate มีเพียง normal state (/N) เท่านั้น
  • ความ unique ของ field name เป็นความรับผิดชอบของ caller HotPDF ไม่ enforce ให้

See Also