Biểu mẫu

Tổng quan nhanh

NextPDF Pro đọc và ghi dữ liệu biểu mẫu tương tác: các giá trị trường AcroForm, các tệp dữ liệu XFDF, và dữ liệu được mang bởi các mẫu XFA (XML Forms Architecture). Nó bổ trợ cho bộ đọc biểu mẫu Core mã nguồn mở bằng việc ràng buộc dữ liệu, trích xuất và tuần tự hóa.

Tính khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một phong bì giấy phép bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Form là một phần của phiên bản Pro. Không có cờ giấy phép riêng theo từng tính năng.

Cài đặt

composer require nextpdf/pro:^3

Năng lực Form yêu cầu một giấy phép NextPDF Pro hợp lệ. Xem Tính khả dụng & cấp phép.

Tổng quan khái niệm

Một biểu mẫu PDF tương tác — đôi khi gọi là AcroForm — lưu trữ mỗi trường trong một field dictionary, như được định nghĩa trong ISO 32000-2 §12.7. NextPDF Pro xây dựng trên bộ đọc biểu mẫu Core để bổ sung ba năng lực:

• Round-trip AcroForm. FormDataExtractor đọc các cặp tên/giá trị trường từ các trường biểu mẫu đã phân tích và tạo ra một đối tượng XfdfData hoặc một ánh xạ name → value thuần. XfdfWriter thực hiện chiều ngược lại, tạo ra một tài liệu XFDF.
• Đọc và ghi XFDF. XFDF là định dạng trao đổi dữ liệu XML cho các giá trị biểu mẫu được mô tả bởi ISO 19444-1:2019. XfdfParser đọc một tệp XFDF thành dữ liệu có cấu trúc; XfdfWriter tuần tự hóa các giá trị trường thành XFDF, với một tham chiếu tùy chọn quay lại PDF nguồn.
• Trích xuất dữ liệu XFA. XfaParser định vị các gói XFA trong một tài liệu, ghép nối các mảnh XML, và phân tích các gói template và datasets thành dữ liệu trường có cấu trúc.

Phạm vi hỗ trợ XFA

Hỗ trợ XFA trong NextPDF Pro là hướng-dữ-liệu, không phải một engine kết xuất hay scripting XFA đầy đủ. Bộ phân tích trích xuất và cấu trúc hóa các gói template và datasets để bạn có thể đọc các định nghĩa và giá trị trường. Nó không thực thi các script tính toán biểu mẫu XFA, không kết xuất các bố cục XFA động, và không round-trip mọi kiểu gói XFA. Hãy kiểm thử bộ phân tích với các tài liệu cụ thể của bạn trước khi dựa vào nó cho một tập biểu mẫu XFA nhất định. Mọi việc phân tích XML đều vô hiệu hóa việc nạp thực thể ngoài (an toàn XXE).

Vì sao nó hoạt động theo cách này

Hỗ trợ XFA được thu hẹp về dữ liệu, không phải kết xuất, một cách có chủ đích. ISO 32000-2 đánh dấu mục XFA của form dictionary là bị phản đối (deprecated) trong PDF 2.0 (§12.7). Một engine bố cục và scripting XFA đầy đủ sẽ đuổi theo một bề mặt cũ mà hầu hết khối lượng công việc không còn cần đến. Thay vào đó, NextPDF Pro trích xuất các gói template và datasets, nơi lưu dữ liệu trường bền vững, và từ chối phần còn lại. Cùng lập trường đó dẫn dắt việc phân tích với XXE tắt và mức trần quét, bởi vì đầu vào biểu mẫu thường đến từ các bên không tin cậy. Điều đó giữ cho bề mặt biểu mẫu của Pro là một phần mở rộng mỏng, có thể dự đoán được của mô hình AcroForm của Core.

Nền tảng thiết kế: Từ biểu mẫu điền được đến bản ghi đóng băng: điền và làm phẳng AcroForm.

Bề mặt API

Lớp	Trách nhiệm
FormDataExtractor	Trích xuất các giá trị trường AcroForm dưới dạng XfdfData hoặc một mảng.
XfdfParser	Phân tích một tài liệu XFDF thành dữ liệu có cấu trúc.
XfdfWriter	Tuần tự hóa các giá trị trường thành XFDF, tham chiếu PDF tùy chọn.
XfaParser	Trích xuất và phân tích các gói template và datasets XFA.
FormDataBinder	Ràng buộc một ánh xạ dữ liệu trở lại các trường biểu mẫu.

Tham chiếu đầy đủ ở mức phương thức nằm trong Tham chiếu sâu về Form.

Mẫu mã — Khởi đầu nhanh

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

Mẫu mã — Production

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

Trường hợp biên & lưu ý

• XfaParser từ chối đầu vào PDF lớn hơn mức trần quét của nó thay vì đọc dữ liệu không giới hạn.
• Một tài liệu có thể mang cả biểu mẫu tương tác và không tương tác; việc trích xuất nhắm tới các field dictionary đầu cuối.
• XFDF round-trip các cấu trúc trường phẳng; các hệ phân cấp trường lồng sâu có thể cần xử lý tường minh.

Hiệu năng

Việc trích xuất và tuần tự hóa là tuyến tính theo số lượng trường biểu mẫu. Chi phí phân tích XFA mở rộng theo kích thước của các gói XML nhúng.

Ghi chú về bảo mật

Mọi việc phân tích XML đều vô hiệu hóa phân giải thực thể ngoài để ngăn XXE. Hãy xem đầu vào XFDF và XFA từ nguồn không tin cậy là thù địch và kiểm định tập trường đã phân tích trước khi ràng buộc nó trở lại một tài liệu.

Sự phù hợp tiêu chuẩn

Hành vi	Tham chiếu	Trạng thái
Mô hình biểu mẫu tương tác / field dictionary	ISO 32000-2 §12.7	Đồng bộ (diễn đạt lại)
Định dạng trao đổi dữ liệu XFDF	ISO 19444-1:2019	Đồng bộ

Bảng này ghi lại các đặc tả mà NextPDF Pro được xây dựng theo. Đây không phải là một tuyên bố về chứng nhận chính thức.

Hợp đồng hành vi

• FormDataExtractor đọc các cặp tên/giá trị từ các field dictionary đầu cuối đã phân tích và trả về một đối tượng XfdfData hoặc một mảng name → value thuần.
• XfdfParser phân tích một tài liệu XFDF thành dữ liệu có cấu trúc; XfdfWriter tuần tự hóa các giá trị trường thành XFDF với một tham chiếu tùy chọn quay lại PDF nguồn.
• XfaParser định vị các gói XFA, ghép nối các mảnh XML, và phân tích các gói template và datasets thành dữ liệu trường có cấu trúc. Nó từ chối đầu vào PDF lớn hơn mức trần quét của nó thay vì đọc dữ liệu không giới hạn.
• Hỗ trợ XFA là hướng-dữ-liệu: bộ phân tích trích xuất và cấu trúc hóa các gói template và datasets. Nó không thực thi các script tính toán biểu mẫu XFA, không kết xuất các bố cục XFA động, và không round-trip mọi kiểu gói XFA.
• Mọi việc phân tích XML đều vô hiệu hóa phân giải thực thể ngoài (an toàn XXE).

Ghi chú ranh giới Enterprise

Enterprise không thay đổi hành vi của Form. Enterprise bổ sung các tính năng tuân thủ và lưu trữ bậc cao hơn được ghi tài liệu riêng; chúng không bắt buộc cho round-trip AcroForm, đọc/ghi XFDF, hay trích xuất dữ liệu XFA.

Phương án dự phòng / thay thế trong Core

Bộ đọc biểu mẫu mã nguồn mở của NextPDF Core đọc các trường biểu mẫu. Việc đọc/ghi XFDF, trích xuất dữ liệu XFA và ràng buộc trường là các bổ sung của Pro. Xem /modules/form/.

Ranh giới xuất bản

Trang này chỉ mô tả hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

• Interop — các DTO dữ liệu biểu mẫu có phiên bản cho hệ thống bên ngoài.
• Module Form của Core — bộ đọc biểu mẫu mã nguồn mở.
• Form — Tham chiếu sâu — tham chiếu ở mức phương thức cho các lớp form của Pro.