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

Поддержка AcroForm

Обзор

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

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

  • Текстовые поля (/FT /Tx) через THPDFPage.AddTextField. Поддерживает опции однострочных, многострочных, парольных, comb, file-select, rich-text полей, прокрутки и проверки орфографии через THPDFFormFieldFlags.
  • Чекбоксы (/FT /Btn, без битов Pushbutton/Radio) через THPDFPage.AddCheckBox с настраиваемым именем export-значения и начальным состоянием отмеченности.
  • Радиокнопки (/FT /Btn /Ff Radio) через THPDFPage.AddRadioButton. Множественные вызовы с одним именем группы сливаются под общим родительским полем с массивом /Kids, ровно как требует 12.7.4.2.
  • Комбобоксы (/FT /Ch /Ff Combo) через THPDFPage.AddComboBox. Передавайте открытый массив опций.
  • Списки (/FT /Ch) через THPDFPage.AddListBox. ffMultiSelect включает мультивыбор.
  • Push-кнопки (/FT /Btn /Ff Pushbutton) через THPDFPage.AddPushButton с опциональной подписью (/MK /CA). С HotPDF v2.31.0 THPDFPage.AddPushButtonWithAction присоединяет к widget-у словарь действия PDF, так что клик по кнопке выполняет /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).
  • Поля placeholder-ов подписи (/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 с placeholder-ами /ByteRange и /Contents. После сохранения документа хост-приложение вызывает PreparePDFForSigning, чтобы пропатчить /ByteRange и узнать, какие диапазоны файла хешировать. Получив внешне (Windows CryptoAPI, OpenSSL, специализированные библиотеки подписи) отсоединённую подпись CMS / PKCS#7, оно вызывает InsertSignatureHex, чтобы вписать hex подписи в placeholder, не трогая ни одного другого байта файла.

Wrapper-и полей времени создания

С HotPDF v2.292.12 хелперы THPDFPage.CreateTextField, CreateCheckBox, CreateRadioButton, CreateComboBox, и CreateListBox создают те же AcroForm widget-ы, что существующие методы Add... и возвращают лёгкую обёртку THPDFAcroFormField для немедленной настройки

С HotPDF v2.292.26 THotPDF.SetFormFieldTooltip назначает пользовательскую подсказку PDF /TU по имени поля для полей, созданных существующими методами Add..., совпадая с wrapper-уровнем THPDFAcroFormField.SetTooltip сценария

С HotPDF v2.298.0 API создания полей и API создания полей в загруженном документе отвергают дубликаты корневых имён полей диагностическим исключением до регистрации какого-либо widget-а. Повторные AddRadioButton вызовы с одним именем группы остаются валидными, потому что делят одно родительское поле и добавляют дополнительные дочерние widget-ы в его /Kids array

Обёртка открывает цепочку setter-ов для /TU tooltip-ов, общих флагов полей (SetReadOnly, SetRequired, SetNoExport), /DA строк внешнего вида по умолчанию, дополнительных действий уровня поля, таких как /AA /K, /AA /F, /AA /V, /AA /C, и действий мыши или фокуса widget-а через THPDFActionBuilder

Pascal-пример wrapper-а времени создания

Field := HPDF.CurrentPage.CreateTextField('Email', '', Rect(50, 80, 250, 104));
Action := THPDFActionBuilder.JavaScript('event.rc = event.value.indexOf("@") > 0;');
try
  Field.SetTooltip('Email address');
  Field.SetRequired(True);
  Field.SetReadOnly(False);
  Field.SetAdditionalAction(fatValidate, Action);
finally
  Action.Free;
  Field.Free;
end;

Инспекция и обновление загруженных полей формы

С HotPDF v2.121.9 приложения могут загрузить существующий AcroForm-PDF через THotPDF.LoadFromFile, перечислить его поля, прочитать их имена, типы и значения, менять значения полей, переключать флаг read-only и сохранить загруженный граф объектов через THotPDF.SaveLoadedDocument Этот путь предназначен для сохраняемых правок уже загруженного документа; не вызывайте BeginDoc / EndDoc просто ради сохранения изменений значений полей загруженного документа.

Хелперы полей: GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue, и SetFormFieldReadOnlyПоиск поля принимает либо индекс поля с нумерацией с 0, либо полностью квалифицированное имя поля. Возвращаемое 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');

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

Wrapper-ы AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction, и AttachFieldCalculateAction присоединяют JavaScript к словарю /AA поля для триггеров /K, /F, /V, и /C PDF. Используйте SetFormFieldAdditionalAction или его именованные THPDFActionBuilder wrapper-ы, когда один и тот же триггер должен выполнять переиспользуемую цепочку действий — JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData или цепочечное /Next действие. Widget-уровневые триггеры мыши и фокуса тоже можно ставить по имени поля через SetFormFieldAnnotationAction и именованные хелперы мыши / фокуса, а парные clear-хелперы убирают один триггер, не трогая остальное в /AA словарь

Генерация внешнего вида

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

Справочник флагов полей (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — общие флаги таблицы 227, применимые к каждому типу полей.
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — специфичные для Tx (таблица 228).
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — специфичные для Ch (таблица 230).

Pascal-пример

HPDF.BeginDoc;
HPDF.AddPage;
HPDF.CurrentPage.AddTextField('Name', '', Rect(50, 100, 250, 120));
HPDF.SetFormFieldTooltip('Name', 'Customer name');
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 рисует пустой прямоугольник, пока host-viewer не пересоберёт внешний вид.
  • Подсостояния Down (/D) и rollover (/R) не генерируются; создаётся только нормальное состояние (/N).
  • Имена полей проверяются на дубликаты корневых записей при создании новых AcroForm widget-ов; иерархическое построение частичных имён помимо паттерна radio-родитель / widget остаётся на ответственности вызывающего.

См. также