Создание доступного элемента Figure с подписью Caption через Connect

Кратко

Передайте HTML-элемент <figure> с <img> и <figcaption> через транспорты Connect. Конвейер создаёт стандартный структурный элемент Figure, вкладывает подпись как дочерний элемент Caption и использует атрибут alt для заполнения /Alt. Проверьте результат инструментом доступности уровня Pro. NextPDF обнаруживает этот инструмент через class_exists() и регистрирует его только если nextpdf/premium установлен вместе с сервером. Инструменты ядра отвечают за создание документа и приём HTML.

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

Установка

composer require nextpdf/server

С помощью вызова tools/list убедитесь, что инструмент доступности уровня Pro присутствует. См. /connect/tool-catalog/.

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

Альтернативное описание предоставляет текст для нетекстового содержимого, например для рисунка (ISO 32000-2 §14.8). Структурный элемент хранит это описание в записи /Alt (ISO 32000-2 §14.8). HTML-атрибут alt заполняет /Alt в создаваемом элементе Figure. Конвейер создаёт <figcaption> как вложенный дочерний элемент Caption, а не как соседний абзац, поэтому подпись остаётся доступной как часть рисунка (PDF/UA-2 §8.2.4).

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "Architecture Reference", "language": "en" }
  }
}

Пример кода — промышленная среда

Добавьте разметку рисунка. Атрибут alt обязателен, чтобы рисунок был доступным:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

Запустите проверку доступности, затем изучите возвращённое дерево структуры. В нём отображается один Figure с /Alt и ровно одним дочерним элементом Caption.

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

<img> без alt. Проверка сообщает об отсутствии альтернативного текста для рисунка. Укажите описательный alt или пометьте чисто декоративное изображение как артефакт (см. /cookbook/connect/page-artifacts/).
Пустой <figcaption>. Конвейер выдаёт предупреждение. Укажите текст подписи или удалите элемент.
<figcaption> вне какого-либо <figure>. Конвейер создаёт его как подпись без родительского элемента. Оберните его в <figure>.
Инструмент отсутствует. Без nextpdf/premium инструмент доступности уровня Pro не регистрируется, и проверка завершается ошибкой неизвестного инструмента.

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

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

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

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

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

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

Утверждение	Раздел	идентификатор ссылки (reference_id)
Альтернативное описание для нетекстового содержимого	ISO 32000-2 §14.8
Альтернативное описание хранится в `/Alt`	ISO 32000-2 §14.8
Подпись доступна через дерево структуры	PDF/UA-2 §8.2.4

Сопоставление тега с ISO 32000-2 §14.9

Figure и Caption — стандартные структурные типы. Вложение <figcaption> как Caption задаёт контракт доступного рисунка.

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

Рисунок с альтернативным текстом и связанной подписью соответствует Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.1.1 (нетекстовое содержимое) и SC 1.3.1 (информация и взаимосвязи) на уровне содержимого.

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

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

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

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

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

Вызывайте create_pdf, add_html и проверку доступности одинаково через Model Context Protocol (MCP), REST и gRPC, используя единый исполнитель инструментов.

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

Создание документа и приём HTML относятся к уровню осторожности. Проверка доступности работает только в режиме чтения. По умолчанию ни для одного из них не задано значение approval_required. См. /connect/hitl-risk-tiers/.

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

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

См. также

/cookbook/connect/aria-tagged-pdf/ — сопоставление ролей ориентиров.
/cookbook/connect/aria-noteref-pattern/ — роли ссылки на сноску и её текста.
/cookbook/connect/page-artifacts/ — пометка декоративных изображений как артефактов.
/connect/tool-catalog/ — вычисление набора инструментов по уровням.