入力可能フォームから凍結された記録へ — AcroForm の入力とフラット化

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

概要

PDF フォームには 2 つの生があります。最初それは 入力可能 です。人が打ち込み、チェックし、あるいは選ぶ、型付けされたフィールドの集合です。それから、合意がなされたとき、それは 凍結された記録 になります。値がページそのものに刷り込まれ、すべてのビューアが、すべてのデバイスで、合意された内容をそっくり目にします。NextPDF は前者を構築し、後者を生成します。1 つの意図的な保証とともに — 受け渡しの途中で値をひそかに捨てたりはしません。

なぜこれが重要か

「私が入力したもの」と「あなたが見るもの」の隔たりこそ、フォームが誤る場所です。

入力可能フィールドは、技術的には、ページに重ねて描かれた小さな対話的ウィジェットです。ビューアによって、それを異なって描画できます。あるものは保存された値を尊重し、あるものはあなたが持たないフォントから見た目を再生成し、あるものは読者にそれを再び編集させます。協力者に編集を続けてほしい下書きなら、それが狙いです。合意された内容の署名済みコピーにとっては、それは負債です。記録は、どのアプリケーションが開くかに依存すべきではなく、事後に編集可能であるべきでもありません。

フラット化はその隔たりを閉じます。それは各フィールドの現在の値を取り、それを通常の不変のグラフィックス — 見出しやロゴと同じ種類のコンテンツ — としてページに刷り込みます。その後は、編集すべきフィールドも、再生成すべき見た目もありません。文書は 1 つのものを、同じものを、どこでも示します。

要点

• AcroForm は文書の対話的フォームです。カタログに宣言された型付きフィールドのツリーです（SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7）。
• 各フィールドは ウィジェット注釈 によって可視になります。あなたがクリックしたり打ち込んだりするページ上の長方形です（SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5）。
• NextPDF は、サポートされるすべての非署名フォームコントロール — テキスト、チェックボックス、ラジオ、リストボックスとコンボボックス（選択）、そしてプッシュボタン — に型付きビルダーを同梱し、さらにそれらを正しい PDF オブジェクトとして書くフィールドマネージャを同梱します。
• フラット化 は、各フィールドの値をページのコンテンツストリームに描画し、いまや冗長になった対話的フォームを除去して、凍結された記録を残します。
• ページのない 文書のフラット化を求めた場合、NextPDF はあなたのフィールド値をひそかに破壊しません。フォームを保存し、警告し、あなたがページを追加して正しくフラット化できるようにします。

NextPDF のアプローチ

メンタルモデルは 2 つのレイヤーです。フィールド はデータです。名前、型、値、そしてフラグの集合です。ウィジェット は絵です。特定のページ上の長方形で、ビューアがフィールドと対話できるようにします（SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5）。1 つのフィールドが複数のウィジェットを通して現れることさえできます — それこそがラジオグループの働き方そのものです。1 つの基礎となる値に配線された、複数のページ上の選択肢です。

NextPDF は各フィールド型にそれ自身の型付きビルダーを与えるので、生のディクショナリを手で組み立てることはありません。型があなたのために PDF として正しい詳細を運びます。チェックボックス、ラジオボタン、プッシュボタンはすべて、仕様では同じ基礎となるフォーム型を共有し、それらのフラグによって区別されます。エンジンは、あなたが選んだ型からそれらのフラグを設定するので、どのビットが「ラジオ」を意味するかを覚えるよう求めません。リストボックスとコンボボックスはどちらも 選択 フィールドです。これもまた、ビルダーが正しいエンコーディングを選びます。あなたはフィールド型を一度、言葉で述べるだけで、バイトが続きます。

フラット化は後半です。フラット化器は、ウィジェット注釈を所有するページごとにグループ化し、各ウィジェットの長方形をそのページ上の配置に使い、それから各値を小さな一連のコンテンツストリーム演算子 — 色を設定し、テキスト位置を設定し、グリフを描く — として、そのページの既存のコンテンツに追記して描画します（SpecSpec: ISO 32000-2, §8.4ISO 32000-2 §8.4）。値はもはやライブのフィールドではなくなり、刷り込まれたインクになります。フォームがもはや対話的フィールドを携えないため、エンジンはそのうえで AcroForm エントリを除去します。対話的であるべきものが何も残っていないからです。

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.

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.

実践例

小さく代表的なフォームです。いくつかの型付きフィールドを構築し、それから凍結された記録へフラット化します。

<?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を参照してください。

よくある誤解

罠は、フィールドを 入力する ことがそれを凍結すると信じることです。そうではありません。入力済みのフィールドは、なお有能なビューアが編集できるライブの値と、一部のビューアが再生成する見た目を携えています。「私は値を設定した」と「文書はいまや固定された記録だ」は、2 つの異なる状態です。一方から他方へ渡るのはフラット化だけです。値をもはやフィールドのように振る舞わないページグラフィックスに変えるのは、フラット化だけだからです。

鏡像の間違いは、なお入力を収集する必要のある下書きをフラット化することです。いったんフラット化すれば、フィールドは消えます — それが全要点です — だから、まだ回覧中のものではなく、最終版にするつもりのコピーをフラット化してください。

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.

限界と境界

NextPDF のフォームサポートはフルコアです。一般的な対話的フィールドコントロールの型付きビルダー、フォームフラット化器、そしてフィールドを正しい PDF オブジェクトとして書くフィールドマネージャです。このページは、そのコアの面を説明します。

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

フラット化は設計上、一方向です。記録が固定されるよう対話的フォームを除去します。それは「一時的にロックする」トグルではなく、刷り込まれたグラフィックスから編集可能なフィールドを再導出するフラット化解除もありません。人々が編集を続けられるコピーが必要なら、フラット化していないフォームを保ち、複製をフラット化してください。

フラット化はまた、署名ではありません。それは通常のビューアの意味で文書を編集不可能にしますが、誰がそれを作ったか、あるいは作成以来変更されていないことを暗号的に証明はしません。記録が、合意されたものであると 証明可能に なければならないとき、フラット化してから署名してください。署名が PDF の中でどう収まるかを参照してください。

最後に、タグ付けされたアクセシブルなフォームは、フラット化されたフォームとは別個の関心事です。入力可能版が支援技術で使えなければならないなら、フィールドがまだ対話的なあいだに、アクセシブルな名前と構造が必要です。何が PDF をアクセシブルにするかを参照してください。

関連ドキュメント

• What makes a PDF accessible — タグ付けされたフォームフィールドとアクセシブルな名前、入力可能段階のために。
• An API that refuses to guess — なぜフィールド型が、エンジンが解釈しなければならない文字列ではなく、型付き列挙なのか。
• The anatomy of a PDF file — フォームがそこから構築されるカタログ、ページ、注釈が実際にどこに存在するか。
• How signatures sit in a PDF — 凍結された記録を、合意されたものであると 証明可能に する方法。

用語集

• AcroForm — PDF の対話的フォーム。文書カタログに宣言された型付きフィールドのツリーで、ファイルを入力可能にする（SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7）。
• フィールド（Field） — フォームコントロールのデータ側。名前、型、値、そしてフラグ。ページ上でどう見えるかとは独立。
• ウィジェット注釈（Widget annotation） — ビューアがフィールドと対話する、ページ上の可視でクリック可能な長方形（SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5）。1 つのフィールドが複数持つことがある。
• 選択フィールド（Choice field） — 一連の選択肢を提供するフィールド。リストボックス はそれらを開いて示し、コンボボックス はドロップダウンで示す。どちらも同じ PDF フィールド型。
• フラット化（Flatten） — 各フィールドの現在の値を不変のグラフィックスとしてページに描画し、対話的フォームを除去して、凍結された記録を生成すること。
• 凍結された記録（Frozen record） — フラット化された文書。すべてのビューアで 1 つの固定されたものを示し、編集すべきフィールドが残っていない。