PDF formu oluşturma ve önceden doldurma

Bir bakışta

AcroForm, PDF’in içindeki etkileşimli formdur. Bu tarifte bir AcroForm oluşturur ve alanlarını başlangıç değerleriyle önceden doldurursunuz. Core HasFormFields trait’i bir form yazma API’sidir: her alanı oluşturur ve değerini aynı çağrıda geçirirsiniz. Metin alanları için default, seçim alanları için selected, onay kutuları için checked bağımsız değişkenini kullanın. PDF, alanları önceden doldurulmuş şekilde açılır ve uyumlu bir okuyucuda düzenlenebilir kalır. Dosyayı açan herkes yine de bu değerleri değiştirebilir. Bu tarif examples/30-form-fields.php dosyasını temel alır.

Kapsam sınırı. Core, belgeyi oluştururken form alanlarını oluşturur ve doldurur. Üçüncü taraf bir PDF’de zaten var olan bir formu okumaz veya ona değer eşlemesi uygulamaz. Burada “doldurma”, formu değerlerle yazmak anlamına gelir; harici bir PDF’yi yükleyip doldurmak anlamına gelmez. Harici bir formu çift yönlü işlemek Premium ve sunucu tarafı bir özelliktir; Core’un ortak API’si değildir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bir AcroForm alanı, geçerli değerini alan sözlüğündeki V girdisinde saklar (ISO 32000-2 §12.7). Ayrıca, form sıfırlama eylemi çalıştırıldığında alanın döneceği isteğe bağlı varsayılan değeri DV içinde de saklayabilir. NextPDF, V değerini her alan oluşturucusuna geçirdiğiniz değere göre ayarlar. Metin işleme için varsayılan görünüm dizesi (DA) kullanılır.

Profil structural olur; çünkü belge bir fragman /ID dizisi içerir. Sonradan işleme adımı, karşılaştırmadan önce değişken olan bu tanımlayıcıyı normalleştirir.

API yüzeyi

NextPDF\Core\Concerns\HasFormFields (Document içine dahil edilir):

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

Önceden doldurma değerleri default, checked ve selected bağımsız değişkenleriyle verilir.

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

<?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";

Kod örneği — üretim

Aşağıdaki tam örnek, birkaç bölümden oluşan bir kayıt formu olan examples/30-form-fields.php dosyasını yansıtır. Çıktıyı, çalıştırma çerçevesi için NEXTPDF_COOKBOOK_OUTPUT ile belirtilen konuma yazar.

<?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";

Beklenen çıktı:

Wrote pre-filled registration form

PDF’yi açtığınızda her alan zaten doldurulmuş olur ve düzenlenebilir kalır.

Sınır durumları ve püf noktaları

Alan adları benzersiz olmalıdır. Aynı adı paylaşan iki alan, uyumlu okuyucularda ortak bir değere sahip tek bir mantıksal alan olur. Bu, bağlantılı alanlar için yararlıdır; aksi halde beklenmedik sonuç doğurur.
Radyo grubu mantığı. radioButton(), her seçeneği bir group ile ilişkilendirir. Seçili seçenek, value değerinin grubun değeriyle eşleştiği seçenektir. Her grupta aynı anda yalnızca bir seçenek seçili olur.
maxLen bir ipucudur. Bir maxLen seçeneği, uyumlu okuyucularda giriş uzunluğunu sınırlar. Önceden doldurularak saklanan değeri sınırlamaz.
API’de koordinatlar sol üst köşeye göredir. Trait, koordinatları sizin için PDF’nin sol alt orijinine dönüştürür; bu nedenle örnekte gösterildiği gibi sol üst koordinatları geçirin.
Harici PDF doldurma desteklenmez. Hiçbir Core yöntemi, mevcut üçüncü taraf bir formu yükleyip bir değer eşlemesi uygulamaz. Yukarıdaki kapsam sınırına bakın.

Performans

Form yazma işlemi, alan sayısıyla doğrusal olarak ölçeklenir. Her alan bir widget açıklaması ve bir görünüm ekler. Birkaç yüz alan bile 1500 ms / 64 MB bütçesinin oldukça içinde kalır.

Güvenlik notları

Önceden doldurulmuş değerler alan sözlüğüne olduğu gibi yazılır. Güvenilmeyen girdiden gelen her değeri, dağıtacağınız bir belgeye yerleştirmeden önce kaçışlayın veya doğrulayın. Önceden doldurulmuş form korumalı değildir: PDF’yi açabilen herkes değerleri okuyabilir ve değiştirebilir. Form içeriği hassassa, bu tarifi İzinlerle şifreleme ile birlikte kullanın ve oradaki, okuyucu işbirliğine dayandığına ilişkin uyarıyı dikkate alın.

Uygunluk

İfade	Belirtim	Madde
Alanın geçerli değeri, alan sözlüğünün `V` girdisinde saklanır.	ISO 32000-2	§12.7
Varsayılan değer `DV` girdisinde saklanır ve form sıfırlamasında geri yüklenir.	ISO 32000-2	§12.7
Alan metninin biçimlendirilmesi, varsayılan görünüm dizesi `DA`’yı kullanır.	ISO 32000-2	§12.7

NextPDF, alıntılanan maddelerde açıklanan AcroForm yapısını üretir. Tam ISO 32000-2 uygunluğu iddia etmez.