Kiểm tra trạng thái bố cục bằng NextPDF Connect

Tổng quan nhanh

Kiểm tra trạng thái bố cục của tài liệu trong phiên làm việc để tự tin quyết định cách định vị nội dung. preview_layout — đã được xác minh lại trong registry công cụ của máy chủ, nơi PreviewLayoutTool hiển thị tên giao thức preview_layout — là một truy vấn chỉ đọc, có tính idempotent. Nó không kết xuất PDF, không di chuyển con trỏ và có thể được gọi nhiều lần tùy ý. Tất cả các công cụ này đều thuộc Core: create_pdf, set_font, add_text, preview_layout, add_page, và output_pdf.

Cài đặt

composer require nextpdf/server

Gắn một transport. Bạn không cần bậc cấp phép.

Tổng quan khái niệm

preview_layout trả về số trang, trang hiện tại, kích thước trang, lề và vị trí con trỏ — các thuộc tính hình học của chính trang (ISO 32000-2 §7.7.3.3). Dùng các giá trị này để tính khoảng trống dọc còn lại:

remaining = page_height - bottom_margin - cursor_y

Nếu remaining lớn hơn chiều cao ước tính của khối tiếp theo, hãy tiếp tục trên trang hiện tại. Nếu không, hãy gọi add_page trước. Vì lệnh gọi này chỉ đọc, nó trả về phản hồi bình thường qua mọi transport (PSR-18 §p2).

Bề mặt API

Công cụ	Vai trò	Bậc rủi ro
create_pdf	Mở phiên làm việc	An toàn
set_font	Đặt phông chữ hiện dùng	Thận trọng
add_text	Viết văn bản, di chuyển con trỏ	Thận trọng
preview_layout	Đọc trạng thái bố cục (không thay đổi)	An toàn
add_page	Thêm một trang khi hết chỗ	Thận trọng
output_pdf	Kết xuất rồi trả về PDF	Cần phê duyệt / Xem xét (base64)

Trang danh mục công cụ là nguồn tham chiếu chính thức. Những công cụ sẵn có phụ thuộc vào bậc đã cài đặt.

Ví dụ mã — bắt đầu nhanh

1. create_pdf (Letter, dọc) → document_id.
2. set_font (helvetica 14).
3. add_text ×3 (đoạn văn căn đều).
4. preview_layout → đọc page_dimensions, margins, cursor_position.
5. Tính remaining; nếu giá trị quá nhỏ, gọi add_page.
6. add_text (phần tiếp theo).
7. output_pdf.

Ví dụ mã — môi trường sản xuất

Gọi preview_layout trước mỗi khối khi bạn không chắc khối đó có vừa hay không. Hãy coi con trỏ trả về là chính xác cho lần viết cuối cùng. Nếu bạn đã thay đổi phông chữ, lề hoặc chiều cao dòng kể từ lần add_text gần nhất, hãy viết một đoạn thử ngắn và truy vấn lại trước khi dựa vào vị trí dự đoán.

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

• Con trỏ lỗi thời sau khi thay đổi kiểu. Vị trí được báo cáo phản ánh lần viết cuối cùng, không phản ánh các thay đổi trạng thái đang chờ. Hãy dò lại nếu độ chính xác là quan trọng.
• Phiên đã bị hủy. preview_layout sẽ thất bại với một document_id đã bị hủy. Để kiểm tra bố cục sau khi xuất, hãy đặt destroy: false trong lần gọi output_pdf trước đó.
• Văn bản rỗng hoặc phông chữ không xác định. Các lỗi xác thực đầu vào tiêu chuẩn sẽ được áp dụng.

Hiệu năng

preview_layout là một thao tác đọc ít tốn kém. Hồ sơ tái lập của tài liệu được tạo ra là structural.

Lưu ý bảo mật

Truy vấn này chỉ đọc và không có tác dụng phụ. Các tọa độ trả về không nhạy cảm, nhưng hãy xem chúng là dữ liệu chỉ có phạm vi trong phiên làm việc.

Tính tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Một đối tượng trang định nghĩa các thuộc tính hình học của nó.	ISO 32000-2	§7.7.3.3
Một truy vấn chỉ đọc trả về một phản hồi transport bình thường.	PSR-18	§p2

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

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

Tính khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	preview_layout là một tools/call.
REST	Có	Thao tác an toàn kiểu GET.
gRPC	Có	Unary; idempotent.

Bậc rủi ro HITL

preview_layout là An toàn (chỉ đọc) và không bao giờ chặn. create_pdf là An toàn. set_font, add_text, và add_page là Thận trọng. output_pdf là Cần phê duyệt, được hạ xuống Xem xét ở chế độ base64 (các bậc rủi ro HITL).

JSON wrapper của cổng xác nhận

Kiểm tra chỉ đọc không bao giờ bị chặn:

{ "allowed": true }

Xem thêm

• Tài liệu nhiều trang
• Chẩn đoán môi trường
• Danh mục công cụ