Od wypełnialnego formularza do zamrożonego zapisu: wypełnianie i spłaszczanie AcroForm

Spec: ISO 32000-2, §12.7

W skrócie

Formularz PDF ma dwa życia. Najpierw jest wypełnialny: zestaw otypowanych pól, w które ktoś wpisuje, odhacza je lub wybiera z nich. Potem, gdy uzgodnienie zostaje zawarte, staje się zamrożonym zapisem: wartości są wydrukowane w samą stronę, więc każdy czytnik, na każdym urządzeniu, widzi dokładnie to, co zostało uzgodnione. NextPDF buduje pierwsze i wytwarza drugie, z jedną celową gwarancją — nie wyrzuci po cichu wartości po drodze.

Dlaczego to ma znaczenie

Luka między „co wypełniłem” a „co widzisz” to miejsce, gdzie formularze idą źle.

Wypełnialne pole jest, technicznie, małym interaktywnym widżetem narysowanym nad stroną. Różne czytniki mogą renderować je różnie. Jedne honorują zapisaną wartość, inne odtwarzają wygląd z czcionki, której nie masz, jeszcze inne pozwalają czytelnikowi edytować je ponownie. Dla wersji roboczej, którą chcesz, by współpracownicy nadal edytowali, to jest właśnie sens. Dla podpisanej kopii tego, co uzgodniono, to zobowiązanie: zapis nie powinien zależeć od tego, która aplikacja go otwiera, ani nie powinien być edytowalny po fakcie.

Spłaszczanie zamyka tę lukę. Bierze bieżącą wartość każdego pola i maluje ją w stronę jako zwykłą, niezmienialną grafikę — ten sam rodzaj treści co nagłówek czy logo. Po tym nie ma już pola do edycji ani wyglądu do odtworzenia. Dokument pokazuje jedno, to samo, wszędzie.

Wersja skrócona

AcroForm to interaktywny formularz dokumentu: drzewo otypowanych pól zadeklarowanych w katalogu (Spec: ISO 32000-2, §12.7).
Każde pole jest uwidaczniane przez adnotację widżetu — prostokąt na stronie, który klikasz lub w który wpisujesz (Spec: ISO 32000-2, §12.5).
NextPDF dostarcza otypowane konstruktory dla każdej wspieranej kontrolki formularza bez podpisu — pole tekstowe, pole wyboru, przycisk opcji, listę i pole kombi (choice) oraz przycisk — plus menedżer pól, który zapisuje je jako właściwe obiekty PDF.
Spłaszczanie renderuje wartość każdego pola do strumienia treści strony i usuwa zbędny już interaktywny formularz, pozostawiając zamrożony zapis.
Jeśli poprosisz o spłaszczenie dokumentu, który nie ma stron, NextPDF nie niszczy po cichu wartości twoich pól. Zachowuje formularz, ostrzega cię i pozwala dodać stronę i spłaszczyć poprawnie.

Jak podchodzi do tego NextPDF

Modelem myślowym są dwie warstwy. Pole to dane: nazwa, typ, wartość oraz zestaw flag. Widżet to obraz: prostokąt na konkretnej stronie, który pozwala czytnikowi wejść w interakcję z polem (Spec: ISO 32000-2, §12.5). Jedno pole może nawet ujawniać się przez kilka widżetów — dokładnie tak działa grupa przycisków opcji, kilka wyborów na stronie podłączonych do jednej wartości pod spodem.

NextPDF nadaje każdemu typowi pola jego własny otypowany konstruktor, więc nigdy nie składasz surowego słownika ręcznie. Typ niesie za ciebie poprawne dla PDF szczegóły. Pole wyboru, przycisk opcji i przycisk mają w specyfikacji ten sam podstawowy typ formularza i są rozróżniane przez swoje flagi; silnik ustawia te flagi na podstawie wybranego przez ciebie typu, zamiast prosić cię o pamiętanie, który bit oznacza „opcja”. Lista i pole kombi to oba pola choice; ponownie, konstruktor wybiera właściwe kodowanie. Stwierdzasz typ pola raz, słowami, a bajty podążają za tym.

Spłaszczanie to druga połowa. Spłaszczacz grupuje adnotacje widżetów według ich strony właścicielskiej, używając prostokąta każdego widżetu do rozmieszczenia na tej stronie, a następnie renderuje każdą wartość jako małą serię operatorów strumienia treści — ustaw kolor, ustaw pozycję tekstu, narysuj glify — dołączoną do istniejącej treści tej strony (Spec: ISO 32000-2, §8.4). Wartość przestaje być żywym polem i staje się namalowanym atramentem. Ponieważ formularz nie niesie już żadnych interaktywnych pól, silnik usuwa następnie wpis AcroForm: nie zostaje już nic, co mogłoby być interaktywne.

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.

Od wypełnialnego formularza do zamrożonego zapisu: zadeklaruj otypowane pola, narysuj ich widżety na stronie, wypełnij wartości, a następnie spłaszcz te wartości w niezmienialną grafikę strony i usuń pusty już interaktywny formularz.

Praktyczny przykład

Mały, reprezentatywny formularz: zbuduj kilka otypowanych pól, a następnie spłaszcz je w zamrożony zapis.

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

Przed flattenForms() to wypełnialny formularz. Po nim te same wartości są namalowane w stronę i nie zostaje żadne pole do zmiany. Typ pola wybierasz, wybierając jego metodę konstruktora — textField, checkBox, comboBox — więc błędnego typu nie da się zakodować jako luźnego łańcucha: literówka to wywołanie metody, która nie istnieje, wychwycone przed zapisaniem jakiegokolwiek pola, a nie po cichu błędne pole. To ta sama postawa odmowy zgadywania, którą przyjmuje reszta silnika; zobacz API, które odmawia zgadywania.

Częste nieporozumienie

Pułapką jest przekonanie, że wypełnienie pola je zamraża. Nie zamraża. Wypełnione pole nadal niesie żywą wartość, którą zdolny czytnik może edytować, oraz wygląd, który niektóre czytniki odtworzą. „Ustawiłem wartość” i „dokument jest teraz stałym zapisem” to dwa różne stany. Tylko spłaszczanie przechodzi z jednego do drugiego, ponieważ tylko spłaszczanie zamienia wartość w grafikę strony, która nie zachowuje się już jak pole.

Lustrzanym odbiciem tego błędu jest spłaszczenie wersji roboczej, na której nadal musisz zbierać dane wejściowe. Po spłaszczeniu pola znikają — taki jest cały sens — więc spłaszcz tę kopię, która ma być ostateczna, a nie tę, którą wciąż obiegasz.

Jest jeden niuans operacyjny, który warto znać. Jeśli poprosisz silnik o spłaszczenie dokumentu, który nie ma stron, nie wrzuci on po cichu do kosza wartości twoich pól. Nie ma powierzchni strony, na której można je namalować, więc zamiast zdejmować interaktywny formularz i zerować jego wartości — całkowita, niewidoczna utrata danych — NextPDF zachowuje formularz, utrzymuje każdą wartość nienaruszoną i wciąż interaktywną oraz wyświetla ostrzeżenie mówiące, co się stało. Dodajesz stronę i spłaszczasz ponownie. To celowy projekt bez utraty danych: silnik woli oddać wciąż wypełnialny dokument i jasne ostrzeżenie niż po cichu opróżniony. Wartości, które ci powierzono, to jedna rzecz, której spłaszczanie nigdy nie może wyrzucić.

Ograniczenia i granice

Wsparcie formularzy w NextPDF jest pełne podstawowe: otypowane konstruktory dla częstych interaktywnych kontrolek pól, spłaszczacz formularzy oraz menedżer pól, który zapisuje pola jako właściwe obiekty PDF. Ta strona opisuje tę podstawową powierzchnię.

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

Spłaszczanie jest z założenia jednokierunkowe. Usuwa interaktywny formularz, więc zapis jest stały; to nie przełącznik „zablokuj tymczasowo” i nie ma cofnięcia spłaszczenia, które odtworzyłoby edytowalne pola z namalowanej grafiki. Jeśli potrzebujesz kopii, którą ludzie mogą dalej edytować, zachowaj niespłaszczony formularz i spłaszcz duplikat.

Spłaszczanie też nie jest podpisem. Czyni dokument nieedytowalnym w sensie zwykłego czytnika, ale nie dowodzi kryptograficznie, kto go wytworzył, ani że nie zmienił się od tego czasu. Gdy zapis musi być dowodnie tym, który uzgodniono, spłaszcz, a następnie podpisz; zobacz jak podpisy siedzą w PDF.

Wreszcie otagowany, dostępny formularz to osobna troska od spłaszczonego. Jeśli wersja wypełnialna musi być użyteczna z technologią wspomagającą, pola potrzebują dostępnych nazw i struktury, póki są jeszcze interaktywne; zobacz co czyni PDF dostępnym.

Powiązane dokumenty

Co czyni PDF dostępnym — otagowane pola formularza i dostępne nazwy, dla etapu wypełnialnego.
API, które odmawia zgadywania — dlaczego typ pola to otypowane wyliczenie, a nie łańcuch, który silnik musi interpretować.
Anatomia pliku PDF — gdzie naprawdę żyją katalog, strony i adnotacje, z których budowany jest formularz.
Jak podpisy siedzą w PDF — jak uczynić zamrożony zapis dowodnie tym, który uzgodniono.

Słownik pojęć

AcroForm — interaktywny formularz PDF: drzewo otypowanych pól zadeklarowanych w katalogu dokumentu, które czyni plik wypełnialnym (Spec: ISO 32000-2, §12.7).
Pole — strona danych kontrolki formularza: nazwa, typ, wartość oraz flagi. Niezależne od tego, jak wygląda na stronie.
Adnotacja widżetu — widoczny, klikalny prostokąt na stronie, przez który czytnik wchodzi w interakcję z polem (Spec: ISO 32000-2, §12.5). Jedno pole może mieć ich kilka.
Pole choice — pole oferujące zestaw opcji: lista pokazuje je otwarte, pole kombi pokazuje rozwijaną listę. Oba to ten sam typ pola PDF.
Spłaszczanie — wyrenderowanie bieżącej wartości każdego pola w stronę jako niezmienialnej grafiki i usunięcie interaktywnego formularza, co wytwarza zamrożony zapis.
Zamrożony zapis — spłaszczony dokument: pokazuje jedną stałą rzecz w każdym czytniku i nie ma już pól do edycji.