Шаблон ссылки и тела сноски в Connect

Кратко

Создавайте через Connect ссылки и тела сносок, чтобы дерево структуры содержало роли сносок PDF 2.0. Встроенный маркер становится ссылкой footnote/endnote, текст сноски — телом примечания, а между ними устанавливается взаимная обратная ссылка. Три формы HTML дают один и тот же результат: ссылка в надстрочном индексе, явная роль Accessible Rich Internet Applications (ARIA) role="doc-noteref" и контейнер тела <aside class="footnote">. Для проверки используется инструмент доступности уровня Pro. NextPDF обнаруживает его с помощью class_exists() и регистрирует только тогда, когда nextpdf/premium установлен вместе с сервером.

Успешный результат инструмента доступности — это проверка доступности, а не независимая сертификация соответствия.

Установка

composer require nextpdf/server

Проверьте наличие инструмента доступности Pro вызовом tools/list; см. /connect/tool-catalog/.

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

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

Конвейер распознаёт три формы:

<sup><a href="#fn-N">N</a></sup> — сокращённая запись “ссылка в надстрочном индексе”.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — явная роль Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA); aria-describedby передаётся как цель обратной ссылки.
<aside class="footnote" id="fn-N">…</aside> (или role="doc-footnote") — контейнер тела, который формируется как тело примечания с внутренней обратной ссылкой на соответствующую ссылку.

Поверхность 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": "Footnote Patterns", "language": "en" }
  }
}

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

Сформируйте обе ссылки и оба тела одним добавлением HTML, затем запустите проверку:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

Проверка доступности сообщает о связанных ролях reference/body и взаимных обратных ссылках.

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

Ссылка без тела (или тело без ссылки) выявляется проверкой; каждой ссылке нужно соответствующее тело и наоборот.
Несоответствие id между aria-describedby и id тела оставляет пару неразрешённой (с учётом регистра).
Якорь в надстрочном индексе на внешний URL формирует обычную ссылку, а не ссылку на сноску; для внешней цели используйте явную роль.
Пустой <aside> без class/role трактуется как ориентир, а не как тело примечания. Добавьте class="footnote" или role="doc-footnote".
Инструмент отсутствует. Без nextpdf/premium инструмент доступности Pro не регистрируется, поэтому проверка завершается ошибкой о неизвестном инструменте.

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

Бюджет в frontmatter задаёт документационный предел; сопоставление сносок выполняется в рамках обычного прохода по структуре.

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

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

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

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

Утверждение	Пункт	reference_id (идентификатор ссылки)
Типы структур footnote/endnote и связь reference/body	PDF/UA-2 §8.2.5
Ссылка на сноску связана со своим телом	PDF/UA-2 §8.2.5
Ссылка и тело достижимы через дерево структуры	PDF/UA-2 §8.2.4

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

Ссылка и тело используют стандартные типы структур footnote/endnote PDF 2.0. Взаимная обратная ссылка задаёт контракт доступной сноски.

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

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

Успешный результат инструмента доступности — это проверка доступности, а не сертификация соответствия; заключение о соответствии выносит независимый инструмент проверки.

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

Инструмент проверки доступности относится к уровню 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/figure-caption/ — вложенная структура Figure / Caption.
/connect/tool-catalog/ — расчёт набора инструментов по уровням.
/connect/hitl-risk-tiers/ — модель риска и шлюз.