Prise en charge AcroForm

Vue d’ensemble

Depuis HotPDF v2.5.0, la bibliothèque peut émettre des formulaires interactifs (AcroForm) conformément à la section 12.7 de PDF 1.7 ISO 32000-1. Chaque champ de formulaire est créé sous forme d’annotation Widget fusionnée avec le dictionnaire du champ et est enregistré automatiquement avec le document, de sorte que au document afin que l’entrée globale /AcroForm soit ajoutée au Catalogue lors de la finalisation du document dans EndDoc.

Types de champs pris en charge

Champs de texte (/FT /Tx) via THPDFPage.AddTextField. Prend en charge les options ligne unique, multi-ligne, mot de passe, comb, sélection de fichier, texte enrichi, défilement et vérification orthographique via THPDFFormFieldFlags
Cases à cocher (/FT /Btn, sans bits Pushbutton/Radio) via THPDFPage.AddCheckBox avec un nom de valeur d’export configurable et un état initial coché
Boutons radio (/FT /Btn /Ff Radio) via THPDFPage.AddRadioButton. Plusieurs appels avec le même nom de groupe sont fusionnés sous un champ parent partagé avec un tableau /Kids, exactement comme l’exige 12.7.4.2
Zones de liste déroulante (/FT /Ch /Ff Combo) via THPDFPage.AddComboBox. Passez un tableau ouvert d’options
Zones de liste (/FT /Ch) via THPDFPage.AddListBox. ffMultiSelect active la sélection multiple
Boutons poussoirs (/FT /Btn /Ff Pushbutton) via THPDFPage.AddPushButton avec légende facultative (/MK /CA). Depuis HotPDF v2.31.0, THPDFPage.AddPushButtonWithAction attache un dictionnaire d’action PDF au widget afin qu’un clic sur le bouton exécute /SubmitForm (envoie les valeurs des champs vers une URL, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (exécute un extrait JS, PDF 1.3 12.6.4.16) ou /URI (ouvre une URL dans le navigateur système, PDF 1.1 12.6.4.7)
Champs d’espace réservé pour signature (/FT /Sig) via THPDFPage.AddSignatureField depuis HotPDF v2.12.0. Le dictionnaire AcroForm gagne automatiquement /SigFlags 3 (SignaturesExist + AppendOnly) lorsqu’au moins un champ de signature est présent. Le champ est laissé non signé afin que des outils externes (Adobe Acrobat, Foxit, bibliothèques de signature CMS / PKCS#7 dédiées) puissent joindre la signature cryptographique réelle après l’enregistrement du fichier
Flux de signature en place via THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex depuis HotPDF v2.23.0. Le premier appel réserve un dictionnaire de signature /V avec des espaces réservés /ByteRange et /Contents. Après l’enregistrement du document, l’application hôte appelle PreparePDFForSigning pour patcher /ByteRange et connaître les plages du fichier à hacher. Après production externe d’une signature détachée CMS / PKCS#7 (CryptoAPI Windows, OpenSSL, bibliothèques de signature dédiées), elle appelle InsertSignatureHex pour déposer la signature hexadécimale dans l’espace réservé sans toucher au moindre autre octet du fichier.

Inspection et mise à jour des champs de formulaire chargés

Depuis HotPDF v2.292.12, les helpers THPDFPage.CreateTextField, CreateCheckBox, CreateRadioButton, CreateComboBox et CreateListBox créent les mêmes widgets AcroForm que les méthodes Add... existantes et renvoient un wrapper léger THPDFAcroFormField pour une configuration immédiate

Depuis HotPDF v2.121.9, les applications peuvent charger un PDF AcroForm existant avec THotPDF.LoadFromFile, énumérer ses champs, lire leurs noms, types et valeurs, modifier les valeurs des champs, basculer l’indicateur read-only et enregistrer le graphe d’objets chargé avec THotPDF.SaveLoadedDocument Ce chemin est prévu pour des modifications persistantes sur un document déjà chargé; n’appelez pas BeginDoc / EndDoc simplement pour sauvegarder des changements de valeurs de champ

Depuis HotPDF v2.298.0, les API de création de champs et les API de création de champs de documents chargés rejettent les noms de champs racine dupliqués avec une exception de diagnostic avant l’enregistrement de tout widget. Les appels répétés à AddRadioButton avec le même nom de groupe restent valides parce qu’ils partagent un champ parent et ajoutent des widgets enfants supplémentaires sous son tableau /Kids

Le wrapper expose des setters chaînables pour les infobulles /TU, les flags de champs courants (SetReadOnly, SetRequired, SetNoExport), les chaînes d’apparence par défaut /DA, les actions additionnelles au niveau champ telles que /AA /K, /AA /F, /AA /V, /AA /C, et les actions souris ou focus de widgets via THPDFActionBuilder

Exemple Pascal du wrapper à la création

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;

Inspection et mise à jour des champs de formulaire chargés

Depuis HotPDF v2.121.9, les applications peuvent charger un PDF AcroForm existant avec THotPDF.LoadFromFile, énumérer ses champs, lire leurs noms, types et valeurs, changer les valeurs des champs, basculer le flag lecture seule, et enregistrer le graphe d’objets chargé avec THotPDF.SaveLoadedDocument Ce chemin est destiné aux éditions persistées d’un document déjà chargé ; n’appelez pas BeginDoc / EndDoc seulement pour enregistrer des changements de valeurs de champs chargés.

Les helpers de champs sont GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue et SetFormFieldReadOnly. La recherche de champ accepte un index de champ en base zéro ou le nom de champ complet. Les valeurs THPDFLoadedFormFieldType renvoyées sont lfftText, lfftButton, lfftChoice, lfftSignature ou lfftUnknown.

Exemple Pascal sur champs chargés

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

Actions supplémentaires de champ

Les wrappers AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction et AttachFieldCalculateAction attachent du JavaScript au dictionnaire /AA d’un champ pour les déclencheurs PDF /K, /F, /V et /C. Utilisez SetFormFieldAdditionalAction ou ses wrappers nommés THPDFActionBuilder lorsque le même déclencheur doit exécuter une chaîne d’actions réutilisable telle que JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData ou une action /Next chaînée. Les déclencheurs souris et focus au niveau widget peuvent aussi être installés par nom de champ via SetFormFieldAnnotationAction et les helpers nommés souris / focus, tandis que les helpers d’effacement correspondants retirent un déclencheur sans perturber le reste du dictionnaire /AA

Génération des apparences

Par défaut, le dictionnaire /AcroForm émis définit /NeedAppearances true et délègue le rendu des flux d’apparence au lecteur consommateur (Adobe Reader, Foxit, Chrome, navigateurs, Apple Preview). Définissez THotPDF.AutoFormAppearances à true avant d’ajouter des champs et HotPDF pré-construira des Form XObjects /AP /N (PDF 1.7 8.10) pour chaque champ texte, bouton poussoir, liste déroulante (combo / liste) et pour les états Yes / Off de chaque enfant checkbox / radio. Le dictionnaire AcroForm porte alors /NeedAppearances false et une entrée de ressources par défaut /DR référençant les 14 polices de base standard (Helv Helvetica, ZaDb ZapfDingbats), de sorte que les renderers qui ignorent /NeedAppearances dessinent quand même correctement le contenu du champ. Disponible depuis HotPDF v2.28.0.

Référence des indicateurs de champ (THPDFFormFieldFlags)

ffReadOnly, ffRequired, ffNoExport — indicateurs communs du Table 227 applicables à tous les types de champ
ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — spécifiques à Tx (Table 228)
ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — spécifiques à Ch (Table 230)

Exemple 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;

Limitations

Le générateur AutoFormAppearances ne compose actuellement que des valeurs ASCII / WinAnsi-encodables; pour les champs dont /V contient du texte multioctet (UTF-8), le /AP stocké affiche un rectangle vide jusqu’à ce que le lecteur hôte régénère l’apparence
Les sous-états Down (/D) et rollover (/R) ne sont pas générés; seul l’état normal (/N) est produit
L’unicité des noms de champ relève de l’appelant; HotPDF ne l’impose pas

Voir aussi