De formulario rellenable a registro congelado: rellenar y aplanar AcroForm

Spec: ISO 32000-2, §12.7

De un vistazo

Un formulario PDF tiene dos vidas. Primero es rellenable: un conjunto de campos tipados en los que una persona escribe, marca o entre los que elige. Luego, cuando se cierra el acuerdo, se convierte en un registro congelado: los valores se imprimen en la propia página, de modo que cada lector, en cada dispositivo, ve exactamente lo que se acordó. NextPDF construye lo primero y produce lo segundo, con una garantía deliberada: no descartará en silencio los valores por el camino.

Por qué importa

La brecha entre «lo que rellené» y «lo que usted ve» es donde los formularios se tuercen.

Un campo rellenable es, técnicamente, un pequeño widget interactivo dibujado sobre la página. Distintos lectores pueden renderizarlo de forma distinta. Algunos respetan un valor guardado, otros regeneran el aspecto a partir de una fuente que usted no tiene, otros permiten que un lector lo vuelva a editar. Para un borrador que quiere que los colaboradores sigan editando, ese es el objetivo. Para la copia firmada de lo acordado, es un pasivo: el registro no debería depender de qué aplicación lo abre, y no debería ser editable después de los hechos.

Aplanar cierra la brecha. Toma el valor actual de cada campo y lo pinta en la página como gráficos ordinarios e inmutables, el mismo tipo de contenido que un encabezado o un logotipo. Después de eso, no hay ningún campo que editar ni ningún aspecto que regenerar. El documento muestra una sola cosa, la misma cosa, en todas partes.

La versión breve

Un AcroForm es el formulario interactivo del documento: un árbol de campos tipados declarados en el catálogo (Spec: ISO 32000-2, §12.7).
Cada campo se hace visible mediante una anotación de widget: el rectángulo en la página en el que se hace clic o se escribe (Spec: ISO 32000-2, §12.5).
NextPDF ofrece constructores tipados para todo control de formulario sin firma admitido —texto, casilla de verificación, botón de opción, cuadro de lista y cuadro combinado (choice), y botón de acción— más un gestor de campos que los escribe como objetos PDF apropiados.
Aplanar renderiza el valor de cada campo en el flujo de contenido de la página y elimina el formulario interactivo ya redundante, dejando un registro congelado.
Si pide aplanar un documento que no tiene páginas, NextPDF no destruye en silencio los valores de sus campos. Conserva el formulario, le avisa y le permite añadir una página y aplanar correctamente.

Cómo lo aborda NextPDF

El modelo mental son dos capas. El campo son los datos: un nombre, un tipo, un valor y un conjunto de banderas. El widget es la imagen: un rectángulo en una página concreta que permite a un lector interactuar con el campo (Spec: ISO 32000-2, §12.5). Un mismo campo puede incluso manifestarse a través de varios widgets: así es exactamente como funciona un grupo de botones de opción, varias opciones en la página cableadas a un único valor subyacente.

NextPDF da a cada tipo de campo su propio constructor tipado, de modo que usted nunca ensambla a mano un diccionario en bruto. El tipo lleva por usted los detalles correctos según PDF. Una casilla de verificación, un botón de opción y un botón de acción comparten todos el mismo tipo de formulario subyacente en el estándar y se distinguen por sus banderas; el motor establece esas banderas a partir del tipo que usted eligió, en lugar de pedirle que recuerde qué bit significa «opción». Un cuadro de lista y un cuadro combinado son ambos campos choice; de nuevo, el constructor elige la codificación correcta. Usted enuncia el tipo de campo una vez, con palabras, y los bytes le siguen.

Aplanar es la segunda mitad. El aplanador agrupa las anotaciones de widget por su página propietaria, usando el rectángulo de cada widget para la colocación en esa página, y luego renderiza cada valor como una pequeña secuencia de operadores de flujo de contenido —establecer un color, establecer una posición de texto, dibujar los glifos— añadida al contenido existente de esa página (Spec: ISO 32000-2, §8.4). El valor deja de ser un campo vivo y se convierte en tinta pintada. Como el formulario ya no lleva ningún campo interactivo, el motor elimina entonces la entrada AcroForm: no queda nada de lo que ser interactivo.

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.

Ejemplo práctico

Un formulario pequeño y representativo: construir unos cuantos campos tipados y luego aplanarlo en un registro congelado.

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

Antes de flattenForms(), esto es un formulario rellenable. Después de él, los mismos valores quedan pintados en la página y no hay ningún campo que cambiar. Usted elige el tipo de campo eligiendo su método constructor —textField, checkBox, comboBox— de modo que un tipo equivocado no puede codificarse como una cadena suelta: una errata es una llamada a un método que no existe, detectada antes de que se escriba ningún campo, no un campo silenciosamente equivocado. Es la misma postura de negarse a adivinar que adopta el resto del motor; consulte una API que se niega a adivinar.

Concepto erróneo habitual

La trampa es creer que rellenar un campo lo congela. No lo hace. Un campo rellenado sigue llevando un valor vivo que un lector capaz puede editar, y un aspecto que algunos lectores regenerarán. «Establecí el valor» y «el documento es ahora un registro fijo» son dos estados distintos. Solo aplanar cruza de uno al otro, porque solo aplanar convierte el valor en gráficos de página que ya no se comportan como un campo.

El error espejo es aplanar un borrador con el que todavía necesita recoger entradas. Una vez aplanados, los campos desaparecen —ese es todo el sentido—, así que aplane la copia que pretende que sea definitiva, no la que aún está haciendo circular.

Hay un matiz de operabilidad que conviene conocer. Si pide al motor que aplane un documento que no tiene páginas, no tira en silencio los valores de sus campos. No hay superficie de página sobre la que pintarlos, así que en lugar de despojar al formulario de su interactividad y anular sus valores —una pérdida de datos total e invisible—, NextPDF conserva el formulario, mantiene cada valor intacto y aún interactivo, y emite una advertencia que le dice qué ocurrió. Usted añade una página y aplana de nuevo. Es un diseño deliberado sin pérdida de datos: el motor prefiere devolverle un documento todavía rellenable y una advertencia clara antes que uno vaciado en silencio. Los valores que se le confiaron son lo único que un aplanado nunca debe descartar.

Límites y fronteras

El soporte de formularios de NextPDF es de núcleo completo: constructores tipados para los controles de campo interactivos comunes, un aplanador de formularios y un gestor de campos que escribe los campos como objetos PDF apropiados. Esta página describe esa superficie de núcleo.

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

Aplanar es de un solo sentido por diseño. Elimina el formulario interactivo para que el registro quede fijo; no es un interruptor de «bloquear temporalmente», y no hay ningún des-aplanado que vuelva a derivar campos editables a partir de gráficos pintados. Si necesita una copia que la gente pueda seguir editando, conserve el formulario sin aplanar y aplane un duplicado.

Aplanar tampoco es una firma. Hace que un documento no sea editable en el sentido del lector ordinario, pero no demuestra criptográficamente quién lo produjo ni que no ha cambiado desde entonces. Cuando el registro deba ser demostrablemente el que se acordó, aplane y luego firme; consulte cómo se sitúan las firmas en un PDF.

Por último, un formulario etiquetado y accesible es una preocupación separada de uno aplanado. Si la versión rellenable debe ser utilizable con tecnología de asistencia, los campos necesitan nombres accesibles y estructura mientras siguen siendo interactivos; consulte qué hace accesible a un PDF.

Documentos relacionados

Qué hace accesible a un PDF: campos de formulario etiquetados y nombres accesibles, para la etapa rellenable.
Una API que se niega a adivinar: por qué el tipo de campo es un enum tipado, no una cadena que el motor tenga que interpretar.
La anatomía de un archivo PDF: dónde viven realmente el catálogo, las páginas y las anotaciones a partir de los que se construye un formulario.
Cómo se sitúan las firmas en un PDF: cómo hacer que un registro congelado sea demostrablemente el que se acordó.

Glosario

AcroForm: el formulario interactivo de un PDF: el árbol de campos tipados declarados en el catálogo del documento que hace el archivo rellenable (Spec: ISO 32000-2, §12.7).
Campo: el lado de datos de un control de formulario: un nombre, un tipo, un valor y banderas. Independiente de cómo se ve en la página.
Anotación de widget: el rectángulo visible y en el que se puede hacer clic en una página a través del cual un lector interactúa con un campo (Spec: ISO 32000-2, §12.5). Un campo puede tener varios.
Campo choice: un campo que ofrece un conjunto de opciones: un cuadro de lista las muestra abiertas, un cuadro combinado muestra un desplegable. Ambos son el mismo tipo de campo PDF.
Aplanar: renderizar el valor actual de cada campo en la página como gráficos inmutables y eliminar el formulario interactivo, produciendo un registro congelado.
Registro congelado: un documento aplanado: muestra una sola cosa fija en cada lector y no le queda ningún campo que editar.