Tạo và điền sẵn biểu mẫu PDF

Tổng quan nhanh

AcroForm là biểu mẫu tương tác bên trong PDF. Trong công thức này, bạn tạo một biểu mẫu và điền sẵn các trường bằng giá trị ban đầu. Trait HasFormFields của Core là API để soạn biểu mẫu: bạn tạo từng trường và cung cấp giá trị của trường đó trong cùng một lệnh gọi. Dùng đối số default cho trường văn bản, selected cho trường lựa chọn, và checked cho hộp kiểm. Khi PDF được mở, các trường đã được điền sẵn và vẫn có thể chỉnh sửa trong trình đọc tuân thủ. Bất kỳ ai mở tệp đều vẫn có thể thay đổi chúng. Công thức này bám sát examples/30-form-fields.php.

Ranh giới phạm vi. Core tạo và điền các trường biểu mẫu khi nó dựng nên tài liệu. Core không đọc biểu mẫu có sẵn trong PDF của bên thứ ba hay gộp một bản đồ giá trị vào đó. Ở đây, “điền” nghĩa là soạn biểu mẫu kèm giá trị, chứ không phải tải và điền vào một PDF bên ngoài. Việc xử lý khứ hồi một biểu mẫu bên ngoài là một khả năng của Premium và server, không phải API công khai của Core.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Trường AcroForm lưu giá trị hiện tại của nó trong mục V của từ điển trường (ISO 32000-2 §12.7). Nó cũng có thể lưu giá trị mặc định tùy chọn trong DV; đây là giá trị mà trường sẽ quay về khi thao tác đặt lại biểu mẫu được thực hiện. NextPDF đặt V theo giá trị bạn truyền vào mỗi hàm khởi tạo trường. Văn bản được kết xuất bằng chuỗi giao diện mặc định (DA).

Hồ sơ là structural vì tài liệu có một mảng /ID trong trailer. Bước xử lý sau sẽ chuẩn hóa định danh có thể thay đổi đó trước khi so sánh.

Bề mặt API

NextPDF\Core\Concerns\HasFormFields (được trộn vào 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

Các đối số default, checked, và selected chứa giá trị được điền sẵn.

Mẫu mã — bắt đầu nhanh

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

Mẫu mã — môi trường sản xuất

Ví dụ đầy đủ bên dưới bám sát examples/30-form-fields.php: một biểu mẫu đăng ký gồm nhiều phần. Ví dụ này ghi vào NEXTPDF_COOKBOOK_OUTPUT cho bộ kiểm thử.

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

Kết quả mong đợi:

Wrote pre-filled registration form

Khi mở PDF, mọi trường đều đã được điền sẵn và vẫn có thể chỉnh sửa.

Trường hợp biên & lưu ý dễ vấp

Tên trường phải là duy nhất. Trong các trình đọc tuân thủ, hai trường trùng tên sẽ trở thành một trường logic dùng chung giá trị. Điều đó hữu ích cho các trường được liên kết; nếu không chủ ý, đây dễ là một bất ngờ.
Ngữ nghĩa của nhóm radio. radioButton() gắn mỗi tùy chọn vào một group. Tùy chọn được chọn là tùy chọn có value khớp với giá trị của nhóm. Mỗi nhóm chỉ có một tùy chọn được bật ở mỗi thời điểm.
maxLen là một gợi ý. Tùy chọn maxLen giới hạn độ dài nhập liệu trong các trình đọc tuân thủ. Nó không giới hạn giá trị được lưu khi bạn điền sẵn.
Tọa độ trong API tính từ góc trên bên trái. Trait sẽ giúp bạn chuyển sang hệ gốc tọa độ ở góc dưới bên trái của PDF, nên hãy truyền tọa độ góc trên bên trái như trong ví dụ.
Không điền vào PDF bên ngoài. Không có phương thức Core nào tải biểu mẫu có sẵn của bên thứ ba rồi áp dụng một bản đồ giá trị. Xem phần ranh giới phạm vi ở trên.

Hiệu năng

Chi phí soạn biểu mẫu tăng tuyến tính theo số lượng trường. Mỗi trường thêm một chú thích widget và một giao diện. Vài trăm trường vẫn nằm trong ngân sách 1500 ms / 64 MB.

Ghi chú bảo mật

Các giá trị điền sẵn được ghi nguyên văn vào từ điển trường. Hãy escape hoặc xác thực mọi giá trị từ đầu vào không đáng tin cậy trước khi đặt vào tài liệu bạn phân phối. Biểu mẫu điền sẵn không tự được bảo vệ: bất kỳ ai mở được PDF đều có thể đọc và thay đổi các giá trị. Nếu nội dung biểu mẫu nhạy cảm, hãy kết hợp công thức này với Mã hóa kèm quyền, và lưu ý cảnh báo tại đó về sự phụ thuộc vào trình đọc.

Mức độ tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Giá trị hiện tại của trường được lưu trong mục `V` của từ điển trường.	ISO 32000-2	§12.7
Giá trị mặc định được lưu trong mục `DV` và được khôi phục khi đặt lại biểu mẫu.	ISO 32000-2	§12.7
Định dạng văn bản trường dùng chuỗi giao diện mặc định `DA`.	ISO 32000-2	§12.7

NextPDF phát ra cấu trúc AcroForm theo mô tả trong các điều khoản đã trích dẫn. NextPDF không tuyên bố tuân thủ đầy đủ ISO 32000-2.