Tạo tài liệu nhiều trang bằng NextPDF Connect

Tổng quan nhanh

Tạo tài liệu nhiều trang bằng NextPDF Connect. add_page thêm một trang kế thừa hình học mặc định của tài liệu hoặc dùng hướng được chỉ định riêng. Sau mỗi lần gọi add_page, con trỏ được đặt lại về lề trên cùng bên trái của trang mới. Bạn dùng bốn công cụ Core: create_pdf, add_text, add_page và output_pdf.

Cài đặt

composer require nextpdf/server

Gắn một transport: Model Context Protocol (MCP) stdio, REST hoặc gRPC. Không bắt buộc phải có bậc giấy phép.

Tổng quan khái niệm

Tài liệu sử dụng cây trang (page tree). Các trang được truy cập thông qua cây đó (ISO 32000-2 §7.7.3). Một trang có các thuộc tính hình học riêng, bao gồm media box xác định vùng hiển thị (ISO 32000-2 §7.7.3.3). create_pdf tự động tạo trang đầu tiên, còn add_page thêm từng trang bổ sung. Bỏ qua page_size/orientation để kế thừa giá trị mặc định của tài liệu. Đặt orientation: "landscape" để trang A4 trở thành 297×210 mm.

Giao diện API

Công cụ	Vai trò	Bậc rủi ro
create_pdf	Mở phiên và tạo trang đầu tiên	An toàn
add_text	Viết văn bản tại vị trí con trỏ	Thận trọng
add_page	Thêm trang (kế thừa hoặc ghi đè)	Thận trọng
output_pdf	Kết xuất và trả về PDF	Yêu cầu phê duyệt / Xem xét (base64)

Tên công cụ là tên giao thức trong registry. Danh mục công cụ là nguồn tham chiếu chính thức. Các công cụ sẵn có phụ thuộc vào bậc đã cài đặt.

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

Quy trình bằng lời:

1. create_pdf (A4 dọc, tiêu đề, tác giả) → document_id.
2. add_text (tiêu đề, phông chữ lớn, căn giữa), rồi add_text (đoạn giới thiệu, phông chữ thân).
3. add_page chỉ với document_id → kế thừa A4 dọc. page_number mới được trả về và con trỏ được đặt lại.
4. add_text cho tiêu đề mục và phần thân trên trang 2.
5. add_page với orientation: "landscape" → một trang A4 nằm ngang.
6. add_text cho nội dung rộng.
7. output_pdf → base64.

Mẫu mã — môi trường production

Xác minh từng phản hồi. Sau add_page, nội dung bắt đầu ở đầu trang mới. Việc đặt lại con trỏ là hành vi có chủ đích, không phải lỗi. Theo dõi position.page từ các phản hồi của add_text để phát hiện thời điểm nội dung tràn sang trang sau. Gọi output_pdf đúng một lần, rồi loại bỏ document_id.

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

• Đặt lại con trỏ. Sau add_page, con trỏ nằm ở lề trên cùng bên trái của trang mới. Lỗi thường gặp là kỳ vọng nó tiếp tục từ trang trước.
• Bắt buộc có document_id. Mọi công cụ ngoại trừ create_pdf đều yêu cầu document_id. Bỏ qua trường này là lỗi.
• Hướng không hợp lệ. Chỉ "portrait" và "landscape" là hợp lệ.
• Chỉnh sửa sau khi xuất. Việc thêm nội dung sau output_pdf với destroy: true sẽ thất bại vì phiên đã bị hủy.

Hiệu năng

Một tài liệu văn bản nhiều trang vẫn nằm trong ngân sách trang, và đầu ra chỉ vài KB. Hồ sơ là structural: trailer /ID và dấu thời gian không ổn định giữa các lần chạy.

Ghi chú bảo mật

Chế độ base64 không có tác dụng phụ. Xuất ra tệp được kiểm soát; xem mục human-in-the-loop (HITL). document_id là một handle mờ. Đừng chia sẻ handle này giữa các yêu cầu chạy đồng thời.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản	reference_id
Các trang được truy cập thông qua cây trang.	ISO 32000-2	§7.7.3
Một đối tượng trang định nghĩa các thuộc tính hình học riêng của nó.	ISO 32000-2	§7.7.3.3

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

Không áp dụng — tất cả công cụ đều nằm trong Core.

Khả năng hỗ trợ transport

Transport	Có sẵn	Ghi chú
MCP (stdio)	Có	tools/call cho từng công cụ.
REST	Có	Một thao tác cho từng công cụ.
gRPC	Có	Unary cho từng công cụ.

Bậc rủi ro HITL

create_pdf là An toàn; add_text và add_page là Thận trọng; output_pdf là Yêu cầu phê duyệt, hạ xuống Xem xét ở chế độ base64. Xuất ra tệp vẫn là Yêu cầu phê duyệt. Xem output-approval và các bậc rủi ro HITL.

Phong bì JSON của cổng phê duyệt

Kết quả base64 ở đây:

{ "allowed": true }

Mẫu thử thách nằm trong output-approval.

Xem thêm

• Hello world
• Kiểm tra bố cục
• Danh mục công cụ