Form: etkileşimli AcroForm alanları ve düzleştirme

Bir bakışta

Form modülü, Portable Document Format (PDF) belgeleri için etkileşimli formlar oluşturur. Metin, onay kutusu, radyo, seçim (liste/açılır), düğme ve imza alanlarını oluşturur; bunları bir parent/child hiyerarşisinde düzenler; görünüm akışlarıyla birlikte PDF nesneleri olarak yazar ve formu statik sayfa içeriğine düzleştirebilir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Etkileşimli bir PDF formu bir AcroForm’dur: uç alanları sayfalardaki widget açıklamalarıyla eşleşen, belge düzeyinde bir alan hiyerarşisidir. ISO 32000-2 §12.7, bu formu, alan sözlüklerini, AcroForm kökünü ve alan hiyerarşisini tanımlar. Bu modül, bu yapıları motorda uygular.

FormFieldManager birincil API yüzeyidir. textField(), checkBox(), radioButton(), button() ve signatureField() oluşturucularını sunar, alanları izler ve bunları writeFields() ile serileştirir. §8.10’un gerektirdiği üzere, her widget için bir Form XObject görünüm akışı yayar (/Subtype /Form, /BBox). FormField bir alan değer nesnesidir. FormFieldDictionaryBuilder bir alanı PDF sözlüğüne dönüştürür ve metin, onay kutusu, seçim ve düğme alanları için türe özgü girdileri ve bayrak bitlerini uygular. Yönetici ve FormField @since 1.0.0 sürümünden beri mevcuttur. Sözlük oluşturucu @since 1.1.0 sürümünden beri mevcuttur.

FormFieldHierarchy, addChild(), getRootFieldNames(), getChildren(), getParent() ve bir walkDepthFirst() ziyaretçisiyle parent/child alan ağacını modeller. Tam nitelikli bir alan adı, bu hiyerarşi boyunca uzanan ve §12.7’deki iç içe alan modeline karşılık gelen noktalı yoldur.

FormFlattener formu işleyerek statik sayfa içeriğine dönüştürür. flatten() bir FlattenResult döndürür; böylece doldurulmuş bir formu arşivleme için dondurabilirsiniz. FieldMDP ve FieldMdpAction alan kilidi dönüşümünü modeller. İmzalanmış bir belge, adlandırılmış bir alan kümesini ileride değiştirilmeye karşı kilitleyebilir. FieldMdpAction kilit kapsamını numaralandırır ve requiresFieldList() açıkça belirtilmiş bir alan listesinin ne zaman zorunlu olduğunu gösterir. FieldMDP @since 2.0.0 sürümünden beri mevcuttur.

API yüzeyi

Sınıf	Başlıca üyeler	Rol
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Alan oluşturucu + serileştirici (@since 1.0.0)
FormField	alan değer nesnesi	Tek bir AcroForm alanı (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Alanı sözlüğe dönüştüren oluşturucu (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Parent/child alan ağacı (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Formu statik içeriğe düzleştirir (@since 1.0.0)
FieldMDP	toTransformParams()	Alan kilidi (FieldMDP) dönüşümü (@since 2.0.0)
FieldMdpAction (enum)	requiresFieldList()	Alan kilidi kapsamı (@since 2.0.0)

Tam PHPDoc tablosunu üretmek için composer docs:generate-api-php -- --module=Form komutunu çalıştırın.

Kod örneği — hızlı başlangıç

Kaynak: examples/30-form-fields.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();

$form->textField(name: 'applicant_name', x: 50, y: 700, w: 200, h: 18);
$form->checkBox(name: 'agree_terms', x: 50, y: 660, size: 12);
$form->radioButton(name: 'plan', x: 50, y: 620, size: 12 /* + option set */);

// The Writer invokes $form->writeFields(...) during document serialization.

Kod örneği — üretim

İmzalı bir belge için bir alan kümesi oluşturun, ardından imzalanan alanları FieldMDP ile kilitleyin.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FieldMDP;
use NextPDF\Form\FieldMdpAction;
use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();
$form->textField(name: 'contract_value', x: 50, y: 700, w: 160, h: 18);
$form->signatureField(name: 'approver_sig', x: 50, y: 600, w: 200, h: 60);

// Lock only the named fields after signing.
$lock = new FieldMDP(
    action: FieldMdpAction::Include,
    fields: ['contract_value'],
);

$transformParams = $lock->toTransformParams();
// $transformParams is attached to the signature's transform method by the signing layer.

Uç durumlar ve dikkat edilmesi gerekenler

• Bir alan adı, FormFieldHierarchy boyunca uzanan tam nitelikli noktalı bir yoldur. Bir görüntüleyicide aynı tam nitelikli ada sahip iki uç alan aynı mantıksal alandır. Benzersizliği sağlamak sizin sorumluluğunuzdadır.
• FieldMdpAction::requiresFieldList() bir alan listesinin ne zaman zorunlu olduğunu bildirir. Gerekli liste yoksa bir Include/Exclude eylemi hatalı biçimlendirilmiş bir kilit oluşturur; bayrağı denetleyin.
• FormFlattener::flatten() etkileşimselliği bilinçli olarak kaldırır. Sonuç statik içeriktir. Etkileşimli kaynağa daha sonra ihtiyacınız olursa onu saklayın.
• Görünüm akışları widget başına üretilir. Görünümü olmayan bir alan, görüntüleyiciler arasında tutarsız biçimde işlenebilir; görünümü atlamak yerine yöneticinin onu oluşturmasına izin verin.
• signatureField() yalnızca alan yer tutucusunu oluşturur. Gerçek imzayı Security/imzalama katmanı üretir; bu modül imza üretmez.

Performans

Alan oluşturma ve serileştirme, alan sayısına göre O(n) karmaşıklıktadır; ayrıca widget başına bir Form XObject görünüm akışı eklenir. Düzleştirme maliyeti, alan sayısına değil, işlenen içeriğe göre ölçeklenir. Varsayılan referans iş yükü, 1500 ms duvar saati / 64 MB tepe bellek bütçesi içinde kalır. Yeniden üretilebilirlik profili structural türündedir: nesne numaraları ve fragman (trailer) /ID değeri çalıştırmalar arasında değişir. Aynı forma sahip iki belge yapısal olarak eşittir, ancak bayt düzeyinde aynı değildir.

Güvenlik notları

Form alanı değerleri kullanıcı girdisidir. Modül, PDF serileştirmesi için dize değerlerine PdfStringEscaper ile kaçış uygular; böylece bir alan değeri kendi PDF dizesinden çıkıp yapı enjekte edemez. Bir form şifrelendiğinde, belgenin AES-256 şifrelemesi alan içeriğini de kapsar. FieldMDP bir güvenlik kontrolüdür: adlandırılmış alanları imza sonrası değişikliğe karşı kilitler. İmzalanan alan kümesiyle eşleşmeyen bir alan kilidi bu kontrolü zayıflatır; kilit kapsamını bilinçli olarak ayarlayın. Doldurulmuş bir formdan elde edilen her değeri güvenilmeyen girdi olarak ele alın. Motorun güvenlik modeli için /modules/core/security/ sayfasına bakın.

Uyumluluk

Bu modülün oluşturduğu form yapıları, ISO 32000-2 §12.7’deki etkileşimli form modelini izler: AcroForm kökü, alan sözlükleri ve belge alan hiyerarşisi. Widget başına görünümler §8.10 uyarınca Form XObject olarak üretilir ve src/Form/ içinde satır içi olarak belgelenir. tests/Unit/Form/ bu uygulama davranışlarını sınar. Bunlar uçtan uca PDF 2.0 uyumluluğunun bir beyanı değildir. Tam belge uyumluluğu, /modules/core/conformance/ içindeki oracle ve golden setleriyle doğrulanır.

Ayrıca bakın

• Navigation modülü — alanlara karşılık gelen widget açıklamaları.
• Security modülü — imzalama ve FieldMDP güvenlik modeli.
• Accessibility modülü — PDF/UA için form alanlarının etiketlenmesi.
• Uyumluluk genel bakışı