在 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 上会失败。若要在输出后查看布局，请设置 destroy: false，并将其用于先前的 output_pdf。
空白文字或未知字体。 适用标准输入验证错误。

性能

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 }