Создание многостраничного документа с NextPDF Connect

Краткий обзор

Создайте многостраничный документ с помощью NextPDF Connect. add_page добавляет страницу, которая наследует геометрию документа по умолчанию или получает явно заданную ориентацию. После каждого вызова add_page курсор сбрасывается к левому верхнему полю новой страницы. Для этого используются четыре инструмента Core: create_pdf, add_text, add_page и output_pdf.

Установка

composer require nextpdf/server

Привяжите транспорт: Model Context Protocol (MCP) stdio, REST или gRPC. Лицензируемый уровень не нужен.

Концептуальный обзор

В документе используется дерево страниц. Доступ к каждой странице осуществляется через это дерево (ISO 32000-2 §7.7.3). Страница имеет собственные атрибуты геометрии, включая медиабокс, который определяет видимую область (ISO 32000-2 §7.7.3.3). create_pdf создаёт первую страницу автоматически, а add_page добавляет каждую следующую страницу. Не указывайте page_size/orientation, чтобы унаследовать значения документа по умолчанию. Задайте orientation: "landscape", чтобы страница A4 получила размер 297×210 мм.

Поверхность API

Инструмент	Роль	Уровень риска
create_pdf	Открывает сеанс и создаёт первую страницу	Safe (безопасно)
add_text	Записывает текст в текущей позиции курсора	Caution (с осторожностью)
add_page	Добавляет страницу (с наследованием или переопределением)	Caution (с осторожностью)
output_pdf	Формирует и возвращает PDF	Approval Required (требуется подтверждение) / Review (проверка) в режиме base64

Имена инструментов — это протокольные имена реестра. Каталог инструментов служит источником истины. Набор доступных инструментов зависит от установленного уровня.

Пример кода — быстрый старт

Последовательность:

1. create_pdf (A4, книжная ориентация, заголовок, автор) → document_id.
2. add_text (заголовок, крупный шрифт, по центру), затем add_text (вводный абзац, основной шрифт).
3. add_page только с document_id → наследует A4 и книжную ориентацию. Возвращается новый page_number, и курсор сбрасывается.
4. add_text для заголовка раздела и основного текста на странице 2.
5. add_page с orientation: "landscape" → широкая страница A4.
6. add_text для широкого содержимого.
7. output_pdf → base64.

Пример кода — продакшен

Проверяйте каждый ответ. После add_page содержимое начинается сверху новой страницы. Сброс курсора — это предусмотренное поведение, а не ошибка. Отслеживайте position.page в ответах add_text, чтобы определить, когда содержимое перешло на следующую страницу. Вызовите output_pdf ровно один раз, затем больше не используйте document_id.

Граничные случаи и подводные камни

• Сброс курсора. После add_page курсор находится у левого верхнего поля новой страницы. Распространённая ошибка — ожидать, что позиция продолжится с предыдущей страницы.
• Обязательный document_id. Каждый инструмент, кроме create_pdf, требует document_id. Если его не передать, возникнет ошибка.
• Недопустимая ориентация. Допустимы только "portrait" и "landscape".
• Редактирование после вывода. Попытка добавить содержимое после output_pdf с destroy: true приведёт к ошибке, поскольку сеанс уже завершён.

Производительность

Многостраничный текстовый документ укладывается в бюджет по страницам, а результат занимает несколько КБ. Профиль — structural: /ID в трейлере и временные метки не остаются стабильными между запусками.

Примечания по безопасности

Режим base64 не имеет побочных эффектов. Вывод в файл ограничен; см. раздел human-in-the-loop (HITL). document_id — это непрозрачный дескриптор. Не передавайте его одновременно в параллельные запросы.

Соответствие

Утверждение	Спецификация	Раздел	reference_id (идентификатор ссылки)
Доступ к страницам осуществляется через дерево страниц.	ISO 32000-2	§7.7.3
Объект страницы определяет собственные атрибуты геометрии.	ISO 32000-2	§7.7.3.3

Коммерческий контекст

Неприменимо — все инструменты относятся к Core.

Доступность транспортов

Транспорт	Доступен	Примечания
MCP (stdio) — стандартный ввод-вывод	Да	tools/call для каждого инструмента.
REST	Да	По одной операции на инструмент.
gRPC	Да	По одному унарному вызову на инструмент.

Уровень риска HITL

create_pdf — Safe; add_text и add_page — Caution; output_pdf — Approval Required, снижается до Review в режиме base64. Вывод в файл остаётся Approval Required. См. output-approval и HITL risk tiers.

JSON-конверт шлюза подтверждения

Для вывода в base64:

{ "allowed": true }

Форма запроса показана в output-approval.

См. также

• Hello world через Connect
• Инспекция макета
• Каталог инструментов