在 NextPDF Connect 中檢視版面狀態

概覽

在工作階段進行期間檢視文件的版面狀態，方便你做出定位決策。preview_layout——已對伺服器工具登錄重新驗證，其中 PreviewLayoutTool 公開了協定名稱 preview_layout——是一項唯讀且具冪等性的查詢。它不會算繪 PDF，也不會推進游標，你可以呼叫任意次數。這些工具全都屬於 Core：create_pdf、set_font、add_text、preview_layout、add_page 與 output_pdf。

安裝

composer require nextpdf/server

綁定一個傳輸層。不需要任何授權層級。

概念總覽

preview_layout 會回傳頁數、目前頁面、頁面尺寸、邊界與游標位置——也就是頁面本身的幾何屬性（ISO 32000-2 §7.7.3.3）。根據這些數值計算剩餘的垂直空間：

remaining = page_height - bottom_margin - cursor_y

如果 remaining 超過你下一個區塊的預估高度，就在目前頁面上繼續。否則，先呼叫 add_page。由於此呼叫是唯讀的，它在每一種傳輸層上都會回傳正常回應（PSR-18 §p2）。

API 介面

工具	角色	風險層級
`create_pdf`	開啟工作階段	安全
`set_font`	設定使用中的字型	謹慎
`add_text`	寫入文字，推進游標	謹慎
`preview_layout`	讀取版面狀態（不會變更）	安全
`add_page`	當空間用盡時附加一頁	謹慎
`output_pdf`	算繪並回傳 PDF	需核准/審查（base64）

工具目錄是正式登載的目錄。你可以使用哪些工具，取決於已安裝的層級。

程式碼範例——快速入門

create_pdf（Letter 直向）→ document_id。
set_font（helvetica 14）。
add_text ×3（左右對齊的段落）。
preview_layout → 讀取 page_dimensions、margins、cursor_position。
計算 remaining；若太小，就 add_page。
add_text（下一個段落）。
output_pdf。

程式碼範例——正式環境

遇到任何不確定能否容納的區塊前，先呼叫 preview_layout。請將回傳的游標視為對最後一次寫入而言是準確的。如果你在上一次 add_text 之後變更了字型、邊界或行高，請先寫入一段簡短的探測內容並重新查詢，再依賴預測的位置。

邊界情況與陷阱

樣式變更後的過時游標。 回傳的位置反映的是最後一次寫入，而非任何待處理的狀態變更。若精確度很重要，請重新探測。
已銷毀的工作階段。 preview_layout 用於已銷毀的 document_id 時會失敗。若要在輸出後檢視版面，請在先前的 output_pdf 設定 destroy: false。
空白文字或未知字型。 會套用標準的輸入驗證錯誤。

效能

preview_layout 是一項低成本的讀取操作。所產生文件的設定檔為 structural。

安全性注意事項

這項查詢是唯讀的，且沒有任何副作用。回傳的座標並非敏感資料，但仍應將其視為僅限工作階段範圍。

符合性

陳述	規範	條款	reference_id
頁面物件會定義其幾何屬性。	ISO 32000-2	§7.7.3.3
唯讀查詢會回傳正常的傳輸層回應。	PSR-18	§p2

商業情境

不適用——所有工具皆屬於 Core。

傳輸層可用性

傳輸層	可用	備註
MCP (stdio)	是	`preview_layout` 是一個 `tools/call`。
REST	是	一項安全的 GET 式操作。
gRPC	是	一元式；具冪等性。

HITL 風險層級

preview_layout 屬於「安全」（唯讀），且絕不會觸發閘門。create_pdf 屬於「安全」。set_font、add_text 與 add_page 屬於「謹慎」。output_pdf 屬於「需核准」，在 base64 模式下會降級為「審查」（HITL 風險層級）。

確認閘門 JSON 封包

唯讀檢視絕不會觸發閘門：

{ "allowed": true }