Vom ausfüllbaren Formular zum eingefrorenen Nachweis: AcroForm ausfüllen und flachklopfen

Spec: ISO 32000-2, §12.7

Auf einen Blick

Ein PDF-Formular hat zwei Leben. Zuerst ist es ausfüllbar: eine Menge typisierter Felder, in die eine Person tippt, die sie ankreuzt oder aus denen sie auswählt. Dann, wenn die Vereinbarung getroffen ist, wird es zu einem eingefrorenen Nachweis: Die Werte werden in die Seite selbst gedruckt, sodass jeder Reader, auf jedem Gerät, genau das sieht, was vereinbart wurde. NextPDF baut das erste auf und erzeugt das zweite, mit einer bewussten Zusicherung – es wird die Werte unterwegs nicht klammheimlich wegwerfen.

Warum das wichtig ist

Die Lücke zwischen „was ich ausgefüllt habe” und „was Sie sehen” ist die Stelle, an der Formulare schiefgehen.

Ein ausfüllbares Feld ist technisch gesehen ein kleines interaktives Widget, das über die Seite gezeichnet ist. Verschiedene Reader können es unterschiedlich rendern. Manche respektieren einen gespeicherten Wert, manche erzeugen das Aussehen aus einer Schrift neu, die Sie nicht haben, manche lassen einen Leser es erneut bearbeiten. Für einen Entwurf, an dem Mitwirkende weiterarbeiten sollen, ist das der Sinn. Für die signierte Kopie dessen, was vereinbart wurde, ist es eine Belastung: Der Nachweis sollte nicht davon abhängen, welche Anwendung ihn öffnet, und er sollte nachträglich nicht bearbeitbar sein.

Das Flachklopfen schließt die Lücke. Es nimmt den aktuellen Wert jedes Felds und druckt ihn als gewöhnliche, unveränderliche Grafik in die Seite – dieselbe Art von Inhalt wie eine Überschrift oder ein Logo. Danach gibt es kein Feld zu bearbeiten und kein Aussehen neu zu erzeugen. Das Dokument zeigt eine Sache, dieselbe Sache, überall.

Die Kurzfassung

Ein AcroForm ist das interaktive Formular des Dokuments: ein Baum typisierter Felder, deklariert im Katalog (Spec: ISO 32000-2, §12.7).
Jedes Feld wird durch eine Widget-Annotation sichtbar gemacht – das Rechteck auf der Seite, in das Sie klicken oder tippen (Spec: ISO 32000-2, §12.5).
NextPDF liefert typisierte Builder für jedes unterstützte Formularsteuerelement, das keine Signatur ist – Textfeld, Kontrollkästchen, Optionsfeld, Listenfeld und Kombinationsfeld (Auswahl) sowie Druckschaltfläche – plus einen Feldmanager, der sie als korrekte PDF-Objekte schreibt.
Das Flachklopfen rendert den Wert jedes Felds in den Seiteninhalts-Stream und entfernt das nun überflüssige interaktive Formular, sodass ein eingefrorener Nachweis zurückbleibt.
Wenn Sie verlangen, ein Dokument flachzuklopfen, das keine Seiten hat, zerstört NextPDF Ihre Feldwerte nicht klammheimlich. Es bewahrt das Formular, warnt Sie und lässt Sie eine Seite hinzufügen und korrekt flachklopfen.

Wie NextPDF dabei vorgeht

Das mentale Modell sind zwei Schichten. Das Feld ist die Daten: ein Name, ein Typ, ein Wert und eine Menge Flags. Das Widget ist das Bild: ein Rechteck auf einer bestimmten Seite, das einen Reader mit dem Feld interagieren lässt (Spec: ISO 32000-2, §12.5). Ein Feld kann sogar durch mehrere Widgets in Erscheinung treten – genau so funktioniert eine Optionsfeldgruppe, mehrere Auswahlmöglichkeiten auf der Seite, verdrahtet mit einem zugrunde liegenden Wert.

NextPDF gibt jedem Feldtyp seinen eigenen typisierten Builder, sodass Sie nie ein rohes Dictionary von Hand zusammensetzen. Der Typ trägt die PDF-korrekten Details für Sie. Ein Kontrollkästchen, ein Optionsfeld und eine Druckschaltfläche teilen sich im Spec alle denselben zugrunde liegenden Formulartyp und werden durch ihre Flags auseinandergehalten; die Engine setzt diese Flags aus dem Typ, den Sie gewählt haben, statt von Ihnen zu verlangen, sich zu merken, welches Bit „Optionsfeld” bedeutet. Ein Listenfeld und ein Kombinationsfeld sind beide Auswahl-Felder; auch hier wählt der Builder die richtige Kodierung. Sie geben den Feldtyp einmal an, in Worten, und die Bytes folgen.

Das Flachklopfen ist die zweite Hälfte. Der Flachklopfer gruppiert Widget-Annotationen nach ihrer Eigentümerseite, verwendet das Rechteck jedes Widgets für die Platzierung auf dieser Seite und rendert dann jeden Wert als einen kleinen Lauf von Inhalts-Stream-Operatoren – eine Farbe setzen, eine Textposition setzen, die Glyphen zeichnen –, angehängt an den bestehenden Inhalt dieser Seite (Spec: ISO 32000-2, §8.4). Der Wert hört auf, ein lebendiges Feld zu sein, und wird zu gedruckter Tinte. Weil das Formular keine interaktiven Felder mehr trägt, entfernt die Engine dann den AcroForm-Eintrag: Es ist nichts mehr übrig, woran etwas interaktiv sein könnte.

Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
Place the widgetsEach field is drawn as a widget annotation — a rectangle on a chosen page that a viewer can type into, tick, or pick from.
Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

From a fillable form to a frozen record: declare typed fields, draw their on-page widgets, fill in values, then flatten those values into immutable page graphics and drop the now-empty interactive form.

Praktisches Beispiel

Ein kleines, repräsentatives Formular: ein paar typisierte Felder aufbauen und es dann zu einem eingefrorenen Nachweis flachklopfen.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();

// Typed builders, called straight on the document. You pick the field
// type by choosing its builder method — textField, checkBox, comboBox —
// and you pass the value to freeze at creation time. The engine writes
// the spec-correct PDF type and flags for you.
$document->textField('full_name', x: 40, y: 700, w: 220, h: 18, default: 'Ada Lovelace');
$document->checkBox('agree_terms', x: 40, y: 660, size: 14, checked: true);
$document->comboBox(
    'plan',
    x: 40,
    y: 620,
    w: 160,
    h: 18,
    items: ['Starter', 'Team', 'Enterprise'],
    selected: 'Team',
);

// Flatten: the values become immutable page graphics and the
// interactive AcroForm is dropped. The result is a frozen record.
$document->flattenForms();

$bytes = $document->getPdfData();

Vor flattenForms() ist dies ein ausfüllbares Formular. Danach sind dieselben Werte in die Seite gedruckt, und es bleibt kein Feld zu ändern. Sie wählen den Feldtyp, indem Sie seine Builder-Methode wählen – textField, checkBox, comboBox –, sodass ein falscher Typ nicht als loser String kodiert werden kann: Ein Tippfehler ist ein Aufruf einer Methode, die nicht existiert, abgefangen, bevor irgendein Feld geschrieben wird, nicht ein klammheimlich falsches Feld. Das ist dieselbe Verweigern-zu-raten-Haltung, die der Rest der Engine einnimmt; siehe eine API, die sich weigert zu raten.

Häufiges Missverständnis

Die Falle ist der Glaube, dass das Ausfüllen eines Felds es einfriert. Tut es nicht. Ein gefülltes Feld trägt immer noch einen lebendigen Wert, den ein leistungsfähiger Reader bearbeiten kann, und ein Aussehen, das manche Reader neu erzeugen. „Ich habe den Wert gesetzt” und „das Dokument ist jetzt ein fester Nachweis” sind zwei verschiedene Zustände. Nur das Flachklopfen überschreitet von einem zum anderen, denn nur das Flachklopfen verwandelt den Wert in Seitengrafik, die sich nicht mehr wie ein Feld verhält.

Der spiegelbildliche Fehler besteht darin, einen Entwurf flachzuklopfen, an dem Sie noch Eingaben sammeln müssen. Einmal flachgeklopft, sind die Felder weg – das ist der ganze Sinn –, also klopfen Sie die Kopie flach, die endgültig sein soll, nicht die, die Sie noch in Umlauf bringen.

Es gibt eine Betriebsnuance, die es zu kennen lohnt. Wenn Sie die Engine bitten, ein Dokument flachzuklopfen, das keine Seiten hat, wirft sie Ihre Feldwerte nicht klammheimlich in den Müll. Es gibt keine Seitenfläche, auf die sie gemalt werden könnten, also bewahrt NextPDF, statt das interaktive Formular zu entfernen und seine Werte zu nullen – ein vollständiger, unsichtbarer Datenverlust –, das Formular, hält jeden Wert intakt und weiterhin interaktiv und gibt eine Warnung aus, die Ihnen sagt, was passiert ist. Sie fügen eine Seite hinzu und klopfen erneut flach. Dies ist ein bewusstes Design ohne Datenverlust: Die Engine gibt lieber ein noch ausfüllbares Dokument und eine klare Warnung zurück als ein klammheimlich geleertes. Die Werte, die Ihnen anvertraut wurden, sind das eine, das ein Flachklopfen niemals wegwerfen darf.

Grenzen und Abgrenzungen

Die Formularunterstützung von NextPDF ist voller Core: typisierte Builder für die gängigen interaktiven Feldsteuerelemente, ein Formular-Flachklopfer und ein Feldmanager, der die Felder als korrekte PDF-Objekte schreibt. Diese Seite beschreibt diese Core-Oberfläche.

AcroForm fields and flattening — edition availability
Edition	Availability
Core	Typisierte Builder für Textfeld-, Kontrollkästchen-, Optionsfeld-, Auswahl- (Listenfeld und Kombinationsfeld) und Druckschaltflächenfelder; Widget-Platzierung; ein Feldmanager; und ein Formular-Flachklopfer, der Werte in Seitengrafik einbäckt. In jeder Edition verfügbar.
Pro	Not in this edition
Enterprise	Not in this edition

Das Flachklopfen ist von Natur aus eine Einbahnstraße. Es entfernt das interaktive Formular, sodass der Nachweis fest ist; es ist kein „vorübergehend sperren”-Umschalter, und es gibt kein Rückgängig-Flachklopfen, das bearbeitbare Felder aus gemalter Grafik neu ableitet. Wenn Sie eine Kopie brauchen, an der Leute weiterarbeiten können, behalten Sie das nicht flachgeklopfte Formular und klopfen Sie ein Duplikat flach.

Das Flachklopfen ist auch keine Signatur. Es macht ein Dokument im Sinne eines gewöhnlichen Readers nicht bearbeitbar, aber es beweist nicht kryptografisch, wer es erzeugt hat oder dass es sich seither nicht geändert hat. Wenn der Nachweis nachweislich der sein muss, der vereinbart wurde, klopfen Sie flach und signieren Sie dann; siehe wie Signaturen in einem PDF liegen.

Schließlich ist ein getaggtes, barrierefreies Formular eine andere Angelegenheit als ein flachgeklopftes. Wenn die ausfüllbare Version mit assistiver Technologie nutzbar sein muss, brauchen die Felder barrierefreie Namen und Struktur, solange sie noch interaktiv sind; siehe was ein PDF barrierefrei macht.

Glossar

AcroForm – das interaktive Formular eines PDF: der Baum typisierter Felder, deklariert im Dokumentkatalog, der die Datei ausfüllbar macht (Spec: ISO 32000-2, §12.7).
Feld – die Datenseite eines Formularsteuerelements: ein Name, ein Typ, ein Wert und Flags. Unabhängig davon, wie es auf der Seite aussieht.
Widget-Annotation – das sichtbare, anklickbare Rechteck auf einer Seite, durch das ein Reader mit einem Feld interagiert (Spec: ISO 32000-2, §12.5). Ein Feld kann mehrere haben.
Auswahlfeld – ein Feld, das eine Menge von Optionen bietet: ein Listenfeld zeigt sie offen, ein Kombinationsfeld zeigt ein Aufklappmenü. Beide sind derselbe PDF-Feldtyp.
Flachklopfen – den aktuellen Wert jedes Felds als unveränderliche Grafik in die Seite zu rendern und das interaktive Formular zu entfernen, sodass ein eingefrorener Nachweis entsteht.
Eingefrorener Nachweis – ein flachgeklopftes Dokument: Es zeigt in jedem Reader eine feste Sache und hat keine Felder mehr zu bearbeiten.