Pro phiên bản

Form — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu chuyên sâu cho module Pro Form. Nó bao quát việc trích xuất giá trị AcroForm, đọc và ghi XFDF, gắn dữ liệu, và trích xuất dữ liệu XFA. Module tiêu thụ các giá trị NextPDF\Form\FormField do bộ đọc biểu mẫu của Core sinh ra và bổ sung thêm tuần tự hóa, phân tích, và gắn dữ liệu lên trên chúng. Hỗ trợ XFA hướng dữ liệu: bộ phân tích 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 XFA hay kết xuất các bố cục XFA động.

Tình trạng khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope hạng 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à lấy giấy phép.

Không tồn tại cờ giấy phép theo từng tính năng. Đây là một năng lực của phiên bản Pro.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`FormDataExtractor::extract`	`list<FormField> $fields`	Đọc tên và giá trị của từng trường	`XfdfData`	—	Bao gồm cả các trường có giá trị rỗng.
`FormDataExtractor::toArray`	`list<FormField> $fields`	Dựng một map chuỗi từ name sang value	`array<string, string>`	—	Tên trùng lặp xuất hiện sau ghi đè tên trước đó.
`FormDataExtractor::toXfdf`	`list<FormField> $fields`, `?string $pdfHref = null`	Ủy quyền cho `XfdfWriter::fromFields`	`string` (XFDF XML)	—	Lối tắt tiện lợi để export bằng một lệnh gọi.
`FormDataExtractor::extractNonEmpty`	`list<FormField> $fields`	Bỏ qua các trường có giá trị là chuỗi rỗng	`XfdfData`	—	—
`FormDataExtractor::getEmptyFieldNames`	`list<FormField> $fields`	Liệt kê tên các trường chưa gán giá trị	`list<string>`	—	Phần bù của `extractNonEmpty`.
`XfdfWriter::fromFields`	`list<FormField> $fields`, `?string $pdfHref = null`	Thu thập các cặp name-to-value, ủy quyền cho `fromArray`	`string` (XFDF XML)	—	—
`XfdfWriter::fromArray`	`array<string, string> $data`, `?string $pdfHref = null`	Bọc map trong `XfdfData`, rồi ủy quyền	`string` (XFDF XML)	—	—
`XfdfWriter::fromXfdfData`	`XfdfData $data`, `?string $pdfHref = null`	Tuần tự hóa thành XFDF; tên dạng dot-notation lồng thành cây phần tử `<field>` phân cấp	`string` (XFDF XML)	—	Loại bỏ các ký tự điều khiển bị XML 1.0 cấm; xem hợp đồng hành vi.
`XfdfParser::parse`	`string $xfdfXml`	Nạp XML theo cách an toàn XXE và làm phẳng các trường về dot notation	`XfdfData`	`InvalidArgumentException`	Mức trần đầu vào 10 MiB; chấp nhận root có và không có namespace.
`XfdfParser::parseFile`	`string $filePath`	Phân giải đường dẫn, đọc tệp, ủy quyền cho `parse`	`XfdfData`	`InvalidArgumentException`	Đường dẫn không tồn tại, không phải tệp, hoặc không đọc được sẽ phát sinh lỗi.
`XfaParser::parse`	`string $pdfData`	Kiểm tra marker, trích xuất XML, phân tích gói	`XfaFormData`	`InvalidArgumentException`, `XfaParseException`	Không có marker `/XFA` thì trả về kết quả rỗng, không phải lỗi.
`XfaParser::hasXfa`	`string $pdfData`	Quét các byte để tìm marker `/XFA`	`bool`	—	Quét byte-marker; bất kỳ lần xuất hiện nào của token đều khớp.
`XfaParser::extractXfaXml`	`string $pdfData`	Quét stream để tìm marker XFA, rồi tìm trực tiếp `<xdp:xdp>`	`string` (XFA XML hoặc `''`)	`RuntimeException` (đã khai báo)	Quét tối đa 50 MiB đầu tiên của đầu vào.
`XfaParser::parseXml`	`string $xml`	Trích xuất các gói template và datasets, phân tích các phần tử `<field>`	`XfaFormData`	`XfaParseException`	Mức trần XML 10 MiB, áp đặt trước khi nạp DOM.
`FormDataBinder::bind`	`list<FormField> $fields`, `XfdfData $data`	Tạo các thể hiện `FormField` mới với giá trị đã gắn	`FormDataBindResult`	—	Bản gốc không bao giờ bị sửa đổi; check box chuẩn hóa về `Yes`/`Off`.
`FormDataBinder::fromXfdf`	`list<FormField> $fields`, `string $xfdfXml`	Phân tích XFDF, rồi gắn	`FormDataBindResult`	`InvalidArgumentException`	Các kiểu lỗi giống với `XfdfParser::parse`.
`FormDataBinder::fromArray`	`list<FormField> $fields`, `array<string, string> $data`	Bọc map trong `XfdfData`, rồi gắn	`FormDataBindResult`	—	—
`FormDataBindResult`	`isFullyBound`, `hasNoUnmatchedKeys`, `boundCount`, `fieldCount`; readonly `fields`, `boundFieldNames`, `unmatchedDataKeys`, `unboundFieldNames`	Chẩn đoán gắn bất biến	theo từng phương thức	—	`isFullyBound` đòi hỏi không có key nào không khớp và không có trường nào chưa gắn.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	Vùng chứa name-to-value bất biến	theo từng phương thức	—	`with*` và `merge` trả về các thể hiện mới; `merge` ưu tiên giá trị của tham số.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	Kết quả phân tích XFA bất biến	theo từng phương thức	—	Mang theo XML gói template và datasets thô để round-trip.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	Bản ghi đơn-trường bất biến	—	—	`type` là một trong `text`, `numeric`, `date`, `choice`, `button`, `signature`.
`XfaPacket`	các case enum `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	Enum gói backed bằng chuỗi	`string` từ `xmlNamespace()`	—	Các URI namespace tuân theo XFA Specification 3.3.

public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array

public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string

public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData

public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData

public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

Ngoại lệ

NextPDF\Pro\Form\Exception\XfaParseException kế thừa RuntimeException — payload XFA không thể phân tích thành một XfaFormData. Việc kế thừa lớp con là có chủ đích: các call site catch (RuntimeException $e) hiện có vẫn tiếp tục hoạt động.
SPL InvalidArgumentException — đầu vào rỗng, quá cỡ, dị dạng, hoặc không phải XFDF đưa vào XfdfParser; đầu vào PDF rỗng cho XfaParser::parse; đường dẫn không đọc được trong XfdfParser::parseFile.

Hợp đồng hành vi

Trích xuất AcroForm. FormDataExtractor đi qua danh sách trường bạn truyền vào và đọc tên cùng giá trị của mỗi trường. extract trả về một XfdfData; toArray trả về một map chuỗi name-to-value thuần túy. extractNonEmpty loại bỏ các trường có giá trị là chuỗi rỗng; getEmptyFieldNames trả về danh sách tên bổ sung. Việc trích xuất không bao giờ làm biến đổi các trường đầu vào.

Ghi XFDF. XfdfWriter tạo ra một tài liệu tuân theo cấu trúc ISO 19444-1:2019. Đầu ra bắt đầu bằng khai báo XML của XFDF và một root xfdf trong namespace Adobe XFDF (http://ns.adobe.com/xfdf/) với xml:space="preserve". Một pdfHref khác null phát ra một tham chiếu <f href="..."/> trỏ ngược về PDF nguồn. Các tên trường dạng dot-notation (ví dụ address.city) lồng thành một cây phần tử <field> phân cấp. Các giá trị và thuộc tính được escape năm ký tự metacharacter của XML. Tên trường, giá trị, và pdfHref còn được chuẩn hóa thêm để đảm bảo well-formed: các ký tự điều khiển C0 mà XML 1.0 cấm sẽ bị loại bỏ, trong khi TAB, LF, và CR được giữ lại. Việc chuẩn hóa này cố tình gây mất mát, nên bộ ghi luôn phát ra XFDF well-formed, phân tích lại được, bất kể byte do bên gọi cung cấp.

Đọc XFDF. XfdfParser chấp nhận cả root xfdf có và không có namespace và so khớp tên root không phân biệt hoa thường, vì một số bộ tạo phát ra phần tử root viết hoa. Các cây <field> phân cấp làm phẳng trở lại thành tên dot-notation, nên ghi và đọc round-trip được với nhau. Toàn bộ việc nạp XML đều tắt truy cập mạng và phân giải thực thể bên ngoài. parseFile thêm bước phân giải đường dẫn và kiểm tra khả năng đọc trước cùng một quá trình phân tích đó.

Gắn dữ liệu. FormDataBinder::bind so khớp các key dữ liệu với tên trường. Vì FormField là bất biến, việc gắn tạo ra các thể hiện mới với giá trị được cập nhật; bản gốc không bao giờ bị sửa đổi. Kết quả báo cáo ba tập chẩn đoán: tên các trường đã gắn, các key dữ liệu không có trường tương ứng, và các trường không nhận được dữ liệu. Giá trị check box chuẩn hóa về mô hình trạng thái on/off của ISO 32000-2:2020, 12.7.5.2.3: không phân biệt hoa thường yes, true, 1, và on ánh xạ thành Yes; mọi giá trị khác ánh xạ thành Off.

Trích xuất dữ liệu XFA. XfaParser::parse nhận các byte PDF thô. Trước tiên nó quét tìm marker /XFA; nếu vắng marker nó trả về một XfaFormData rỗng. Sau đó việc trích xuất thử hai chiến lược: quét các khối stream…endstream để tìm chỉ dấu XFA XML, rồi tìm trực tiếp một tài liệu <xdp:xdp>. Một đoạn xdp:xdp đơn lẻ được trả về nguyên trạng; nhiều đoạn được ghép nối thành một bao xdp:xdp được tổng hợp. parseXml trích xuất các gói template và datasets và phân tích mỗi phần tử <field> template thành một XfaFormField: thuộc tính name là bắt buộc, type suy ra từ phần tử con UI của trường, cờ required suy ra từ một phần tử validate có nullTest đặt thành error, và các tùy chọn choice đến từ các phần tử con items.

Hỗ trợ XFA hướng dữ liệu. Bộ phân tích 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 XFA, không kết xuất các bố cục XFA động, và không round-trip mọi loại gói. Hãy xác thực bộ phân tích trên tập tài liệu cụ thể của bạn trước khi tin cậy nó.

Trường hợp biên & kiểu lỗi

XfdfParser::parse('') ném InvalidArgumentException. Đầu vào trên 10 MiB ném InvalidArgumentException có nêu mức trần.
XML dị dạng ném InvalidArgumentException mang theo các thông báo libxml đã thu thập. Một tài liệu well-formed mà root không phải xfdf sẽ ném và nêu tên phần tử root thực tế.
Một tài liệu XFDF không có phần tử <fields> phân tích ra thành một XfdfData rỗng; đó không phải là lỗi.
Các phần tử trường không có thuộc tính name bị bỏ qua trong cả phân tích XFDF và XFA. Một trường XFDF không có phần tử con <value> không đóng góp mục nào.
XfaParser::parse('') ném InvalidArgumentException. Một PDF không có marker /XFA, hoặc một PDF không thể định vị được XFA XML, sẽ trả về một XfaFormData rỗng thay vì ném lỗi.
hasXfa là một phép quét byte-marker: bất kỳ token /XFA nào trong tệp đều khớp, kể cả một token trong đối tượng không dùng đến. Bước trích xuất tiếp theo quyết định liệu có XML dùng được hay không.
Việc trích xuất XFA chỉ xét tối đa 50 MiB đầu tiên của chuỗi byte PDF; nội dung vượt quá ngưỡng đó không được quét.
XFA XML trên 10 MiB ném XfaParseException trước khi bất kỳ cây DOM nào được hiện thực hóa. XFA XML dị dạng ném XfaParseException kèm các thông báo libxml.
Việc chuẩn hóa check box không bao giờ cho các giá trị không nhận dạng được đi qua; bất cứ thứ gì ngoài các dạng on được chấp nhận đều ánh xạ thành Off.
Việc loại bỏ ký tự điều khiển của bộ ghi gây mất mát: các byte C0 bị XML 1.0 cấm trong tên, giá trị, hoặc pdfHref bị loại bỏ để đầu ra vẫn well-formed. TAB, LF, và CR được giữ lại.
Toàn bộ việc phân tích XML đều tắt phân giải thực thể bên ngoài và truy cập mạng (an toàn XXE).
Module này không thực hiện thao tác mã hóa nào; chế độ FIPS không thay đổi hành vi của nó.

Tính phù hợp

Hành vi	Tham chiếu	Trạng thái
Mô hình biểu mẫu tương tác / từ điển trường	ISO 32000-2:2020, 12.7	Đã căn chỉnh (dựa trên sản phẩm)
Chuẩn hóa trạng thái on/off của check box (`Yes`/`Off`)	ISO 32000-2:2020, 12.7.5.2.3	Đã căn chỉnh; điều khoản được trích dẫn trong bản ghi trích dẫn của trang này
Cấu trúc trao đổi dữ liệu XFDF	ISO 19444-1:2019	Đã căn chỉnh (dựa trên sản phẩm)
Tên gói XFA và các URI namespace	XFA Specification 3.3	Đã căn chỉnh (dựa trên sản phẩm)

Kho ngữ liệu RAG có sẵn tại thời điểm biên soạn không bao gồm ISO 19444-1:2019, XFA Specification, hay W3C XML 1.0, nên các tuyên bố căn chỉnh đó dựa trên sản phẩm từ các chú thích nguồn và bài kiểm thử thay vì trích dẫn điều khoản. Các tuyên bố này mô tả năng lực đối chiếu với các tài liệu được tham chiếu. NextPDF không nắm giữ chứng nhận phù hợp nào, và việc hỗ trợ một điều khoản không phải là một tuyên bố chứng nhận.

Ghi chú phát triển

Mọi entry point trừ XfaParser đều là static. XfaParser có thể khởi tạo và không trạng thái; một thể hiện có thể tái dùng an toàn cho nhiều tài liệu.
Chu trình round-trip dự kiến là: bộ đọc biểu mẫu của Core sinh ra các giá trị FormField; FormDataExtractor hoặc XfdfWriter tuần tự hóa chúng; XfdfParser đọc dữ liệu trở lại; FormDataBinder áp dụng nó lên một danh sách trường. Các tên phân cấp sống sót qua chu trình round-trip nhờ dot notation.
Dùng các chẩn đoán của FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) để phát hiện sai lệch giữa một tệp dữ liệu XFDF và một template PDF đã sửa đổi trước khi chấp nhận một lần điền.
XfdfData là một đối tượng giá trị: withField, withoutField, và merge trả về các thể hiện mới. Khi key va chạm, merge ưu tiên giá trị của tham số.
XfaFormData giữ lại XML gói template và datasets thô (templateXml, datasetsXml) để bạn có thể hậu xử lý các gói mà mô hình trường không bao phủ.
Module này không tự phân tích các từ điển AcroForm ra khỏi byte PDF; nó tiêu thụ các trường do bộ đọc biểu mẫu của Core sinh ra. Chỉ XfaParser hoạt động trên nội dung PDF thô.

Ranh giới xuất bản

Trang này chỉ ghi lại 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à tiền tố ticket đều nằm ngoài phạm vi.