Du formulaire à remplir à l'enregistrement figé : remplissage et aplatissement AcroForm

SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7

En bref

Un formulaire PDF a deux vies. D’abord il est à remplir : un ensemble de champs typés dans lesquels une personne saisit, qu’elle coche ou parmi lesquels elle choisit. Puis, lorsque l’accord est conclu, il devient un enregistrement figé : les valeurs sont imprimées dans la page elle-même, de sorte que chaque lecteur, sur chaque appareil, voit exactement ce qui a été convenu. NextPDF construit le premier et produit le second, avec une garantie délibérée — il ne jettera pas discrètement les valeurs en chemin.

Pourquoi c’est important

L’écart entre « ce que j’ai rempli » et « ce que tu vois » est l’endroit où les formulaires tournent mal.

Un champ à remplir est, techniquement, un petit widget interactif dessiné par-dessus la page. Différents lecteurs peuvent le rendre différemment. Certains honorent une valeur enregistrée, certains régénèrent l’apparence à partir d’une police que tu n’as pas, certains laissent un lecteur l’éditer à nouveau. Pour un brouillon que tu veux voir tes collaborateurs continuer d’éditer, c’est précisément le but. Pour la copie signée de ce qui a été convenu, c’est un risque : l’enregistrement ne devrait pas dépendre de l’application qui l’ouvre, et il ne devrait pas être modifiable après coup.

L’aplatissement comble l’écart. Il prend la valeur actuelle de chaque champ et la peint dans la page sous forme de graphiques ordinaires et immuables — le même genre de contenu qu’un titre ou un logo. Après cela, il n’y a plus de champ à éditer ni d’apparence à régénérer. Le document montre une seule chose, la même chose, partout.

La version courte

• Un AcroForm est le formulaire interactif du document : un arbre de champs typés déclarés dans le catalogue (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7).
• Chaque champ est rendu visible par une annotation widget — le rectangle sur la page sur lequel tu cliques ou dans lequel tu saisis (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5).
• NextPDF fournit des constructeurs typés pour chaque contrôle de formulaire pris en charge hors signature — texte, case à cocher, bouton radio, liste déroulante et liste combinée (choix), et bouton-poussoir — plus un gestionnaire de champs qui les écrit comme de véritables objets PDF.
• L’aplatissement rend la valeur de chaque champ dans le flux de contenu de la page et supprime le formulaire interactif désormais redondant, laissant un enregistrement figé.
• Si tu demandes l’aplatissement d’un document qui n’a aucune page, NextPDF ne détruit pas discrètement les valeurs de tes champs. Il préserve le formulaire, t’avertit, et te laisse ajouter une page et aplatir correctement.

L’approche de NextPDF

Le modèle mental comporte deux couches. Le champ est la donnée : un nom, un type, une valeur et un ensemble de drapeaux. Le widget est l’image : un rectangle sur une page précise qui permet à un lecteur d’interagir avec le champ (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5). Un seul champ peut même apparaître à travers plusieurs widgets — c’est exactement ainsi que fonctionne un groupe de boutons radio, plusieurs choix sur la page câblés à une seule valeur sous-jacente.

NextPDF donne à chaque type de champ son propre constructeur typé, pour que tu n’assembles jamais un dictionnaire brut à la main. Le type porte pour toi les détails PDF corrects. Une case à cocher, un bouton radio et un bouton-poussoir partagent tous le même type de formulaire sous-jacent dans la spécification et se distinguent par leurs drapeaux ; le moteur fixe ces drapeaux à partir du type que tu as choisi, plutôt que de te demander de te souvenir quel bit signifie « radio ». Une liste déroulante et une liste combinée sont toutes deux des champs de choix ; là encore, le constructeur choisit le bon encodage. Tu énonces le type de champ une fois, en mots, et les octets suivent.

L’aplatissement est la seconde moitié. L’aplatisseur regroupe les annotations widgets selon la page qui les détient, en utilisant le rectangle de chaque widget pour le placement sur cette page, puis rend chaque valeur sous forme d’une petite suite d’opérateurs de flux de contenu — définir une couleur, définir une position de texte, dessiner les glyphes — ajoutée au contenu existant de cette page (SpecSpec: ISO 32000-2, §8.4ISO 32000-2 §8.4). La valeur cesse d’être un champ vivant et devient de l’encre peinte. Parce que le formulaire ne porte plus aucun champ interactif, le moteur supprime alors l’entrée AcroForm : il ne reste plus rien qui doive être interactif.

1. Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
2. 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.
3. Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
4. Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
5. Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

D'un formulaire à remplir à un enregistrement figé : déclare des champs typés, dessine leurs widgets sur la page, renseigne les valeurs, puis aplatis ces valeurs en graphiques de page immuables et supprime le formulaire interactif désormais vide.

Exemple pratique

Un formulaire petit et représentatif : construis quelques champs typés, puis aplatis-le en un enregistrement figé.

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

Avant flattenForms(), c’est un formulaire à remplir. Après, les mêmes valeurs sont peintes dans la page et il ne reste aucun champ à changer. Tu choisis le type de champ en choisissant sa méthode de construction — textField, checkBox, comboBox — de sorte qu’un type erroné ne peut pas être encodé sous forme de chaîne libre : une faute de frappe est un appel à une méthode qui n’existe pas, attrapé avant qu’aucun champ ne soit écrit, et non un champ silencieusement faux. C’est la même posture de refus de deviner que le reste du moteur adopte ; vois une API qui refuse de deviner.

Idée fausse courante

Le piège est de croire que remplir un champ le fige. Ce n’est pas le cas. Un champ rempli porte toujours une valeur vivante qu’un lecteur capable peut éditer, et une apparence que certains lecteurs régénéreront. « J’ai défini la valeur » et « le document est désormais un enregistrement fixe » sont deux états différents. Seul l’aplatissement franchit le pas de l’un à l’autre, car seul l’aplatissement transforme la valeur en graphiques de page qui ne se comportent plus comme un champ.

L’erreur inverse est d’aplatir un brouillon sur lequel tu dois encore collecter des données. Une fois aplatis, les champs ont disparu — c’est tout l’intérêt — alors aplatis la copie que tu destines à être finale, pas celle que tu fais encore circuler.

Human-factors note:Human-factors note

There is one operability nuance worth knowing. If you ask the engine to flatten a document that has no pages, it does not silently bin your field values. There is no page surface to paint them onto, so instead of stripping the interactive form and nulling its values — a total, invisible data loss — NextPDF preserves the form, keeps every value intact and still interactive, and surfaces a warning telling you what happened. You add a page and flatten again. This is a deliberate no-data-loss design: the engine would rather hand back a still-fillable document and a clear warning than a quietly emptied one. The values you were trusted with are the one thing a flatten must never throw away.

Limites et frontières

Le support des formulaires de NextPDF est entièrement core : des constructeurs typés pour les contrôles de champ interactifs courants, un aplatisseur de formulaires, et un gestionnaire de champs qui écrit les champs comme de véritables objets PDF. Cette page décrit cette surface core.

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

L’aplatissement est à sens unique par conception. Il supprime le formulaire interactif pour que l’enregistrement soit fixe ; ce n’est pas un bouton « verrouiller temporairement », et il n’existe pas de dé-aplatissement qui re-dérive des champs éditables à partir de graphiques peints. Si tu as besoin d’une copie que les gens peuvent continuer d’éditer, conserve le formulaire non aplati et aplatis un double.

L’aplatissement n’est pas non plus une signature. Il rend un document non éditable au sens du lecteur ordinaire, mais il ne prouve pas cryptographiquement qui l’a produit ni qu’il n’a pas changé depuis. Lorsque l’enregistrement doit être prouvablement celui qui a été convenu, aplatis puis signe ; vois comment les signatures s’insèrent dans un PDF.

Enfin, un formulaire balisé et accessible est une préoccupation distincte d’un formulaire aplati. Si la version à remplir doit être utilisable avec une technologie d’assistance, les champs ont besoin de noms accessibles et de structure tant qu’ils sont encore interactifs ; vois ce qui rend un PDF accessible.

Documents liés

• Ce qui rend un PDF accessible — les champs de formulaire balisés et les noms accessibles, pour l’étape à remplir.
• Une API qui refuse de deviner — pourquoi le type de champ est une énumération typée, pas une chaîne que le moteur doit interpréter.
• L’anatomie d’un fichier PDF — où vivent réellement le catalogue, les pages et les annotations à partir desquels un formulaire est construit.
• Comment les signatures s’insèrent dans un PDF — comment rendre un enregistrement figé prouvablement celui qui a été convenu.

Glossaire

• AcroForm — le formulaire interactif d’un PDF : l’arbre de champs typés déclarés dans le catalogue du document qui rend le fichier remplissable (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7).
• Champ — le côté donnée d’un contrôle de formulaire : un nom, un type, une valeur et des drapeaux. Indépendant de son apparence sur la page.
• Annotation widget — le rectangle visible et cliquable sur une page à travers lequel un lecteur interagit avec un champ (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5). Un champ peut en avoir plusieurs.
• Champ de choix — un champ offrant un ensemble d’options : une liste déroulante les affiche ouvertes, une liste combinée affiche un menu déroulant. Les deux sont le même type de champ PDF.
• Aplatir — rendre la valeur actuelle de chaque champ dans la page sous forme de graphiques immuables et supprimer le formulaire interactif, produisant un enregistrement figé.
• Enregistrement figé — un document aplati : il montre une seule chose fixe dans chaque lecteur et n’a plus aucun champ à éditer.