Руководство по тегированному PDF через Connect

Руководство по тегированному PDF через Connect

Граница соответствия (прочитайте это в первую очередь). NextPDF формирует тегированную структуру, альтернативный текст и метаданные, которые требуются PDF/UA-2. Благодаря этому результат предназначен для соответствия PDF/UA-2 (ISO 14289-2). Это само по себе не делает документ “соответствующим”. Соответствие определяет независимое средство проверки: veraPDF в строгом режиме PDF/UA-2. Каждую формулировку “PASS”, “conformant” или “compliant” ниже понимайте как “документ предназначен для соответствия; итог определяет veraPDF”.

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

В этом руководстве вы создадите тегированный файл Portable Document Format (PDF) через транспорты Connect. Вы включите тегированный режим, зададите заголовок, добавите семантический HTML и проверите результат с помощью инструмента проверки соответствия стандартам и veraPDF. Используемые здесь инструменты тегированного режима и работы с содержимым входят в ядро. Инструмент проверки соответствия стандартам относится к уровню Pro/Enterprise. Он регистрируется через class_exists() только если nextpdf/premium установлен вместе с сервером.

Установка

composer require nextpdf/server

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

Логическая структура вместе с указанием естественного языка делает содержимое доступным для навигации в порядке чтения (ISO 32000-2 §14.7). Запись /Alt содержит альтернативное описание для нетекстового содержимого (ISO 32000-2 §14.8). Содержимое должно быть отражено в дереве структуры, а соответствие определяет средство проверки (PDF/UA-2 §8.2.4). Когда вы пишете хорошо структурированный семантический HTML, конвейер создаёт корректную структуру за вас. Это руководство опирается на такой подход и не требует выстраивать структуру вручную.

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

Имена инструментов сверяются с текущим реестром через tools/list. Эталонный каталог — /connect/tool-catalog/. В этом руководстве количество инструментов не дублируется.

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

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

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

Включите тегированный режим до первого вызова добавления содержимого. Модуль записи фиксирует режим в момент формирования первой страницы. Если включить его позже, NextPDF не вернётся назад и не тегирует уже сформированное содержимое. Заголовок документа обязателен для PDF/UA-2, а тегированный режим задаёт для средства просмотра предпочтение отображать заголовок.

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

Добавьте семантический HTML. Конвейер сопоставляет с корректными типами структуры заголовки, списки, таблицы с <th scope>, ссылки и иллюстрации с alt:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

Затем выполните проверку соответствия PDF/UA-2 и запустите veraPDF --flavour ua2 для результата. Результат проверки и вердикт veraPDF — это оценки: они показывают, предназначен ли документ для соответствия. Соответствие определяет veraPDF, а не NextPDF.

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

• Тегированный режим включён после добавления содержимого. Любое содержимое, добавленное до включения режима, остаётся без тегов. Проверка сообщает об ошибке тегирования содержимого. Включайте режим сразу после создания документа.
• Информативное изображение без alt. Проверка сообщает об ошибке альтернативного текста иллюстрации. Укажите альтернативный текст или пометьте декоративное изображение как артефакт (/cookbook/connect/page-artifacts/).
• Пропущен уровень заголовка. Если пропустить уровень, например перейти с H1 на H3, это ошибка порядка заголовков. Понижайте уровень не более чем на один за раз.
• <th> без scope. Ячейка заголовка без связанных ячеек данных считается ошибкой структуры таблицы. Задавайте каждому <th> либо scope="col", либо scope="row".
• Отсутствует заголовок. Документ без заголовка считается ошибкой метаданных. Задавайте заголовок после включения тегированного режима.

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

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

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

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

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

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

Семантический HTML сопоставляется со стандартными типами структуры PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). Сопоставление выполняется автоматически. Ваша задача — писать семантический HTML.

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

Утверждение	Пункт	reference_id (идентификатор ссылки)
Логическая структура + язык → доступно для навигации в порядке чтения	ISO 32000-2 §14.7
Альтернативное описание, хранящееся в /Alt	ISO 32000-2 §14.8
Содержимое в дереве структуры; соответствие определяет средство проверки	PDF/UA-2 §8.2.4

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

Структура поддерживает WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1 и 2.4.6 на уровне содержимого. Как автор содержимого, вы по-прежнему отвечаете за авторские решения на уровне WCAG.

NextPDF создаёт результат, предназначенный для соответствия PDF/UA-2. Он не заявляет соответствие. Заключение о соответствии выносит veraPDF или другое средство проверки. Успешная проверка или прогон veraPDF — это свидетельство того, что результат предназначен для соответствия, а не сертификация со стороны NextPDF.

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

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

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

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

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

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

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

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

Когда путь вывода с записью в файл закрыт шлюзом, шлюз возвращает конверт запроса и одноразовый токен. Токен привязан к имени инструмента, одноразовому значению (nonce) и сроку жизни 300 секунд (time-to-live, TTL). Чтобы продолжить, повторно вызовите инструмент с arguments._confirmation_token. См. /connect/hitl-risk-tiers/.

См. также

• /cookbook/connect/conformance-mode/ — дискриминатор режима, лежащий в основе тегированного режима.
• /cookbook/connect/aria-tagged-pdf/ — сопоставление ролей ориентиров.
• /cookbook/connect/page-artifacts/ — исключение декоративного содержимого из дерева структуры.
• /connect/tool-catalog/ — вычисление набора инструментов по уровням.