Вертикальное письмо CJK через Connect

Обзор

Этот рецепт показывает, как через транспорты Connect встроить шрифт CIDFont для китайского, японского и корейского письма (CJK) с метриками вертикального письма. Движок выводит записи вертикальных метрик PDF 2.0 (/W2 для каждого глифа и /DW2 по умолчанию) в словаре CIDFont и располагает глифы сверху вниз. Встраивание шрифтов CJK относится к уровню Enterprise. Инструменты для шрифтов CJK обнаруживаются через проверки class_exists() и регистрируются только тогда, когда nextpdf/premium установлен вместе с сервером. Движок выводит вертикальные метрики только тогда, когда активная кодировка CID является вертикальной кодировкой Identity. Горизонтальные фрагменты текста остаются без изменений.

Установка

composer require nextpdf/server

С помощью tools/list убедитесь, что инструменты для шрифтов CJK уровня Enterprise доступны. См. /connect/tool-catalog/.

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

Шрифт CIDFont в режиме вертикального письма использует вертикальные метрики /W2 (для каждого глифа) и /DW2 (по умолчанию) (ISO 32000-2 §9.7). CMap выбирает горизонтальный или вертикальный режим письма (ISO 32000-2 §9.7). Режим вертикального письма переносит приращение глифа на вертикальную ось (ISO 32000-2 §9.7). При регистрации шрифта конвейер разбирает его таблицы вертикальных метрик. Записи словаря выводятся только после того, как вы выберете вертикальную кодировку CID.

Интерфейс API

Проверьте имена инструментов в рабочем реестре с помощью tools/list. Эталонный каталог — /connect/tool-catalog/. Этот рецепт не дублирует количество инструментов.

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

Создайте документ, зарегистрируйте шрифт CJK и выберите вертикальную кодировку:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_cjk_font",
    "arguments": {
      "document_id": "<id>",
      "family": "NotoSansCJKjp",
      "source": "/usr/share/fonts/opentype/noto/NotoSansCJKjp-Regular.otf",
      "subset": true
    }
  }
}

Пример кода — рабочая среда

Выберите вертикальную кодировку, задайте шрифт, запишите вертикальный фрагмент текста, а затем выведите и проверьте словарь CIDFont:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "set_cid_encoding",
    "arguments": { "document_id": "<id>", "font_key": "NotoSansCJKjp", "encoding": "/Identity-V" }
  }
}

Словарь CIDFont в выходных данных содержит /W2 и /DW2. При отрисовке с горизонтальной кодировкой тот же исходный код опускает обе записи. Различается только проверка кодировки, поэтому профиль воспроизводимости structural здесь остаётся точным.

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

В шрифте отсутствуют таблицы вертикальных метрик. Инструмент для работы со шрифтами выдаёт предупреждение. Выберите шрифт CJK, который их содержит; шрифт только с латиницей таких таблиц не имеет.
Выбор вертикальной кодировки для шрифта без вертикальных метрик считается ошибкой. Вернитесь к горизонтальной кодировке или выберите другой шрифт.
Запрос вертикального текста при активной горизонтальной кодировке считается ошибкой. Выберите вертикальную кодировку до первого вывода вертикального текста.
Переключение кодировки после первого вывода текста отклоняется с ошибкой о замороженной кодировке. Задайте кодировку сразу после регистрации шрифта.
Инструмент отсутствует. Без nextpdf/premium инструменты для шрифтов CJK уровня Enterprise не регистрируются, и вызов завершается ошибкой неизвестного инструмента.

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

Бюджет в front-matter — документационный предел. Создание подмножества ограничивает размер массива метрик для каждого глифа. Отключайте создание подмножества только тогда, когда вертикальному фрагменту текста нужны глифы, которые иначе были бы отброшены из подмножества.

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

Дополнительных примечаний нет, кроме общих рекомендаций по транспортам Connect.

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

Утверждение	Пункт	reference_id (идентификатор ссылки)
Шрифт CIDFont в вертикальном режиме использует `/W2` и `/DW2` для вертикальных метрик	ISO 32000-2 §9.7
CMap выбирает горизонтальный или вертикальный режим письма	ISO 32000-2 §9.7
Режим вертикального письма продвигает глифы по вертикальной оси	ISO 32000-2 §9.7

Вывод записей вертикальных метрик реализует процитированные пункты. Это не общее утверждение о соответствии. Валидатор определяет соответствие документа в целом.

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

Встраивание шрифтов CJK относится к уровню Enterprise. Инструменты для шрифтов CJK регистрируются только тогда, когда nextpdf/premium установлен вместе с сервером.

Особенности Connect

Доступность транспортов (MCP / REST / gRPC)

Вызов выполняется одинаково через MCP tools/call, конечную точку инструментов REST и службу gRPC. Все три направляются через общий исполнитель инструментов.

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

Регистрация шрифта, выбор кодировки и вывод текста относятся к уровню caution. Вывод требует подтверждения, если записывает файл; в режиме base64 подтверждение не требуется. См. /connect/hitl-risk-tiers/.

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

Когда путь вывода с записью файла защищён шлюзом, шлюз возвращает конверт запроса и одноразовый токен, привязанный к имени инструмента, nonce и TTL в 300 секунд. Повторите вызов с arguments._confirmation_token. См. /connect/hitl-risk-tiers/.

См. также

/cookbook/connect/font-typography/ — основы работы с горизонтальным текстом и выбора шрифта.
/cookbook/connect/conformance-mode/ — вертикальные фрагменты текста CJK по-прежнему требуют тегирования для PDF/UA-2.
/connect/tool-catalog/ — вычисление набора инструментов для каждого уровня.
/connect/hitl-risk-tiers/ — модель рисков и шлюз.