Проверка состояния макета в 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 относится к уровню Safe (только для чтения) и никогда не требует подтверждения. create_pdf относится к уровню Safe. set_font, add_text и add_page относятся к уровню Caution. output_pdf относится к уровню Approval Required, который в режиме base64 понижается до Review (уровни риска HITL).

JSON-конверт контроля подтверждения

Проверка только для чтения никогда не требует подтверждения:

{ "allowed": true }