От заполняемой формы к замороженной записи: заполнение и сведение AcroForm

Spec: ISO 32000-2, §12.7

Кратко

У формы PDF две жизни. Сначала она заполняемая: набор типизированных полей, в которые человек печатает, которые отмечает или из которых выбирает. Затем, когда соглашение достигнуто, она становится замороженной записью: значения напечатаны в саму страницу, так что каждая программа просмотра на каждом устройстве видит ровно то, о чём договорились. NextPDF строит первую и производит вторую, с одной намеренной гарантией — он не выбросит значения по-тихому по дороге.

Почему это важно

Зазор между «что я заполнил» и «что вы видите» — это место, где формы идут не так.

Заполняемое поле — это, технически, небольшой интерактивный виджет, нарисованный поверх страницы. Разные программы просмотра могут отрисовывать его по-разному. Одни уважают сохранённое значение, другие заново порождают вид из шрифта, которого у вас нет, третьи позволяют читателю снова его редактировать. Для черновика, который вы хотите, чтобы соавторы продолжали редактировать, это и есть смысл. Для подписанной копии того, о чём договорились, это уязвимость: запись не должна зависеть от того, какое приложение её открывает, и не должна быть редактируемой задним числом.

Сведение закрывает зазор. Оно берёт текущее значение каждого поля и впечатывает его в страницу как обычную, неизменяемую графику — того же рода содержимое, что заголовок или логотип. После этого нет ни поля для редактирования, ни вида для повторного порождения. Документ показывает одно, то же самое, везде.

Если коротко

AcroForm — это интерактивная форма документа: дерево типизированных полей, объявленных в каталоге (Spec: ISO 32000-2, §12.7).
Каждое поле делается видимым аннотацией-виджетом — прямоугольником на странице, по которому вы кликаете или в который печатаете (Spec: ISO 32000-2, §12.5).
NextPDF поставляет типизированные построители для каждого поддерживаемого элемента управления формы без подписи — текст, флажок, переключатель, список и поле со списком (choice), а также нажимная кнопка — плюс менеджер полей, который записывает их как надлежащие объекты PDF.
Сведение отрисовывает значение каждого поля в поток содержимого страницы и удаляет ставшую теперь избыточной интерактивную форму, оставляя замороженную запись.
Если вы просите свести документ, у которого нет страниц, NextPDF не уничтожает по-тихому значения ваших полей. Он сохраняет форму, предупреждает вас и позволяет добавить страницу и свести правильно.

Как NextPDF подходит к этому

Мысленная модель — два слоя. Поле — это данные: имя, тип, значение и набор флагов. Виджет — это картинка: прямоугольник на конкретной странице, который позволяет программе просмотра взаимодействовать с полем (Spec: ISO 32000-2, §12.5). Одно поле может даже проявиться через несколько виджетов — именно так работает группа переключателей: несколько выборов на странице, привязанных к одному лежащему в основе значению.

NextPDF даёт каждому типу поля собственный типизированный построитель, так что вы никогда не собираете сырой словарь вручную. Тип несёт за вас корректные для PDF детали. Флажок, переключатель и нажимная кнопка все разделяют один и тот же лежащий в основе тип формы в стандарте и различаются по своим флагам; движок устанавливает эти флаги из выбранного вами типа, а не просит вас помнить, какой бит означает «переключатель». Список и поле со списком — оба поля choice; и снова построитель выбирает правильную кодировку. Вы называете тип поля один раз, словами, а байты следуют за этим.

Сведение — вторая половина. Сводитель группирует аннотации-виджеты по их владеющей странице, используя прямоугольник каждого виджета для размещения на этой странице, затем отрисовывает каждое значение как небольшую серию операторов потока содержимого — установить цвет, установить позицию текста, нарисовать глифы, — добавленную к существующему содержимому этой страницы (Spec: ISO 32000-2, §8.4). Значение перестаёт быть живым полем и становится впечатанными чернилами. Поскольку форма больше не несёт интерактивных полей, движок затем удаляет запись AcroForm: интерактивным быть больше нечему.

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.

От заполняемой формы к замороженной записи: объявите типизированные поля, нарисуйте их виджеты на странице, заполните значения, затем сведите эти значения в неизменяемую графику страницы и сбросьте ставшую пустой интерактивную форму.

Практический пример

Небольшая, представительная форма: постройте несколько типизированных полей, затем сведите её в замороженную запись.

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

До flattenForms() это заполняемая форма. После него те же значения впечатаны в страницу, и поля, которое можно было бы изменить, не осталось. Вы выбираете тип поля, выбирая метод-построитель — textField, checkBox, comboBox, — так что неверный тип нельзя закодировать как свободную строку: опечатка — это вызов несуществующего метода, пойманный до того, как записано хоть одно поле, а не по-тихому неверное поле. Это та же позиция «отказа от догадок», которую занимает остальной движок; см. API, отказывающийся гадать.

Распространённое заблуждение

Ловушка — вера в то, что заполнение поля замораживает его. Это не так. Заполненное поле всё ещё несёт живое значение, которое способная программа просмотра может отредактировать, и вид, который некоторые программы порождают заново. «Я задал значение» и «документ теперь фиксированная запись» — два разных состояния. Только сведение переходит из одного в другое, потому что только сведение превращает значение в графику страницы, которая больше не ведёт себя как поле.

Зеркальная ошибка — сводить черновик, по которому вам ещё нужно собирать ввод. После сведения полей больше нет — в этом весь смысл, — так что сводите ту копию, которую вы намерены сделать окончательной, а не ту, которую ещё распространяете.

Есть один нюанс эксплуатационности, который стоит знать. Если вы просите движок свести документ, у которого нет страниц, он не выбрасывает по-тихому значения ваших полей. Нет поверхности страницы, чтобы их впечатать, поэтому вместо того, чтобы снять интерактивную форму и обнулить её значения — полная, невидимая потеря данных, — NextPDF сохраняет форму, держит каждое значение нетронутым и по-прежнему интерактивным и выводит предупреждение, говорящее вам, что произошло. Вы добавляете страницу и сводите снова. Это намеренная конструкция без потери данных: движок предпочтёт вернуть всё ещё заполняемый документ и ясное предупреждение, чем по-тихому опустошённый. Значения, которые вам доверили, — это та единственная вещь, которую сведение никогда не должно выбрасывать.

Пределы и границы

Поддержка форм в NextPDF — полностью ядро: типизированные построители для распространённых интерактивных элементов управления полями, сводитель форм и менеджер полей, который записывает поля как надлежащие объекты PDF. Эта страница описывает эту поверхность ядра.

AcroForm fields and flattening — edition availability
Edition	Availability
Core	Типизированные построители для полей текста, флажка, переключателя, choice (список и поле со списком) и нажимной кнопки; размещение виджетов; менеджер полей; и сводитель форм, который впекает значения в графику страницы. Доступно в каждом издании.
Pro	Not in this edition
Enterprise	Not in this edition

Сведение по своей природе одностороннее. Оно удаляет интерактивную форму, так что запись фиксирована; это не переключатель «временно заблокировать», и нет обратного сведения, которое заново выводило бы редактируемые поля из впечатанной графики. Если вам нужна копия, которую люди могут продолжать редактировать, сохраните несведённую форму и сведите дубликат.

Сведение также не является подписью. Оно делает документ нередактируемым в смысле обычной программы просмотра, но оно не доказывает криптографически, кто его произвёл или что он не изменился с тех пор. Когда запись должна быть доказуемо той, о которой договорились, сведите, а затем подпишите; см. как подписи располагаются в PDF.

Наконец, размеченная, доступная форма — это отдельная забота от сведённой. Если заполняемая версия должна быть пригодна для использования со вспомогательными технологиями, полям нужны доступные имена и структура, пока они ещё интерактивны; см. что делает PDF доступным.

Связанная документация

Что делает PDF доступным — размеченные поля форм и доступные имена, для заполняемой стадии.
API, отказывающийся гадать — почему тип поля — это типизированное перечисление, а не строка, которую движку приходится истолковывать.
Анатомия файла PDF — где на самом деле живут каталог, страницы и аннотации, из которых строится форма.
Как подписи располагаются в PDF — как сделать замороженную запись доказуемо той, о которой договорились.

Глоссарий

AcroForm — интерактивная форма PDF: дерево типизированных полей, объявленных в каталоге документа, которое делает файл заполняемым (Spec: ISO 32000-2, §12.7).
Поле — сторона данных элемента управления формы: имя, тип, значение и флаги. Независимо от того, как оно выглядит на странице.
Аннотация-виджет — видимый, кликабельный прямоугольник на странице, через который программа просмотра взаимодействует с полем (Spec: ISO 32000-2, §12.5). У одного поля их может быть несколько.
Поле choice — поле, предлагающее набор вариантов: список показывает их открытыми, поле со списком показывает выпадающий список. Оба — один и тот же тип поля PDF.
Свести — отрисовать текущее значение каждого поля в страницу как неизменяемую графику и удалить интерактивную форму, производя замороженную запись.
Замороженная запись — сведённый документ: он показывает одну фиксированную вещь в каждой программе просмотра, и полей для редактирования не осталось.