Kết xuất bảng HTML bằng NextPDF Connect

Tổng quan nhanh

Kết xuất dữ liệu dạng bảng có cấu trúc từ một chuỗi bảng HTML. add_table làm sạch dữ liệu đầu vào bằng một danh sách cho phép nghiêm ngặt dựa trên DOMDocument trước khi bố trí, nhờ đó kết quả vẫn nhất quán ngay cả khi mã đánh dấu nguồn khác nhau. Sử dụng các công cụ Core create_pdf, add_table và output_pdf. Bảng được bố trí dưới dạng lưới row/column (CSS Tables 3 §3.1).

Cài đặt

composer require nextpdf/server

Liên kết một transport. Dữ liệu đầu vào phải bao gồm một phần tử gốc <table> với các hàng <tr> và các ô <th>/<td>.

Tổng quan khái niệm

add_table áp dụng một danh sách cố định các phần tử được phép (table, thead, tbody, tfoot, tr, th, td, caption, b, i, u, strong, em, br, p, span). Mọi thuộc tính đều bị loại bỏ khỏi từng phần tử — style, class, width, colspan, rowspan, id và các thuộc tính còn lại. Bất kỳ thẻ nào nằm ngoài danh sách cho phép đều được thay bằng nội dung văn bản của chính thẻ đó. Văn bản trong ô sử dụng trạng thái phông chữ hiện hành của tài liệu; bạn thiết lập trạng thái này bằng set_font trước add_table. Văn bản được phát ra bởi các toán tử hiển thị văn bản theo thứ tự content-stream (ISO 32000-2 §9.4). Công cụ bố cục, không phải CSS nội tuyến, quyết định chiều rộng cột.

Bề mặt API

Công cụ	Vai trò	Cấp độ rủi ro
`create_pdf`	Mở phiên làm việc	An toàn
`set_font`	Thiết lập phông chữ cho văn bản trong ô (tùy chọn, trước `add_table`)	Thận trọng
`add_table`	Làm sạch và bố trí bảng	Thận trọng
`output_pdf`	Kết xuất và trả về PDF	Cần phê duyệt / Xem xét (base64)

Trang Danh mục công cụ là danh mục chính thức. Bộ công cụ sẵn có phụ thuộc vào gói bạn đã cài đặt.

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

create_pdf (A4 khổ dọc, tiêu đề) → document_id.
add_table với một chuỗi <table>...</table> hoàn chỉnh (hàng tiêu đề và các hàng dữ liệu).
output_pdf → base64 hoặc, khi có một file_path, một thao tác ghi tệp có kiểm soát.

Con trỏ di chuyển xuống bên dưới hàng được kết xuất cuối cùng, để chừa chỗ cho nội dung tiếp theo.

Mã mẫu — môi trường vận hành

Kiểm tra HyperText Markup Language (HTML) trước khi gửi. Thiết lập phông chữ cho ô bằng set_font để kiểu chữ được xác định rõ. Nếu bạn dựa vào giá trị mặc định, phông chữ đầu ra sẽ phụ thuộc vào cách triển khai. Để kiểm soát những công cụ mà host được phép gọi, hãy giới hạn registry bằng chính sách bảo mật.

Trường hợp đặc biệt và lưu ý

HTML rỗng hoặc không phải bảng. Dữ liệu đầu vào không có <table> sẽ trả về lỗi không-có-bảng-để-kết-xuất.
Mã đánh dấu sai định dạng. Các thẻ không cân bằng sẽ trả về lỗi phân tích cú pháp, vì vậy hãy kiểm tra cấu trúc trước.
Bảng rộng hơn trang. Hãy giảm số cột, rút ngắn nội dung hoặc chuyển sang hướng ngang.
Tràn nội dung. Một bảng quá cao sẽ tràn sang trang mới. Hãy kiểm tra position.page trong phản hồi hoặc gọi add_page trước.

Hiệu năng

Một bảng nhỏ được kết xuất trong giới hạn cho phép và đầu ra chỉ vài KB. Hồ sơ là structural. Bước làm sạch chạy trong một lượt duy nhất trên DOM đã phân tích.

Lưu ý bảo mật

Việc loại bỏ thuộc tính diễn ra vô điều kiện và không thể bị bỏ qua. Cơ chế này bảo vệ chống lại việc chèn style và script thông qua mã đánh dấu của ô. Không có CSS nội tuyến, trình xử lý sự kiện hay URL javascript: nào có thể tồn tại. Danh sách cho phép chính là ranh giới tin cậy, vì vậy đừng coi kết quả được kết xuất là bản tái tạo trung thực của định kiểu nguồn tùy ý.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Bảng được bố trí dưới dạng lưới ô row/column.	CSS Tables 3	§3.1
Văn bản được hiển thị bằng các toán tử văn bản theo thứ tự luồng.	ISO 32000-2	§9.4

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

Không áp dụng — tất cả công cụ ở đây đều thuộc Core.

Trích lược ma trận hỗ trợ CSS (chỉ phần đã xác minh)

add_table không chạy một công cụ CSS tổng quát. Hành vi “CSS” duy nhất là mô hình lưới bảng cố định: các hàng và cột đến từ cấu trúc của bảng, còn công cụ bố cục chọn chiều rộng. Theo thiết kế, định kiểu nội tuyến không được hỗ trợ vì các thuộc tính đã bị loại bỏ. Để biết phạm vi hỗ trợ CSS ở cấp công cụ (không qua Connect), hãy xem ma trận hỗ trợ CSS của dự án.

Ràng buộc truyền luồng một lượt

add_table phân tích mã đánh dấu được cung cấp thành một DOM một lần và bố trí nó trong một lượt duy nhất. Công cụ này không bố trí lại theo các bảng định kiểu bên ngoài. Một bảng tràn khỏi trang sẽ chuyển sang trang tiếp theo thay vì được bố trí lại từ đầu.

Ngân sách bộ nhớ cho bảng lớn

Các bảng rất lớn giữ DOM đã phân tích và các ô đã bố trí trong bộ nhớ trong suốt toàn bộ lần gọi. Hãy chia tập dữ liệu lớn thành nhiều lần gọi add_table để vẫn nằm trong ngân sách bộ nhớ đỉnh.

Tính sẵn có của transport

Transport	Có sẵn	Ghi chú
MCP (stdio)	Có	HTML lớn sẽ làm khung stdio phình to.
REST	Có	Gửi HTML trong phần thân yêu cầu.
gRPC	Có	Unary; giới hạn kích thước thông điệp được áp dụng.

Cấp độ rủi ro HITL

create_pdf là An toàn; set_font và add_table là Thận trọng; output_pdf là Cần phê duyệt, được hạ xuống Xem xét ở chế độ base64. Đầu ra dạng tệp vẫn là Cần phê duyệt. Xem output-approval.

Bao bọc JSON của cổng xác nhận

Đầu ra Base64:

{ "allowed": true }

Đầu ra dạng tệp trả về lớp bao bọc thử thách mà output-approval mô tả.