Управление шрифтами и типографикой через NextPDF Connect

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

Создайте документ с несколькими стилями текста, переключая гарнитуры между текстовыми блоками. set_font задаёт активную гарнитуру, стиль и размер. Это состояние применяется к каждому последующему вызову add_text, пока вы его не измените. Вам понадобятся create_pdf, set_font, add_text и output_pdf — все они входят в набор инструментов Core. Параметры состояния текста управляют отрисовкой глифов (ISO 32000-2 §9).

Установка

composer require nextpdf/server

Подключите транспорт. Вы можете использовать три встроенных семейства шрифтов, не добавляя файлы шрифтов: helvetica, times и courier.

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

set_font принимает family, style ("", "B", "I", "BI", "U") и size. Заданный шрифт применяется к каждому последующему вызову add_text, пока вы снова не вызовете set_font. Автоматического сброса нет. Если в add_text указан font_size, это значение переопределяет активный размер только для этого одного вызова. В следующем вызове снова используется размер из set_font. Текст выводится операторами показа текста в порядке потока содержимого (ISO 32000-2 §9.4). У add_text нет параметра цвета. Цвет текста берётся из цвета заливки графического состояния документа.

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

Инструмент	Роль	Уровень риска
`create_pdf`	Открыть сеанс	Safe (безопасный)
`set_font`	Задать активное состояние typeface/style/размер	Caution (осторожность)
`add_text`	Добавить текст активным шрифтом	Caution (осторожность)
`output_pdf`	Отрисовать и вернуть PDF	Approval Required / Review (требуется подтверждение / проверка, base64)

Эталонный источник — каталог инструментов. Доступные инструменты зависят от установленной редакции.

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

create_pdf (A4, книжная ориентация) → document_id.
set_font (helvetica, B, 24), затем add_text (заголовок, по центру).
set_font (helvetica, "", 12), затем add_text (основной текст по ширине).
set_font (courier, I, 10), затем add_text (фрагмент кода).
output_pdf.

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

Задавайте шрифт явно перед каждым блоком, где важна типографика. Никогда не полагайтесь на унаследованное состояние между логическими разделами. Используйте переопределение font_size для отдельного вызова только для разового выделения: оно не сохраняется. Создавайте документ раздел за разделом и проверяйте, что каждый add_text возвращает position.

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

Неизвестное семейство. Любое семейство вне helvetica/times/courier (например, arial) отклоняется.
Пустое семейство. Значение family должно быть непустой строкой.
Недопустимый стиль. Используйте коды в верхнем регистре. "bold" отклоняется.
Неположительный размер. Значение size должно быть положительным числом.
Размер для отдельного вызова временный. Он не изменяет состояние set_font.

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

Встроенные шрифты почти не увеличивают вес, а размер вывода составляет несколько КБ. Профиль — structural.

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

Режим base64 не даёт побочных эффектов в файловой системе. Встроенные шрифты не загружают внешние файлы шрифтов, поэтому в этом рецепте нет поверхности атаки, связанной с разбором шрифтов.

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

Утверждение	Спецификация	Раздел	reference_id (идентификатор ссылки)
Текст показывается операторами показа текста в порядке потока.	ISO 32000-2	§9.4
Параметры состояния текста управляют отрисовкой глифов.	ISO 32000-2	§9

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

Неприменимо — все инструменты входят в набор Core.

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

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

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

create_pdf — Safe; set_font/add_text — Caution; output_pdf — Approval Required, в режиме base64 понижается до Review (уровни риска HITL).

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

Вывод в base64:

{ "allowed": true }