HotPDF-Dokumentation
Startseite Inhalt Übersicht

AcroForm-Unterstützung

Übersicht

Seit HotPDF v2.5.0 kann die Bibliothek interaktive Formulare (AcroForm) gemäß PDF 1.7 ISO 32000-1 Abschnitt 12.7 erstellen. Jedes Formularfeld wird als Widget-Anmerkung erstellt, die mit dem Feld-Wörterbuch zusammengeführt wird, und automatisch beim Dokument registriert, sodass der globale /AcroForm-Eintrag beim Fertigstellen des Dokuments in EndDoc zum Katalog hinzugefügt wird

Unterstützte Feldtypen

  • Textfelder (/FT /Tx) über THPDFPage.AddTextField. Unterstützt einzeilige, mehrzeilige, Passwort-, Comb-, Dateiauswahl-, Rich-Text-, Scroll- und Rechtschreibprüfungsoptionen durch THPDFFormFieldFlags
  • Kontrollkästchen (/FT /Btn, keine Pushbutton/Radio-Bits) über THPDFPage.AddCheckBox mit konfigurierbarem Exportwertnamen und anfänglichem Aktivierungsstatus
  • Optionstasten (Radiobuttons) (/FT /Btn /Ff Radio) über THPDFPage.AddRadioButton. Mehrere Aufrufe mit demselben Gruppennamen werden unter einem gemeinsamen übergeordneten Feld mit einem /Kids-Array zusammengeführt, genau wie in 12.7.4.2 gefordert
  • Kombinationsfelder (Comboboxen) (/FT /Ch /Ff Combo) über THPDFPage.AddComboBox. Übergeben Sie ein offenes Array von Optionen
  • Listenfelder (/FT /Ch) über THPDFPage.AddListBox. ffMultiSelect ermöglicht die Mehrfachauswahl
  • Druckknöpfe (Buttons) (/FT /Btn /Ff Pushbutton) über THPDFPage.AddPushButton mit optionaler Beschriftung (/MK /CA). Seit HotPDF v2.31.0 verknüpft THPDFPage.AddPushButtonWithAction ein PDF-Aktionswörterbuch mit dem Widget, sodass das Klicken auf die Schaltfläche /SubmitForm (Feldwerte an eine URL senden, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (ein JS-Snippet ausführen, PDF 1.3 12.6.4.16) oder /URI (eine URL im Systembrowser öffnen, PDF 1.1 12.6.4.7) ausführt
  • Signatur-Platzhalterfelder (/FT /Sig) über THPDFPage.AddSignatureField seit HotPDF v2.12.0. Das AcroForm-Wörterbuch erhält automatisch /SigFlags 3 (SignaturesExist + AppendOnly), wenn mindestens ein Signaturfeld vorhanden ist. Das Feld bleibt unsigniert, damit externe Werkzeuge (Adobe Acrobat, Foxit, dedizierte CMS / PKCS#7-Signaturbibliotheken) die tatsächliche kryptografische Signatur nach dem Speichern der Datei anhängen können
  • In-Place-Signaturworkflow über THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex seit HotPDF v2.23.0. Der erste Aufruf reserviert ein /V-Signaturwörterbuch mit /ByteRange- und /Contents-Platzhaltern. Nach dem Speichern des Dokuments ruft die Host-Anwendung PreparePDFForSigning auf, um /ByteRange anzupassen und zu ermitteln, welche Dateibereiche gehasht werden müssen. Nach der externen Erstellung einer detached CMS / PKCS#7-Signatur (Windows CryptoAPI, OpenSSL, dedizierte Signaturbibliotheken) ruft sie InsertSignatureHex auf, um das Signatur-Hex in den Platzhalter einzufügen, ohne andere Bytes in der Datei zu verändern

Wrapper zur Erstellungszeit

Seit HotPDF v2.292.12 erzeugen die Helfer THPDFPage.CreateTextField, CreateCheckBox, CreateRadioButton, CreateComboBox und CreateListBox dieselben AcroForm-Widgets wie die vorhandenen Add...-Methoden und geben einen leichten THPDFAcroFormField-Wrapper für die sofortige Konfiguration zurück

Seit HotPDF v2.292.26 weist THotPDF.SetFormFieldTooltip den PDF-/TU-Benutzerhinweis über den Feldnamen zu, und zwar für Felder, die über die vorhandenen Add...-Methoden erstellt wurden; damit entspricht er dem Wrapper-Workflow THPDFAcroFormField.SetTooltip

Seit HotPDF v2.298.0 weisen die Feld-APIs zur Erstellungszeit und die Felderstellungs-APIs geladener Dokumente doppelte Root-Feldnamen mit einer diagnostischen Ausnahme zurück, bevor ein Widget registriert wird. Wiederholte AddRadioButton-Aufrufe mit demselben Gruppennamen bleiben gültig, weil sie sich ein gemeinsames übergeordnetes Feld teilen und zusätzliche Child-Widgets unter dessen /Kids-Array anlegen

Der Wrapper bietet verkettbare Setter für /TU-Tooltips, gängige Feldflags (SetReadOnly, SetRequired, SetNoExport), /DA-Standarddarstellungs-Strings, zusätzliche Aktionen auf Feldebene wie /AA /K, /AA /F, /AA /V und /AA /C sowie Widget-Maus- und Fokusaktionen über THPDFActionBuilder

Pascal-Beispiel für den Wrapper zur Erstellungszeit

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;

Prüfung und Aktualisierung geladener Formularfelder

Seit HotPDF v2.121.9 können Anwendungen ein vorhandenes AcroForm-PDF mit THotPDF.LoadFromFile laden, dessen Felder auflisten, deren Namen, Typen und Werte lesen, Feldwerte ändern, das Schreibschutz-Flag umschalten und den geladenen Objektgraphen mit THotPDF.SaveLoadedDocument speichern. Dieser Pfad ist für persistente Bearbeitungen an einem bereits geladenen Dokument gedacht; rufen Sie nicht BeginDoc / EndDoc auf, nur um geladene Feldwertänderungen zu speichern

Die Feld-Hilfsmittel sind GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue und SetFormFieldReadOnly. Die Feldsuche akzeptiert entweder einen nullbasierten Feldindex oder den vollqualifizierten Feldnamen. Die zurückgegebenen THPDFLoadedFormFieldType-Werte sind lfftText, lfftButton, lfftChoice, lfftSignature oder lfftUnknown

Pascal-Beispiel für geladene Felder

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

Zusätzliche Aktionen für Felder

Die Wrapper AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction und AttachFieldCalculateAction hängen JavaScript an das /AA-Wörterbuch eines Felds an, und zwar für die PDF-Trigger /K, /F, /V und /C. Verwenden Sie SetFormFieldAdditionalAction oder die benannten THPDFActionBuilder-Wrapper, wenn derselbe Trigger eine wiederverwendbare Aktionskette ausführen muss, etwa JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData oder eine verkettete /Next-Aktion. Maus- und Fokus-Trigger auf Widget-Ebene lassen sich ebenfalls über den Feldnamen mit SetFormFieldAnnotationAction und den benannten Maus-/Fokus-Helfern installieren, während die passenden Clear-Helfer jeweils einen Trigger entfernen, ohne den Rest des /AA-Wörterbuchs anzutasten

Darstellungserstellung (Appearance Generation)

Standardmäßig setzt das ausgegebene /AcroForm-Wörterbuch /NeedAppearances true and delegiert das Rendern des Darstellungsstroms an den verarbeitenden Viewer (Adobe Reader, Foxit, Chrome, Browser, Apple Preview). Setzen Sie THotPDF.AutoFormAppearances vor dem Hinzufügen von Feldern auf true, und HotPDF erstellt /AP /N Form-XObjects (PDF 1.7 8.10) für jedes Textfeld, jeden Druckknopf, jede Auswahl (Combo / Liste) und die Zustände Yes / Off jedes Checkbox-/Radio-Unterelements vor. Das AcroForm-Wörterbuch enthält dann /NeedAppearances false und einen Standardressourcen-Eintrag /DR, der auf die 14 Standard-Basisschriftarten verweist (Helv Helvetica, ZaDb ZapfDingbats), sodass Renderer, die /NeedAppearances ignorieren, den Feldinhalt dennoch korrekt zeichnen. Verfügbar seit HotPDF v2.28.0

Feld-Flag-Referenz (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — gemeinsame Flags aus Tabelle 227, die für jeden Feldtyp gelten
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — Tx-spezifisch (Tabelle 228)
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — Ch-spezifisch (Tabelle 230)

Pascal-Beispiel

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;

Einschränkungen

  • Der Generator AutoFormAppearances legt derzeit nur ASCII- / WinAnsi-codierbare Werte aus; für Felder, deren /V Multibyte-Text (UTF-8) enthält, rendert das gespeicherte /AP ein leeres Rechteck, bis der Host-Viewer die Darstellung neu generiert
  • Down- (/D) und Rollover- (/R) Unterzustände werden nicht generiert; es wird nur der normale Zustand (/N) erzeugt
  • Die Eindeutigkeit des Feldnamens liegt in der Verantwortung des Aufrufers; HotPDF erzwingt diese nicht

Siehe auch