Разметка артефактов страницы через Connect

Кратко

Этот рецепт через транспорты Connect оборачивает служебные элементы пагинации — в том числе колонтитулы, номера страниц, водяные знаки и фоны — в содержимое, помеченное как артефакт. Эти служебные элементы по-прежнему отображаются на странице, но не попадают в дерево структуры и порядок чтения вспомогательных технологий. Инструмент артефактов относится к уровню Enterprise: NextPDF обнаруживает его с помощью проверки class_exists() и регистрирует только тогда, когда nextpdf/premium установлен вместе с сервером. Подтип задаётся типизированным перечислением (Pagination, Layout, Page, Background).

Чтобы проверить результат, используйте инструмент проверки на соответствие стандартам уровня Enterprise, который формирует отчёт по PDF/UA-2. Положительный результат означает проверку, выполненную самим инструментом, а не независимую сертификацию соответствия.

Установка

composer require nextpdf/server

Проверьте наличие инструмента артефактов Enterprise вызовом tools/list. См. /connect/tool-catalog/.

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

Содержимое, не входящее в логическую структуру, помечается как артефакт и исключается из порядка чтения (PDF/UA-2 §8.3). Артефактами считаются элементы пагинации, макета, страницы или фона; они отличаются от реального содержимого (PDF/UA-2 §8.3). Реальное содержимое отражается в дереве структуры; артефакты — нет (PDF/UA-2 §8.2.4).

Инструмент открывает последовательность помеченного содержимого для артефакта запрошенного подтипа. Любые операции рисования, выполненные до соответствующего закрытия, оборачиваются в неё.

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

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

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

Откройте артефакт Background, нарисуйте водяной знак и закройте артефакт:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

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

Каждому открытию сопоставляйте закрытие и проверяйте, что на странице нет осиротевшего содержимого:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

После отрисовки текста нижнего колонтитула закройте артефакт инструментом завершения и запустите проверку на соответствие PDF/UA-2. Дерево структуры должно содержать только основное содержимое; водяной знак и нижний колонтитул должны быть исключены.

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

Неизвестный подтип (например, "Header") отклоняется. Передайте одно из значений: Pagination, Layout, Page, Background.
Закрытие без открытия завершается ошибкой с сообщением о нулевой глубине. Всегда сопоставляйте открытие и закрытие.
Рисование до открытия контекста артефакта или структуры порождает осиротевшее содержимое и нарушение правила структуры. Сначала откройте контекст структуры или артефакта.
Инструмент отсутствует. Без nextpdf/premium инструмент артефактов Enterprise не регистрируется, и вызов завершается ошибкой о неизвестном инструменте.

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

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

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

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

Соответствие требованиям

Сопоставление с PDF/UA-2

Подтип	Сценарий использования
`Pagination`	Постраничные headers/footers, номера страниц, навигационные служебные элементы
`Layout`	Линейки, разделители, декоративные рамки
`Page`	Привязанные к странице вспомогательные элементы (метки реза, приводка)
`Background`	Водяные знаки, фоновые заливки, брендинг

Тег → перекрёстная ссылка на ISO 32000-2 §14.9

Утверждение	Пункт	reference_id (идентификатор ссылки)
Неструктурное содержимое, помеченное как артефакт, исключено из порядка чтения	PDF/UA-2 §8.3
Подтипы артефактов: pagination/layout/page/background	PDF/UA-2 §8.3
Реальное содержимое — в дереве структуры; артефакты — нет	PDF/UA-2 §8.2.4

Сопоставление с WCAG 2.2

Исключение декоративных служебных элементов из порядка чтения поддерживает выполнение Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) на уровне содержимого.

Положительный результат проверки на соответствие стандартам — это проверка, а не сертификация соответствия. Вывод о соответствии делает независимый проверяющий инструмент.

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

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

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

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

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

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

Создание артефактов и рисование содержимого имеют уровень caution; проверка на соответствие стандартам выполняется только для чтения. Ни одна из этих операций по умолчанию не является approval_required. См. /connect/hitl-risk-tiers/.

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

Эти инструменты не активируют шлюз, если операторское переопределение не повышает один из них до approval_required. Конверт и контракт одноразового токена описаны в /connect/hitl-risk-tiers/.

См. также

/cookbook/connect/aria-tagged-pdf/ — сопоставление ролей ориентиров.
/cookbook/connect/figure-caption/ — доступная группировка изображений.
/connect/tool-catalog/ — вычисление набора инструментов по уровням.
/connect/hitl-risk-tiers/ — модель риска и шлюз.