Form: bidang AcroForm interaktif dan perataan

Sekilas

Modul Form membuat formulir interaktif dalam dokumen Portable Document Format (PDF). Modul ini membangun bidang teks, kotak centang, radio, pilihan (daftar/kombo), tombol, dan tanda tangan, menyusunnya dalam hierarki parent/child, menuliskannya sebagai objek PDF dengan aliran tampilan, dan dapat meratakan formulir menjadi konten halaman statis.

Pemasangan

composer require nextpdf/core:^3

Ikhtisar konseptual

Formulir PDF interaktif berupa AcroForm: hierarki bidang di tingkat dokumen yang bidang terminalnya dipasangkan dengan anotasi widget pada halaman. ISO 32000-2 §12.7 mendefinisikan formulir tersebut, kamus bidangnya, akar AcroForm, dan hierarki bidangnya. Modul ini merepresentasikan struktur tersebut di dalam mesin.

FormFieldManager adalah permukaan API utama. Modul ini menyediakan pembangun textField(), checkBox(), radioButton(), button(), dan signatureField(), melacak bidang, dan menserialisasinya dengan writeFields(). Modul ini memancarkan satu aliran tampilan Form XObject untuk setiap widget (/Subtype /Form, /BBox), sebagaimana disyaratkan oleh §8.10. FormField merupakan objek nilai bidang. FormFieldDictionaryBuilder mengonversi bidang menjadi kamus PDF-nya dan menerapkan entri khusus tipe serta bit flag untuk bidang teks, kotak centang, pilihan, dan tombol. Manajer dan FormField berstatus @since 1.0.0. Pembangun kamus berstatus @since 1.1.0.

FormFieldHierarchy memodelkan pohon bidang parent/child dengan addChild(), getRootFieldNames(), getChildren(), getParent(), dan visitor walkDepthFirst(). Nama bidang yang sepenuhnya memenuhi syarat merupakan jalur bertitik melalui hierarki ini, sesuai dengan model bidang bersarang dalam §12.7.

FormFlattener merender formulir menjadi konten halaman statis. flatten() mengembalikan FlattenResult, sehingga Anda dapat membekukan formulir yang telah diisi untuk pengarsipan. FieldMDP dan FieldMdpAction memodelkan transformasi penguncian bidang. Dokumen yang ditandatangani dapat mengunci sekumpulan bidang bernama agar tidak dapat dimodifikasi lebih lanjut. FieldMdpAction menentukan cakupan penguncian, dan requiresFieldList() menunjukkan kapan daftar bidang eksplisit menjadi wajib. FieldMDP berstatus @since 2.0.0.

Permukaan API

Kelas	Anggota utama	Peran
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Pembangun bidang + serializer (@since 1.0.0)
FormField	objek nilai bidang	Satu bidang AcroForm (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Pembangun bidang-ke-kamus (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Pohon bidang parent/child (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Meratakan formulir menjadi konten statis (@since 1.0.0)
FieldMDP	toTransformParams()	Transformasi penguncian bidang (FieldMDP) (@since 2.0.0)
FieldMdpAction (enum)	requiresFieldList()	Cakupan penguncian bidang (@since 2.0.0)

Jalankan composer docs:generate-api-php -- --module=Form untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Sumber: 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.

Contoh kode — Produksi

Buat satu set bidang untuk dokumen yang ditandatangani, lalu kunci bidang yang ditandatangani dengan FieldMDP.

<?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.

Kasus tepi & jebakan

• Nama bidang merupakan jalur bertitik yang sepenuhnya memenuhi syarat melalui FormFieldHierarchy. Dalam penampil, dua bidang terminal dengan nama yang sepenuhnya memenuhi syarat yang sama adalah bidang logis yang sama. Anda bertanggung jawab atas keunikannya.
• FieldMdpAction::requiresFieldList() memberi tahu Anda kapan daftar bidang menjadi wajib. Aksi Include/Exclude tanpa daftar yang disyaratkan akan menghasilkan penguncian yang cacat; periksa flag-nya.
• FormFlattener::flatten() sengaja menghapus interaktivitas. Hasilnya adalah konten statis. Simpan sumber interaktifnya jika Anda membutuhkannya nanti.
• Aliran tampilan dipancarkan per widget. Bidang tanpa tampilan dapat dirender secara tidak konsisten di berbagai penampil; biarkan manajer menghasilkan tampilannya, bukan menghilangkannya.
• signatureField() hanya membuat placeholder bidang. Tanda tangan yang sebenarnya dihasilkan oleh lapisan Security/penandatanganan; bukan oleh modul ini.

Performa

Pembuatan dan serialisasi bidang berkompleksitas O(n) terhadap jumlah bidang, ditambah satu aliran tampilan Form XObject per widget. Biaya perataan berskala dengan konten yang dirender, bukan dengan jumlah bidang. Beban kerja referensi standar tetap berada dalam anggaran 1500 ms wall / 64 MB peak. Profil reproduktibilitasnya adalah structural: nomor objek dan /ID trailer bervariasi antarproses. Dua dokumen dengan formulir yang sama setara secara struktural, tetapi tidak identik pada tingkat byte.

Catatan keamanan

Nilai bidang formulir adalah masukan pengguna. Modul ini melakukan escaping pada nilai string untuk serialisasi PDF dengan PdfStringEscaper, sehingga nilai bidang tidak dapat keluar dari string PDF-nya dan menyuntikkan struktur. Ketika formulir dienkripsi, enkripsi AES-256 dokumen mencakup konten bidang. FieldMDP adalah kontrol keamanan: ia mengunci bidang bernama agar tidak dapat dimodifikasi setelah penandatanganan. Penguncian bidang yang tidak cocok dengan set bidang yang ditandatangani akan melemahkan kontrol tersebut; tetapkan cakupan penguncian secara saksama. Perlakukan setiap nilai yang diekstraksi dari formulir yang telah diisi sebagai masukan yang tidak tepercaya. Lihat model keamanan mesin di /modules/core/security/.

Konformansi

Struktur formulir yang dipancarkan modul ini mengikuti model formulir interaktif dalam ISO 32000-2 §12.7: akar AcroForm, kamus bidang, dan hierarki bidang dokumen. Tampilan per-widget dipancarkan sebagai Form XObject sesuai §8.10 dan didokumentasikan secara inline di src/Form/. tests/Unit/Form/ menguji fakta implementasi ini. Ini bukan pernyataan konformansi PDF 2.0 secara menyeluruh. Konformansi dokumen penuh divalidasi oleh suite oracle dan golden di /modules/core/conformance/.

Lihat juga

• Modul Navigation — anotasi widget yang dipasangkan dengan bidang.
• Modul Security — model kepercayaan penandatanganan dan FieldMDP.
• Modul Accessibility — penandaan bidang formulir untuk PDF/UA.
• Ikhtisar konformansi