通过 Connect 将 ARIA 地标角色映射到标记式 PDF

概览

通过 Connect 传输层提交使用 HTML5 分段元素与 ARIA 地标角色的 HTML。标记内容管线会将这些内容映射到 PDF 2.0 标准结构类型，使辅助技术能够按地标而不是视觉位置浏览。此处使用的无障碍检查属于 Pro 层级：该工具通过 class_exists() 探测发现，且仅在 nextpdf/premium 与服务器一同安装时才会注册。PDF 创建与 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" → PDF 2.0 Aside 标准类型
<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 无障碍工具便不会注册，验证步骤会因未知工具错误而失败。

性能

元数据中的预算是一项文档层级的上限。地标映射属于正常版面排版流程的一部分。对于一般文档，它不会新增可单独测量的阶段。

安全性注意事项

除一般 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（信息与关系）及 SC 2.4.1（绕过区块）。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/ — 风险模型与关卡。