Сопоставление ориентирующих ролей ARIA с тегированным PDF с помощью Connect

Кратко

Передайте через Connect HTML, в котором используются секционирующие элементы HTML5 и ориентирующие роли Accessible Rich Internet Applications (ARIA). Конвейер тегированного содержимого сопоставляет их со стандартными типами структуры PDF 2.0, поэтому вспомогательные технологии могут перемещаться по ориентирам, а не по визуальной компоновке. Используемая здесь проверка доступности относится к уровню Pro: инструмент обнаруживается проверкой class_exists() и регистрируется только тогда, когда nextpdf/premium установлен рядом с сервером. Для создания документа и приёма HTML используются базовые инструменты.

Инструмент контроля доступности сообщает о проблемах, выявленных по PDF/UA-2 (ISO 14289-2). Успешный результат — это собственная оценка инструмента. Это контроль доступности, а не независимая сертификация соответствия. Соответствие определяет veraPDF или другой инструмент проверки.

Установка

composer require nextpdf/server

С помощью вызова tools/list убедитесь, что инструмент контроля доступности уровня Pro присутствует в работающем развёртывании (см. /connect/tool-catalog/). Если его нет, значит nextpdf/premium не установлен в этом развёртывании, поэтому шаг проверки из этого рецепта выполнить нельзя.

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

Группирующие структурные элементы организуют логическую структуру документа в разделы и подобные контейнеры (ISO 32000-2 §14.8). Конвейер HTML сопоставляет эти элементы:

<aside> и role="complementary" → Aside, стандартный тип PDF 2.0
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Нестандартный тип структуры допустим только тогда, когда он сопоставлен по роли со стандартным типом (PDF/UA-2 §8.2.5). Конвейер сразу выдаёт стандартный тип, поэтому ручное сопоставление ролей не требуется. Содержимое должно отражаться в дереве структуры, чтобы вспомогательные технологии могли получить к нему доступ (PDF/UA-2 §8.2.4).

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

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

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

Создайте тегированный документ PDF 2.0, добавьте HTML с ориентирующими ролями и проверьте его, выполнив последовательность запросов MCP tools/call:

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

Подключите эмиттер тегированного содержимого перед добавлением любого HTML. Создайте документ с заданным языком, чтобы эмиттер был активен уже при первом добавлении содержимого.

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

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

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

Ответ проверки возвращает наблюдаемое дерево структуры и сводку выявленных проблем по PDF/UA-2. И <aside>, и <div role="complementary"> преобразуются в один и тот же стандартный тип Aside.

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

Тегированный вывод не активирован до добавления содержимого. Если документ не был создан с заданным языком / тегированным режимом, первое добавление HTML создаёт нетегированное содержимое, и проверка сообщает о сбое тегированного содержимого. Пересоздайте документ с заданным языком.
Конфликтующая роль на секционирующем элементе (<aside role="navigation">) приводит к предупреждению. Удалите конфликтующую роль или используйте <div>.
Инструмент отсутствует. Без nextpdf/premium инструмент контроля доступности уровня Pro не регистрируется, и шаг проверки завершается ошибкой о неизвестном инструменте.

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

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

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

Помимо общего правила транспорта Connect, дополнительных рекомендаций нет: не записывайте содержимое документа или тело HTML в журнал на уровне журналирования, данные которого отправляются наружу.

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

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

HTML	Стандартный тип PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

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

Утверждение	Пункт	reference_id (идентификатор ссылки)
Группирующие элементы организуют логическую структуру в разделы	ISO 32000-2 §14.8
Нестандартные типы требуют сопоставления по роли со стандартным типом	PDF/UA-2 §8.2.5
Содержимое должно быть достижимо через дерево структуры	PDF/UA-2 §8.2.4

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

Навигация по ориентирам поддерживает WCAG 2.2 SC 1.3.1 (Info and Relationships) и SC 2.4.1 (Bypass Blocks) на уровне содержимого. Формат PDF передаёт структуру. Автор содержимого по-прежнему отвечает за решения по контенту на уровне WCAG.

Успешный результат инструмента контроля доступности — это проверка доступности, а не сертификация соответствия. Соответствие PDF/UA-2 определяет независимый инструмент проверки (например, veraPDF).

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

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

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

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

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

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

Создание документа и приём HTML относятся к уровню предостережения (автоматическое выполнение, запись в журнал аудита). Контроль доступности работает только на чтение. Ни один из этих инструментов по умолчанию не имеет approval_required. См. /connect/hitl-risk-tiers/.

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

Эти инструменты не запускают шлюз, кроме случая, когда переопределение конфигурации оператором повышает один из них до approval_required. При срабатывании шлюза конверт запроса-подтверждения и контракт одноразового токена соответствуют /connect/hitl-risk-tiers/.

См. также

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