Документация HotPDF
Главная Содержание Обзор

AcroForm Support

Обзор

Начиная с HotPDF v2.5.0 библиотека может создавать интерактивные формы (AcroForm) по PDF 1.7 ISO 32000-1, раздел 12.7. Каждое поле формы создается как аннотация Widget, объединенная со словарем поля, и автоматически регистрируется в документе, поэтому глобальная запись /AcroForm добавляется в Catalog при финализации документа в EndDoc

Поддерживаемые типы полей

  • Text fields (/FT /Tx) via THPDFPage.AddTextField. Supports single-line, multi-line, password, comb, file-select, rich-text, scroll and spell-check options through THPDFFormFieldFlags.
  • Check boxes (/FT /Btn, no Pushbutton/Radio bits) via THPDFPage.AddCheckBox with a configurable export value name and initial checked state.
  • Переключатели (/FT /Btn /Ff Radio) через THPDFPage.AddRadioButton. Несколько вызовов с одним именем группы объединяются под общим родительским полем с массивом /Kids, как требует 12.7.4.2
  • Combo boxes (/FT /Ch /Ff Combo) via THPDFPage.AddComboBox. Pass an open array of options.
  • List boxes (/FT /Ch) via THPDFPage.AddListBox. ffMultiSelect enables multi-select.
  • Кнопки (/FT /Btn /Ff Pushbutton) создаются через THPDFPage.AddPushButton с необязательной подписью (/MK /CA). Начиная с HotPDF v2.31.0 THPDFPage.AddPushButtonWithAction присоединяет к widget словарь PDF action, поэтому щелчок по кнопке выполняет /SubmitForm (отправка значений полей на 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 (открытие URL в системном браузере, PDF 1.1 12.6.4.7)
  • Поля-заполнители подписи (/FT /Sig) создаются через THPDFPage.AddSignatureField начиная с HotPDF v2.12.0. Словарь AcroForm автоматически получает /SigFlags 3 (SignaturesExist + AppendOnly), если присутствует хотя бы одно поле подписи. Поле остается неподписанным, чтобы внешние инструменты (Adobe Acrobat, Foxit, специализированные библиотеки подписи CMS / PKCS#7) могли добавить реальную криптографическую подпись после сохранения файла
  • Сценарий подписи на месте через THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex доступен с HotPDF v2.23.0. Первый вызов резервирует словарь подписи /V с заполнителями /ByteRange и /Contents. После сохранения документа принимающее приложение вызывает PreparePDFForSigning, чтобы исправить /ByteRange и узнать, какие диапазоны файла нужно хешировать. После внешнего создания отсоединенной подписи CMS / PKCS#7 (Windows CryptoAPI, OpenSSL, специализированные библиотеки подписи) оно вызывает InsertSignatureHex, чтобы поместить шестнадцатеричное представление подписи в заполнитель, не изменяя другие байты файла

Loaded form-field inspection and updates

Начиная с HotPDF v2.121.9, applications могут загрузить существующий AcroForm PDF через THotPDF.LoadFromFile, перечислить его fields, прочитать их names, types и values, изменить field values, переключить read-only flag и сохранить loaded object graph через THotPDF.SaveLoadedDocument. Этот путь предназначен для persistent edits уже загруженного документа; не вызывайте BeginDoc / EndDoc только ради сохранения изменений loaded field values

Field helpers включают GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue и SetFormFieldReadOnly. Поиск поля принимает zero-based field index или fully qualified field name. Возвращаемые значения THPDFLoadedFormFieldType: 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');

Дополнительные действия полей

AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction и AttachFieldCalculateAction присоединяют JavaScript к словарю поля /AA для PDF-триггеров /K, /F, /V и /C. Используйте их после создания или загрузки поля, когда фильтрация, формат, проверка или вычисления должны принадлежать полю.

Appearance generation

По умолчанию создаваемый словарь /AcroForm задает /NeedAppearances true и передает отрисовку appearance streams используемому просмотровщику (Adobe Reader, Foxit, Chrome, браузеры, Apple Preview). Установите THotPDF.AutoFormAppearances в true до добавления полей, и HotPDF заранее создаст /AP /N Form XObjects (PDF 1.7 8.10) для каждого текстового поля, кнопки, поля выбора (combo / list), а также состояний Yes / Off каждого checkbox / radio kid. Затем словарь AcroForm содержит /NeedAppearances false и запись ресурсов по умолчанию /DR со ссылками на стандартные 14 базовых шрифтов (Helv Helvetica, ZaDb ZapfDingbats), поэтому средства вывода, игнорирующие /NeedAppearances, все равно корректно рисуют содержимое полей. Доступно с HotPDF v2.28.0

Field flag reference (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — common Table 227 flags applicable to every field type.
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — Tx-specific (Table 228).
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — Ch-specific (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

  • Генератор AutoFormAppearances сейчас компонует только ASCII / WinAnsi-encodable values; для полей, где /V содержит multi-byte (UTF-8) text, сохраненный /AP рендерит пустой прямоугольник, пока host viewer не пересоздаст appearance
  • Подсостояния Down (/D) и rollover (/R) не создаются; создается только normal (/N) state
  • Field name uniqueness is the caller's responsibility; HotPDF does not enforce it.

См. также