Form: trường AcroForm tương tác và làm phẳng

Tổng quan nhanh

Module Form tạo biểu mẫu tương tác trong tài liệu Portable Document Format (PDF). Module này tạo các trường text, checkbox, radio, choice (list/combo), button và chữ ký, sắp xếp chúng thành phân cấp parent/child, ghi chúng dưới dạng đối tượng PDF kèm luồng giao diện, và có thể làm phẳng biểu mẫu thành nội dung trang tĩnh.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Một biểu mẫu PDF tương tác là AcroForm: một phân cấp trường ở cấp tài liệu, trong đó các trường đầu cuối được ghép với chú thích widget trên các trang. ISO 32000-2 §12.7 định nghĩa biểu mẫu này, các từ điển trường, gốc AcroForm và phân cấp trường của nó. Module này mã hóa các cấu trúc đó để engine sử dụng.

FormFieldManager là bề mặt chính. Nó cung cấp các builder textField(), checkBox(), radioButton(), button() và signatureField(), theo dõi các trường và tuần tự hóa chúng bằng writeFields(). Nó phát ra luồng giao diện Form XObject cho mỗi widget (/Subtype /Form, /BBox), đúng như §8.10 yêu cầu. FormField là đối tượng giá trị của trường. FormFieldDictionaryBuilder chuyển đổi một trường thành từ điển PDF tương ứng, rồi áp dụng các mục và bit cờ riêng theo từng loại cho trường text, checkbox, choice và button. Manager và FormField có @since 1.0.0. Dictionary builder có @since 1.1.0.

FormFieldHierarchy mô hình hóa cây trường parent/child với addChild(), getRootFieldNames(), getChildren(), getParent() và một visitor walkDepthFirst(). Tên trường đầy đủ là đường dẫn đi qua phân cấp này, được phân tách bằng dấu chấm, khớp với mô hình trường lồng nhau trong §12.7.

FormFlattener kết xuất biểu mẫu thành nội dung trang tĩnh. flatten() trả về một FlattenResult, nhờ đó bạn có thể đóng băng một biểu mẫu đã điền để lưu trữ. FieldMDP và FieldMdpAction mô hình hóa phép biến đổi khóa trường. Một tài liệu đã ký có thể khóa một tập hợp trường được đặt tên để ngăn mọi thay đổi tiếp theo. FieldMdpAction liệt kê phạm vi khóa, còn requiresFieldList() cho biết khi nào bắt buộc phải có danh sách trường tường minh. FieldMDP có @since 2.0.0.

Bề mặt API

Lớp	Thành viên chính	Vai trò
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Builder + bộ tuần tự hóa các trường (@since 1.0.0)
FormField	đối tượng giá trị của trường	Một trường AcroForm (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Builder chuyển trường thành từ điển (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Cây trường parent/child (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Làm phẳng biểu mẫu thành nội dung trang tĩnh (@since 1.0.0)
FieldMDP	toTransformParams()	Phép biến đổi khóa trường (FieldMDP) (@since 2.0.0)
FieldMdpAction (enum)	requiresFieldList()	Phạm vi khóa trường (@since 2.0.0)

Chạy composer docs:generate-api-php -- --module=Form để tạo bảng PHPDoc đầy đủ.

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

Nguồn: 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.

Mẫu mã — sản xuất

Tạo một tập trường cho tài liệu có chữ ký, rồi khóa các trường đã được ký bằng 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.

Các trường hợp biên & điểm cần lưu ý

• Tên trường là đường dẫn đầy đủ đi qua FormFieldHierarchy, được phân tách bằng dấu chấm. Trong trình xem, hai trường đầu cuối có cùng tên đầy đủ chính là cùng một trường logic. Bạn chịu trách nhiệm đảm bảo tính duy nhất.
• FieldMdpAction::requiresFieldList() cho bạn biết khi nào danh sách trường là bắt buộc. Một hành động Include/Exclude thiếu danh sách bắt buộc sẽ tạo ra khóa sai định dạng; hãy kiểm tra cờ này.
• FormFlattener::flatten() cố ý loại bỏ tính tương tác. Kết quả là nội dung tĩnh. Hãy giữ lại bản nguồn còn tương tác nếu sau này bạn cần đến.
• Luồng giao diện được phát ra theo từng widget. Một trường không có giao diện có thể được kết xuất không nhất quán giữa các trình xem; hãy để manager tạo giao diện thay vì bỏ qua.
• signatureField() chỉ tạo trình giữ chỗ của trường. Lớp Security/signing mới là nơi tạo chữ ký thực tế; module này thì không.

Hiệu năng

Việc tạo và tuần tự hóa trường là O(n) theo số lượng trường, cộng thêm một luồng giao diện Form XObject cho mỗi widget. Chi phí làm phẳng tỷ lệ với nội dung được kết xuất, không phải với số lượng trường. Khối lượng công việc tham chiếu mặc định nằm trong ngân sách 1500 ms thời gian thực / 64 MB đỉnh. Hồ sơ khả năng tái lập là structural: số đối tượng và /ID của trailer thay đổi giữa các lần chạy. Hai tài liệu có cùng biểu mẫu thì tương đương về mặt cấu trúc nhưng không giống hệt nhau ở cấp byte.

Lưu ý bảo mật

Giá trị của trường biểu mẫu là dữ liệu do người dùng nhập. Module này thoát chuỗi giá trị khi tuần tự hóa PDF bằng PdfStringEscaper, vì vậy giá trị trường không thể thoát khỏi chuỗi PDF tương ứng để chèn cấu trúc. Khi một biểu mẫu được mã hóa, mã hóa AES-256 của tài liệu bao phủ cả nội dung trường. FieldMDP là một biện pháp kiểm soát bảo mật: nó khóa các trường được đặt tên để chống thay đổi sau khi ký. Một khóa trường không khớp với tập trường đã ký sẽ làm suy yếu biện pháp kiểm soát đó; hãy đặt phạm vi khóa một cách có chủ đích. Hãy xem mọi giá trị trích xuất từ một biểu mẫu đã điền là dữ liệu không đáng tin cậy. Xem mô hình bảo mật của engine trong /modules/core/security/.

Tuân thủ

Các cấu trúc biểu mẫu mà module này phát ra tuân theo mô hình biểu mẫu tương tác trong ISO 32000-2 §12.7: gốc AcroForm, các từ điển trường và phân cấp trường của tài liệu. Giao diện theo từng widget được phát ra dưới dạng Form XObject theo §8.10 và được ghi chú nội tuyến trong src/Form/. tests/Unit/Form/ kiểm thử các chi tiết triển khai này. Chúng không phải là tuyên bố về tính tuân thủ PDF 2.0 toàn trình. Tính tuân thủ toàn tài liệu được kiểm chứng bởi bộ oracle và bộ golden trong /modules/core/conformance/.

Xem thêm

• Module Navigation — chú thích widget được ghép với các trường.
• Module Security — mô hình tin cậy cho việc ký và FieldMDP.
• Module Accessibility — gắn thẻ trường biểu mẫu cho PDF/UA.
• Tổng quan về tuân thủ