Điền biểu mẫu PDF qua NextPDF Connect (Pro)

Tổng quan nhanh

Dùng NextPDF Connect để điền các trường biểu mẫu PDF tương tác bằng XML Forms Data Format (XFDF). Công cụ dành cho ký và biểu mẫu là fill_form. Nhà cung cấp công cụ Pro đăng ký new FillFormTool() với tên giao thức là fill_form. fill_form là công cụ thuộc bậc Pro. Khi khởi động, máy chủ kiểm tra gói Pro bằng class_exists() và chỉ đăng ký công cụ khi gói có mặt. Nếu chỉ cài Core, fill_form sẽ không có trong registry.

Cài đặt

composer require nextpdf/server
composer require nextpdf/pro

Ràng buộc một transport. Sau đó xác nhận công cụ có tồn tại bằng diagnostic.capabilities (xem environment-diagnostics). Đừng giả định bộ công cụ là cố định.

Tổng quan khái niệm

XFDF ánh xạ tên trường đến giá trị bằng các phần tử <field>. Mỗi tên phải khớp với một trường AcroForm đã tồn tại trong tài liệu đích. Từ điển trường của interactive form giữ từng trường (ISO 32000-2 §12.7), và giá trị được cung cấp trở thành giá trị của trường (ISO 32000-2 §12.7). Nếu một tên không khớp với trường nào, công cụ sẽ bỏ qua nó thay vì coi đó là lỗi. Công cụ báo cáo số trường đã điền và số trường đã bỏ qua.

Bề mặt API

Công cụ	Bậc	Vai trò	Bậc rủi ro
`create_pdf`	Core	Mở phiên	An toàn
`fill_form`	Pro	Áp dụng giá trị XFDF cho các trường AcroForm	Thận trọng
`output_pdf`	Core	Kết xuất và trả về PDF	Cần phê duyệt / Xem xét (base64)

Tên công cụ chính là tên giao thức trong registry. Danh mục công cụ là danh mục chính thức. Bậc đã cài đặt quyết định công cụ nào khả dụng. Các công cụ Pro chỉ xuất hiện khi gói Pro đã được cài đặt.

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

create_pdf (hoặc tải một mẫu đã có sẵn các trường biểu mẫu).
fill_form với xfdf_data ánh xạ tên trường tới giá trị.
output_pdf → base64.

Kết quả sẽ báo cáo fields_filled, fields_skipped, và các tên trường đã khớp.

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

Dùng một mẫu với các tên trường AcroForm mà bạn kiểm soát. Hãy kiểm tra XFDF theo lược đồ XFDF trước khi gửi. Kiểm tra fields_skipped và danh sách tên được trả về để phát hiện tên không khớp (tên có phân biệt chữ hoa chữ thường). Với các lượt điền lớn, hãy giữ dữ liệu dưới giới hạn kích thước XFDF và chia nhỏ nếu cần.

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

XFDF không hợp lệ. Lỗi phân tích cú pháp sẽ chỉ ra vị trí gây lỗi. Hãy escape các thực thể XML và bao gồm xmlns.
Tên không khớp. Một trường không khớp sẽ bị bỏ qua mà không báo lỗi, và fields_skipped tăng lên. Tên có phân biệt chữ hoa chữ thường.
Không có trường biểu mẫu. Một tài liệu không có AcroForm sẽ không điền được trường nào.
XFDF quá lớn. Máy chủ từ chối dữ liệu vượt quá giới hạn kích thước. Hãy chia nhỏ dữ liệu hoặc lược bớt khoảng trắng.
Không có Pro. Nếu chỉ có Core, fill_form không được đăng ký, và việc gọi nó sẽ trả về lỗi công cụ không xác định. Hãy kiểm tra bằng diagnostic.capabilities trước.

Hiệu năng

Việc điền nhanh hơn so với kết xuất. Kết quả dao động từ vài KB đến hàng chục KB, tùy vào số lượng trường và việc nhúng phông chữ. Hồ sơ là structural.

Ghi chú bảo mật

Giá trị của trường trở thành nội dung tài liệu. Đừng đặt thông tin bí mật vào các trường biểu mẫu nếu sau đó bạn trả về PDF qua một kênh không đáng tin cậy. Luồng base64 không có tác động phụ lên hệ thống tệp. Đầu ra tệp được kiểm soát.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Một trường biểu mẫu được giữ trong từ điển trường của interactive form.	ISO 32000-2	§12.7
Dữ liệu được cung cấp trở thành giá trị của trường.	ISO 32000-2	§12.7

Bối cảnh thương mại

fill_form là công cụ thuộc bậc Pro. Máy chủ chỉ đăng ký nó khi gói Pro phân giải được lúc khởi động (phép dò class_exists()). Các triển khai Core không cung cấp công cụ này.

Khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có (Pro)	Chỉ có mặt khi Pro được cài đặt.
REST	Có (Pro)	Tương tự.
gRPC	Có (Pro)	Tương tự.

Bậc rủi ro HITL

fill_form ở mức Thận trọng vì đây là một thay đổi nội dung có thể đảo ngược. output_pdf ở mức Cần phê duyệt và được hạ xuống Xem xét ở chế độ base64 (các bậc rủi ro HITL).

Phong bì JSON của cổng xác nhận

Kết quả base64:

{ "allowed": true }

Đầu ra tệp trả về phong bì thử thách được mô tả trong output-approval.