通过 Connect 处理脚注引用与脚注正文模式

概览

通过 Connect 传输层生成脚注引用与脚注正文，使结构树包含 PDF 2.0 的脚注角色。行内标记会成为 footnote/endnote 引用，脚注文字则会成为注解正文，两者之间包含相互对应的回指引用。三种 HTML 形态会驱动相同输出：上标内的链接、明确的 ARIA role="doc-noteref"，以及 <aside class="footnote"> 正文容器。验证时会使用 Pro 层级 的无障碍工具。NextPDF 会通过 class_exists() 探测该工具；只有在服务器同一环境中同时安装了 nextpdf/premium 时，才会注册它。

无障碍工具通过只表示通过了一项无障碍检查，并不等同于独立的一致性认证。

安装

composer require nextpdf/server

通过 tools/list 调用确认 Pro 无障碍工具存在；请参阅 /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> — 明确的 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 角色，以及相互对应的回指引用。

边界情况与陷阱

有引用却没有正文（或有正文却没有引用）会被检查报告；每个引用都需要有对应的正文，反之亦然。
aria-describedby 与正文 id 之间的 id 不一致 会使这组配对无法解析（区分大小写）。
指向外部 URL 的上标锚点 会输出一般链接，而非脚注引用；如果目标是外部位置，请改用明确的角色。
没有 class/role 的纯 <aside> 会被视为地标，而不是注解正文。请加上 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 交叉引用

引用与正文使用 PDF 2.0 的 footnote/endnote 标准结构类型。相互对应的回指引用就是无障碍脚注的契约。

WCAG 2.2 对应

建立关联的脚注引用与正文，可在内容层级支持 WCAG 2.2 SC 1.3.1（信息与关联）以及 SC 2.4.1（略过区块）。

无障碍工具通过只表示通过了一项无障碍检查，并非一致性认证；该判定须由独立检查器作出。

商业情境

无障碍检查工具属于 Pro 层级，只有在服务器同一环境中同时安装了 nextpdf/premium 时才会注册。

Connect 专属细节

传输层可用性（MCP / REST / gRPC）

create_pdf、add_html 以及无障碍检查，都通过共用的工具执行器，在 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/ — 风险模型与确认关卡。