Membuat dan mengisi nilai awal formulir PDF

Sekilas

AcroForm adalah formulir interaktif di dalam PDF. Dalam resep ini, Anda membuat formulir dan mengisi nilai awal pada bidang-bidangnya. Trait HasFormFields dari Core adalah API untuk menyusun formulir: Anda membuat setiap bidang sekaligus menyediakan nilainya dalam panggilan yang sama. Gunakan argumen default untuk bidang teks, selected untuk bidang pilihan, dan checked untuk kotak centang. PDF akan terbuka dengan bidang-bidang yang sudah terisi, dan bidang-bidang tersebut tetap dapat diedit di pembaca yang mematuhi standar. Siapa pun yang membuka berkas tetap dapat mengubahnya. Resep ini mengikuti examples/30-form-fields.php.

Batas cakupan. Core membuat dan mengisi bidang formulir saat menyusun dokumen. Core tidak membaca formulir yang sudah ada di PDF pihak ketiga atau menerapkan peta nilai ke dalamnya. Di sini, “isi” berarti menyusun formulir beserta nilainya, bukan memuat dan mengisi PDF eksternal. Round-trip formulir eksternal adalah kemampuan Premium dan server, bukan API publik Core.

Pemasangan

composer require nextpdf/core:^3

Gambaran konseptual

Bidang AcroForm menyimpan nilai saat ini pada entri V dari kamus bidang (ISO 32000-2 §12.7). Bidang ini juga dapat menyimpan nilai standar opsional di DV, yang menjadi nilai yang dipulihkan saat aksi reset formulir dijalankan. NextPDF menetapkan V dari nilai yang Anda berikan ke setiap konstruktor bidang. Perenderan teks menggunakan string kemunculan standar (DA).

Profilnya adalah structural karena dokumen menyertakan larik /ID pada trailer. Pasca-pemrosesan menormalkan pengidentifikasi yang berubah-ubah tersebut sebelum perbandingan.

Permukaan API

NextPDF\Core\Concerns\HasFormFields (digabungkan ke dalam Document):

textField(string $name, float $x, float $y, float $w, float $h, string $default = '', array $options = []): static
checkBox(string $name, float $x, float $y, float $size, bool $checked = false): static
radioButton(string $name, float $x, float $y, float $size, string $value, string $group): static
comboBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
listBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
button(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static

Argumen default, checked, dan selected berisi nilai isian awal.

Contoh kode — Memulai cepat

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Pre-filled Form');
$doc->addPage();

// Text field pre-filled with a value (sets the field dictionary /V entry).
$doc->textField(name: 'full_name', x: 20, y: 30, w: 90, h: 8, default: 'Ada Lovelace');

// Choice field pre-selected.
$doc->comboBox(
    name: 'country',
    x: 20, y: 45, w: 90, h: 8,
    items: ['United Kingdom', 'Taiwan', 'Japan'],
    selected: 'Taiwan',
);

// Checkbox pre-checked.
$doc->checkBox(name: 'newsletter', x: 20, y: 60, size: 5, checked: true);

$doc->save(__DIR__ . '/prefilled-form.pdf');
echo "Wrote prefilled-form.pdf\n";

Contoh kode — Produksi

Contoh lengkap di bawah ini mencerminkan examples/30-form-fields.php, yaitu formulir pendaftaran dengan beberapa bagian. Contoh ini menulis ke NEXTPDF_COOKBOOK_OUTPUT untuk harness.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Customer Registration — Pre-filled');
$doc->addPage();

$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Customer Registration Form', newLine: true);
$doc->ln(4);

$leftMargin = 15.0;
$fieldX     = 70.0;
$fieldW     = 120.0;
$fieldH     = 8.0;
$rowSpacing = 12.0;

// --- Personal information, pre-filled ---
$prefill = [
    'full_name' => 'Ada Lovelace',
    'email'     => '[email protected]',
    'phone'     => '+44 20 7946 0000',
    'company'   => 'Analytical Engines Ltd',
];

$y = 40.0;
$doc->setFont('helvetica', '', 10);
foreach ($prefill as $name => $value) {
    $doc->setXY($leftMargin, $y);
    $doc->cell(50, $fieldH, ucwords(str_replace('_', ' ', $name)) . ':');
    $doc->textField(
        name: $name,
        x: $fieldX,
        y: $y,
        w: $fieldW,
        h: $fieldH,
        default: $value,
        options: ['maxLen' => 80],
    );
    $y += $rowSpacing;
}

// --- Choice field, pre-selected ---
$y += 6;
$doc->setXY($leftMargin, $y);
$doc->cell(50, $fieldH, 'Country:');
$doc->comboBox(
    name: 'country',
    x: $fieldX,
    y: $y,
    w: $fieldW,
    h: $fieldH,
    items: ['United States', 'United Kingdom', 'Germany', 'Japan', 'Taiwan'],
    selected: 'United Kingdom',
);

// --- Checkboxes, pre-set ---
$y += $rowSpacing + 6;
$doc->setXY($leftMargin, $y);
$doc->cell(0, 7, 'Subscribe to newsletter');
$doc->checkBox(name: 'newsletter', x: $leftMargin + 70, y: $y, size: 5, checked: true);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/registration-prefilled.pdf');

echo "Wrote pre-filled registration form\n";

Keluaran yang diharapkan:

Wrote pre-filled registration form

Saat Anda membuka PDF, setiap bidang sudah terisi dan tetap bisa diedit.

Kasus tepi & jebakan

Nama bidang harus unik. Dua bidang yang berbagi nama menjadi satu bidang logis dengan nilai bersama di pembaca yang mematuhi standar. Ini berguna untuk bidang yang tertaut, tetapi bisa mengejutkan jika tidak diinginkan.
Semantik grup radio. radioButton() mengaitkan setiap opsi ke sebuah group. Opsi yang terpilih adalah opsi yang value-nya cocok dengan nilai grup. Hanya satu opsi per grup yang dapat aktif pada satu waktu.
maxLen hanyalah petunjuk. Opsi maxLen membatasi panjang masukan di pembaca yang mematuhi standar. Opsi ini tidak membatasi nilai tersimpan yang Anda isi sebagai nilai awal.
Koordinat di API menggunakan titik asal kiri-atas. Trait ini mengonversinya ke titik asal kiri-bawah PDF untuk Anda, jadi berikan koordinat kiri-atas, seperti yang ditunjukkan contoh.
Tidak ada pengisian PDF eksternal. Tidak ada metode Core yang memuat formulir pihak ketiga yang sudah ada dan menerapkan peta nilai. Lihat batas cakupan di atas.

Performa

Penyusunan formulir berskala linear terhadap jumlah bidang. Setiap bidang menambahkan satu anotasi widget dan satu kemunculan. Beberapa ratus bidang tetap jauh di bawah anggaran 1500 ms / 64 MB.

Catatan keamanan

Nilai isian awal ditulis apa adanya ke dalam kamus bidang. Lakukan escaping atau validasi terhadap setiap nilai dari masukan yang tidak tepercaya sebelum Anda menempatkannya di dokumen yang akan didistribusikan. Formulir yang terisi nilai awal tidak terlindungi: siapa pun yang dapat membuka PDF dapat membaca dan mengubah nilainya. Saat isi formulir bersifat sensitif, gabungkan resep ini dengan Enkripsi dengan izin, dan perhatikan peringatan bahwa pembaca PDF bersifat kooperatif di sana.

Kesesuaian

Pernyataan	Spesifikasi	Klausa
Nilai bidang saat ini disimpan pada entri `V` kamus bidang.	ISO 32000-2	§12.7
Nilai standar disimpan pada entri `DV` dan dipulihkan saat formulir di-reset.	ISO 32000-2	§12.7
Pemformatan teks bidang menggunakan string kemunculan standar `DA`.	ISO 32000-2	§12.7

NextPDF menghasilkan struktur AcroForm yang dijelaskan oleh klausa yang dikutip. NextPDF tidak mengklaim kesesuaian penuh dengan ISO 32000-2.