Doldurulabilir formdan donmuş kayda: AcroForm doldurma ve düzleştirme

Spec: ISO 32000-2, §12.7

Bir bakışta

Bir PDF formunun iki yaşamı vardır. Önce doldurulabilirdir: bir kişinin yazdığı, işaretlediği ya da arasından seçtiği bir dizi tipli alan. Sonra, uzlaşı sağlandığında, bir donmuş kayda dönüşür: değerler sayfanın kendisine basılır; böylece her görüntüleyici, her cihazda, tam olarak üzerinde uzlaşılan şeyi görür. NextPDF, birincisini kurar ve ikincisini üretir; tek bir bilinçli güvenceyle — değerleri yol boyunca sessizce atmaz.

Bunun önemi nedir

“Ne doldurdum” ile “siz ne görüyorsunuz” arasındaki boşluk, formların ters gittiği yerdir.

Doldurulabilir bir alan, teknik olarak, sayfanın üzerine çizilen küçük etkileşimli bir widget’tır. Farklı görüntüleyiciler onu farklı oluşturabilir. Bazıları kaydedilmiş bir değeri onurlandırır, bazıları görünümü sizde olmayan bir fonttan yeniden üretir, bazıları bir okuyucunun onu yeniden düzenlemesine izin verir. İşbirlikçilerin düzenlemeye devam etmesini istediğiniz bir taslak için, amaç budur. Üzerinde uzlaşılanın imzalı kopyası için ise bir yükümlülüktür: kayıt, hangi uygulamanın onu açtığına bağlı olmamalı ve sonradan düzenlenebilir olmamalıdır.

Düzleştirme bu boşluğu kapatır. Her alanın güncel değerini alır ve onu sayfaya sıradan, değiştirilemez grafikler olarak basar — bir başlık ya da bir logo ile aynı türden içerik. Bundan sonra düzenlenecek bir alan ya da yeniden üretilecek bir görünüm yoktur. Belge tek bir şeyi, aynı şeyi, her yerde gösterir.

Kısa açıklama

Bir AcroForm, belgenin etkileşimli formudur: katalogda bildirilen tipli alanlardan oluşan bir ağaç (Spec: ISO 32000-2, §12.7).
Her alan, bir widget açıklaması ile görünür kılınır — tıkladığınız ya da yazdığınız sayfa üzerindeki dikdörtgen (Spec: ISO 32000-2, §12.5).
NextPDF, desteklenen her imza-dışı form denetimi için tipli oluşturucular sunar — metin, onay kutusu, radyo, liste kutusu ve birleşik kutu (seçim) ve düğme — artı bunları gerçek PDF nesneleri olarak yazan bir alan yöneticisi.
Düzleştirme, her alanın değerini sayfa içerik akışına oluşturur ve artık gereksiz olan etkileşimli formu kaldırır; geriye donmuş bir kayıt bırakır.
Hiç sayfası olmayan bir belgeyi düzleştirmek isterseniz, NextPDF alan değerlerinizi sessizce yok etmez. Formu korur, sizi uyarır ve bir sayfa eklemenize ve doğru biçimde düzleştirmenize olanak tanır.

NextPDF’nin yaklaşımı

Zihinsel model iki katmandır. Alan veridir: bir ad, bir tip, bir değer ve bir dizi bayrak. Widget resimdir: belirli bir sayfada, bir görüntüleyicinin alanla etkileşmesine olanak tanıyan bir dikdörtgen (Spec: ISO 32000-2, §12.5). Bir alan, hatta birkaç widget aracılığıyla yüzeye çıkabilir — bir radyo grubunun tam olarak çalışma biçimi budur; tek bir altta yatan değere bağlanmış birkaç sayfa üzeri seçim.

NextPDF, her alan tipine kendi tipli oluşturucusunu verir; böylece asla elle ham bir sözlük kurmazsınız. Tip, PDF açısından doğru ayrıntıları sizin yerinize taşır. Bir onay kutusu, bir radyo düğmesi ve bir basma düğmesi, spec’te aynı altta yatan form tipini paylaşır ve birbirlerinden bayraklarıyla ayrılır; motor, o bayrakları sizin seçtiğiniz tipten ayarlar, hangi bitin “radyo” anlamına geldiğini hatırlamanızı istemek yerine. Bir liste kutusu ve bir birleşik kutu, ikisi de seçim alanıdır; yine, oluşturucu doğru kodlamayı seçer. Alan tipini bir kez, sözcüklerle belirtirsiniz ve byte’lar onu izler.

Düzleştirme ikinci yarıdır. Düzleştirici, widget açıklamalarını sahibi olan sayfaya göre gruplar, her widget’ın yerleşimi için o sayfadaki dikdörtgenini kullanır, sonra her değeri küçük bir dizi içerik-akışı işleci olarak oluşturur — bir renk ayarla, bir metin konumu ayarla, glifleri çiz — ve onu o sayfanın mevcut içeriğine ekler (Spec: ISO 32000-2, §8.4). Değer, canlı bir alan olmaktan çıkar ve basılı mürekkep olur. Form artık hiçbir etkileşimli alan taşımadığı için motor, ardından AcroForm girdisini kaldırır: etkileşimli olunacak bir şey kalmamıştır.

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.

Pratik örnek

Küçük, temsili bir form: birkaç tipli alan kurun, sonra onu donmuş bir kayda düzleştirin.

<?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() öncesinde bu, doldurulabilir bir formdur. Sonrasında, aynı değerler sayfaya basılır ve değiştirilecek bir alan kalmaz. Alan tipini, oluşturucu yöntemini seçerek belirlersiniz — textField, checkBox, comboBox — böylece yanlış bir tip, gevşek bir dizge olarak kodlanamaz: bir yazım hatası, var olmayan bir yönteme yapılan bir çağrıdır ve herhangi bir alan yazılmadan önce, sessizce yanlış bir alan olarak değil, yakalanır. Bu, motorun geri kalanının benimsediği aynı tahmin-etmeyi-reddet duruşudur; bkz. tahmin etmeyi reddeden bir API.

Yaygın yanlış kanı

Tuzak, bir alanı doldurmanın onu dondurduğuna inanmaktır. Dondurmaz. Doldurulmuş bir alan, yetkin bir görüntüleyicinin düzenleyebileceği canlı bir değeri ve bazı görüntüleyicilerin yeniden üreteceği bir görünümü hâlâ taşır. “Değeri ayarladım” ve “belge artık sabit bir kayıt” iki farklı durumdur. Yalnızca düzleştirme birinden diğerine geçer; çünkü yalnızca düzleştirme, değeri artık bir alan gibi davranmayan sayfa grafiklerine çevirir.

Ayna görüntüsü hatası, hâlâ üzerinde girdi toplamanız gereken bir taslağı düzleştirmektir. Bir kez düzleştirildiğinde, alanlar gitmiştir — bütün amaç budur — bu yüzden hâlâ dolaştırdığınızı değil, son hâli olmasını istediğiniz kopyayı düzleştirin.

Sınırlar ve hudutlar

NextPDF’nin form desteği tam çekirdektir: yaygın etkileşimli alan denetimleri için tipli oluşturucular, bir form düzleştiricisi ve alanları gerçek PDF nesneleri olarak yazan bir alan yöneticisi. Bu sayfa o çekirdek yüzeyini açıklar.

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

Düzleştirme, tasarım gereği tek yönlüdür. Etkileşimli formu kaldırır ki kayıt sabit olsun; bir “geçici kilitle” geçişi değildir ve basılı grafiklerden düzenlenebilir alanları yeniden türeten bir düzleştirme-geri-alma yoktur. İnsanların düzenlemeye devam edebileceği bir kopyaya ihtiyacınız varsa, düzleştirilmemiş formu saklayın ve bir kopyayı düzleştirin.

Düzleştirme ayrıca bir imza da değildir. Bir belgeyi sıradan-görüntüleyici anlamında düzenlenemez kılar, ama onu kimin ürettiğini ya da o günden beri değişmediğini kriptografik olarak kanıtlamaz. Kayıt, üzerinde uzlaşılan kaydın kanıtlanabilir biçimde o olması gerektiğinde, düzleştirin ve sonra imzalayın; bkz. imzalar bir PDF’de nasıl oturur.

Son olarak, etiketli, erişilebilir bir form, düzleştirilmiş bir formdan ayrı bir meseledir. Doldurulabilir sürüm yardımcı teknolojiyle kullanılabilir olmalıysa, alanların hâlâ etkileşimliyken erişilebilir adlara ve yapıya ihtiyacı vardır; bkz. bir PDF’yi erişilebilir kılan nedir.

İlgili belgeler

Bir PDF’yi erişilebilir kılan nedir — doldurulabilir aşama için etiketli form alanları ve erişilebilir adlar.
Tahmin etmeyi reddeden bir API — alan tipinin neden motorun yorumlaması gereken bir dizge değil, tipli bir enum olduğu.
Bir PDF dosyasının anatomisi — bir formun üzerine kurulduğu kataloğun, sayfaların ve açıklamaların gerçekte nerede yaşadığı.
İmzalar bir PDF’de nasıl oturur — bir donmuş kaydı, üzerinde uzlaşılan kayıt olduğunu kanıtlanabilir biçimde nasıl yaparsınız.

Sözlük

AcroForm — bir PDF’nin etkileşimli formu: belge kataloğunda bildirilen ve dosyayı doldurulabilir kılan tipli alanlar ağacı (Spec: ISO 32000-2, §12.7).
Alan (field) — bir form denetiminin veri tarafı: bir ad, bir tip, bir değer ve bayraklar. Sayfada nasıl göründüğünden bağımsızdır.
Widget açıklaması (widget annotation) — bir görüntüleyicinin bir alanla etkileştiği, sayfa üzerindeki görünür, tıklanabilir dikdörtgen (Spec: ISO 32000-2, §12.5). Bir alanın birkaç tanesi olabilir.
Seçim alanı (choice field) — bir dizi seçenek sunan bir alan: bir liste kutusu onları açık gösterir, bir birleşik kutu açılır bir liste gösterir. İkisi de aynı PDF alan tipidir.
Düzleştirmek (flatten) — her alanın güncel değerini sayfaya değiştirilemez grafikler olarak oluşturmak ve etkileşimli formu kaldırmak; bir donmuş kayıt üretir.
Donmuş kayıt (frozen record) — düzleştirilmiş bir belge: her görüntüleyicide tek bir sabit şeyi gösterir ve düzenlenecek hiçbir alanı kalmamıştır.