Van invulbaar formulier tot bevroren record: AcroForm invullen en afvlakken

Spec: ISO 32000-2, §12.7

In een oogopslag

Een PDF-formulier heeft twee levens. Eerst is het invulbaar: een set getypeerde velden waarin een persoon typt, aanvinkt of uit kiest. Dan, wanneer de afspraak is gemaakt, wordt het een bevroren record: de waarden worden in de pagina zelf gedrukt zodat elke viewer, op elk apparaat, precies ziet wat is afgesproken. NextPDF bouwt het eerste en produceert het tweede, met één bewuste garantie — het zal de waarden onderweg niet stilletjes weggooien.

Waarom dit belangrijk is

De kloof tussen “wat ik heb ingevuld” en “wat jij ziet” is waar formulieren misgaan.

Een invulbaar veld is technisch gezien een kleine interactieve widget die over de pagina is getekend. Verschillende viewers kunnen het anders renderen. Sommige respecteren een opgeslagen waarde, sommige genereren het uiterlijk opnieuw uit een lettertype dat jij niet hebt, sommige laten een lezer het opnieuw bewerken. Voor een concept dat je collega’s wilt laten blijven bewerken, is dat juist de bedoeling. Voor het ondertekende exemplaar van wat is afgesproken, is het een aansprakelijkheid: het record zou niet mogen afhangen van welke applicatie het opent, en het zou achteraf niet bewerkbaar mogen zijn.

Afvlakken sluit de kloof. Het neemt de huidige waarde van elk veld en schildert die in de pagina als gewone, onveranderlijke grafiek — hetzelfde soort inhoud als een kop of een logo. Daarna is er geen veld om te bewerken en geen uiterlijk om opnieuw te genereren. Het document toont één ding, hetzelfde ding, overal.

De korte versie

Een AcroForm is het interactieve formulier van het document: een boom van getypeerde velden gedeclareerd in de catalog (Spec: ISO 32000-2, §12.7).
Elk veld wordt zichtbaar gemaakt door een widget-annotatie — de rechthoek op de pagina waarop je klikt of waarin je typt (Spec: ISO 32000-2, §12.5).
NextPDF levert getypeerde builders voor elke ondersteunde niet-handtekening-formuliercontrol — text, checkbox, radio, list box en combo box (choice), en push button — plus een veldmanager die ze als correcte PDF-objecten schrijft.
Afvlakken rendert de waarde van elk veld in de pagina-inhoudsstream en verwijdert het nu-overbodige interactieve formulier, met een bevroren record als resultaat.
Als je vraagt een document af te vlakken dat geen pagina’s heeft, vernietigt NextPDF je veldwaarden niet stilletjes. Het behoudt het formulier, waarschuwt je, en laat je een pagina toevoegen en correct afvlakken.

Hoe NextPDF dit aanpakt

Het mentale model bestaat uit twee lagen. Het veld is de data: een naam, een type, een waarde en een set vlaggen. De widget is het beeld: een rechthoek op een specifieke pagina die een viewer met het veld laat interacteren (Spec: ISO 32000-2, §12.5). Eén veld kan zelfs via meerdere widgets verschijnen — dat is precies hoe een radiogroep werkt, meerdere keuzes op de pagina gekoppeld aan één onderliggende waarde.

NextPDF geeft elk veldtype zijn eigen getypeerde builder, zodat je nooit met de hand een ruwe dictionary in elkaar zet. Het type draagt de PDF-correcte details voor je. Een checkbox, een radioknop en een push button delen allemaal hetzelfde onderliggende formuliertype in de spec en worden uit elkaar gehouden door hun vlaggen; de engine zet die vlaggen op basis van het type dat je hebt gekozen, in plaats van je te laten onthouden welke bit “radio” betekent. Een list box en een combo box zijn beide choice-velden; opnieuw kiest de builder de juiste codering. Je vermeldt het veldtype één keer, in woorden, en de bytes volgen.

Afvlakken is de tweede helft. De flattener groepeert widget-annotaties per hun eigen pagina, gebruikt de rechthoek van elke widget voor plaatsing op die pagina, en rendert vervolgens elke waarde als een kleine reeks inhoudsstream-operatoren — zet een kleur, zet een tekstpositie, teken de glyphs — toegevoegd aan de bestaande inhoud van die pagina (Spec: ISO 32000-2, §8.4). De waarde houdt op een levend veld te zijn en wordt geschilderde inkt. Omdat het formulier geen interactieve velden meer draagt, verwijdert de engine vervolgens de AcroForm-vermelding: er valt niets meer interactief over te zijn.

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.

Van een invulbaar formulier naar een bevroren record: declareer getypeerde velden, teken hun widgets op de pagina, vul waarden in, vlak die waarden vervolgens af tot onveranderlijke paginagrafiek en laat het nu-lege interactieve formulier vallen.

Praktisch voorbeeld

Een klein, representatief formulier: bouw een paar getypeerde velden en vlak het daarna af tot een bevroren record.

<?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();

Vóór flattenForms() is dit een invulbaar formulier. Erna zijn dezelfde waarden in de pagina geschilderd en is er geen veld meer over om te wijzigen. Je kiest het veldtype door zijn buildermethode te kiezen — textField, checkBox, comboBox — zodat een verkeerd type niet als een losse string kan worden gecodeerd: een typefout is een aanroep naar een methode die niet bestaat, gevangen voordat enig veld wordt geschreven, niet een stilletjes verkeerd veld. Dat is dezelfde weiger-te-gokken-houding die de rest van de engine inneemt; zie een API die weigert te gokken.

Veelvoorkomend misverstand

De valkuil is geloven dat het invullen van een veld het bevriest. Dat is niet zo. Een ingevuld veld draagt nog steeds een levende waarde die een capabele viewer kan bewerken, en een uiterlijk dat sommige viewers opnieuw genereren. “Ik heb de waarde gezet” en “het document is nu een vast record” zijn twee verschillende toestanden. Alleen afvlakken kruist van de ene naar de andere, omdat alleen afvlakken de waarde omzet in paginagrafiek die zich niet langer als een veld gedraagt.

De spiegelbeeldfout is een concept afvlakken waarop je nog invoer moet verzamelen. Eenmaal afgevlakt zijn de velden weg — dat is het hele punt — dus vlak het exemplaar af dat je definitief wilt laten zijn, niet het exemplaar dat je nog rondstuurt.

Er is één operabiliteitsnuance die het waard is om te kennen. Als je de engine vraagt een document af te vlakken dat geen pagina’s heeft, gooit het je veldwaarden niet stilletjes weg. Er is geen paginavlak om ze op te schilderen, dus in plaats van het interactieve formulier te strippen en zijn waarden te nullen — een totaal, onzichtbaar gegevensverlies — behoudt NextPDF het formulier, houdt elke waarde intact en nog interactief, en geeft een waarschuwing die je vertelt wat er is gebeurd. Je voegt een pagina toe en vlakt opnieuw af. Dit is een bewust no-data-loss-ontwerp: de engine geeft liever een nog-invulbaar document en een duidelijke waarschuwing terug dan een stilletjes geleegd exemplaar. De waarden die aan jou zijn toevertrouwd, zijn het ene ding dat een afvlakking nooit mag weggooien.

Grenzen en beperkingen

De formulierondersteuning van NextPDF is volledig core: getypeerde builders voor de gangbare interactieve veldcontrols, een formulier-flattener, en een veldmanager die de velden als correcte PDF-objecten schrijft. Deze pagina beschrijft dat core-oppervlak.

AcroForm fields and flattening — edition availability
Edition	Availability
Core	Typed builders for text, checkbox, radio, choice (list box and combo box), and push-button fields; widget placement; a field manager; and a form flattener that bakes values into page graphics. Available in every edition.
Pro	Not in this edition
Enterprise	Not in this edition

Afvlakken is eenrichting bij ontwerp. Het verwijdert het interactieve formulier zodat het record vast is; het is geen “tijdelijk vergrendelen”-schakelaar, en er is geen ontvlakking die bewerkbare velden opnieuw afleidt uit geschilderde grafiek. Als je een exemplaar nodig hebt dat mensen kunnen blijven bewerken, bewaar dan het niet-afgevlakte formulier en vlak een duplicaat af.

Afvlakken is ook geen handtekening. Het maakt een document niet-bewerkbaar in de gewone-viewer-zin, maar het bewijst niet cryptografisch wie het heeft geproduceerd of dat het sindsdien niet is gewijzigd. Wanneer het record aantoonbaar het afgesprokene moet zijn, vlak af en onderteken vervolgens; zie hoe handtekeningen in een PDF zitten.

Tot slot is een getagd, toegankelijk formulier een afzonderlijke zorg ten opzichte van een afgevlakt formulier. Als de invulbare versie bruikbaar moet zijn met ondersteunende technologie, hebben de velden toegankelijke namen en structuur nodig terwijl ze nog interactief zijn; zie wat een PDF toegankelijk maakt.

Verwante documentatie

Wat een PDF toegankelijk maakt — getagde formuliervelden en toegankelijke namen, voor het invulbare stadium.
Een API die weigert te gokken — waarom het veldtype een getypeerde enum is, geen string die de engine moet interpreteren.
De anatomie van een PDF-bestand — waar de catalog, pagina’s en annotaties waaruit een formulier is opgebouwd werkelijk leven.
Hoe handtekeningen in een PDF zitten — hoe je een bevroren record aantoonbaar het afgesprokene maakt.

Woordenlijst

AcroForm — het interactieve formulier van een PDF: de boom van getypeerde velden gedeclareerd in de document catalog die het bestand invulbaar maakt (Spec: ISO 32000-2, §12.7).
Veld — de datakant van een formuliercontrol: een naam, een type, een waarde en vlaggen. Onafhankelijk van hoe het er op de pagina uitziet.
Widget-annotatie — de zichtbare, aanklikbare rechthoek op een pagina waardoor een viewer met een veld interacteert (Spec: ISO 32000-2, §12.5). Eén veld kan er meerdere hebben.
Choice-veld — een veld dat een set opties biedt: een list box toont ze open, een combo box toont een dropdown. Beide zijn hetzelfde PDF-veldtype.
Afvlakken — de huidige waarde van elk veld in de pagina renderen als onveranderlijke grafiek en het interactieve formulier verwijderen, met een bevroren record als resultaat.
Bevroren record — een afgevlakt document: het toont in elke viewer één vast ding en heeft geen velden meer over om te bewerken.