使用 Connect 输出带标题的无障碍 Figure

概览

通过 Connect 传输发送一个包含 <img> 和 <figcaption> 的 HTML <figure>。该流水线会输出一个 Figure 标准结构元素，将标题嵌套为 Caption 子元素，并使用 alt 属性填充 /Alt。验证步骤使用 Pro 级 无障碍工具。NextPDF 通过 class_exists() 发现该工具，并且仅当 nextpdf/premium 与服务器一同安装时才会注册它。文档创建和 HTML 摄取则使用核心工具。

无障碍工具给出的通过结果表示一次无障碍检查通过，而不是独立的合规认证。

安装

composer require nextpdf/server

通过一次 tools/list 调用确认 Pro 无障碍工具存在。参见 /connect/tool-catalog/。

概念概述

替代描述为图形等非文本内容提供文本说明（ISO 32000-2 §14.8）。该结构元素会将此描述保存在其 /Alt 条目中（ISO 32000-2 §14.8）。HTML alt 属性会填充所输出 Figure 上的 /Alt。该流水线会将 <figcaption> 输出为嵌套的 Caption 子元素，而不是同级段落，因此标题仍作为图形的一部分可被访问到（PDF/UA-2 §8.2.4）。

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": "Architecture Reference", "language": "en" }
  }
}

代码示例 — 生产环境

添加 figure 标记。要使该图形具备无障碍能力，alt 是必需的：

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

运行无障碍检查，并查看报告中的结构树。它会显示单个携带 /Alt 的 Figure，且恰好包含一个 Caption 子元素。

边界情况与注意事项

没有 alt 的 <img>。 该检查会报告图形替代文本失败。请提供描述性的 alt，或将纯装饰性图像标记为伪影（参见 /cookbook/connect/page-artifacts/）。
空的 <figcaption>。 该流水线会发出警告。请提供标题文本或移除该元素。
位于任何 <figure> 之外的 <figcaption>。 该流水线会将其输出为孤立标题。请将其包裹在 <figure> 中。
工具缺失。 如果没有 nextpdf/premium，Pro 无障碍工具不会注册，验证会因未知工具错误而失败。

性能

front-matter 预算是文档层面的上限。图形处理会作为正常布局过程的一部分运行。

安全说明

除通用的 Connect 传输指南外，没有其他适用事项。

合规性

PDF/UA-2 映射

声明	条款	reference_id
非文本内容的替代描述	ISO 32000-2 §14.8
保存在 `/Alt` 中的替代描述	ISO 32000-2 §14.8
可通过结构树访问标题	PDF/UA-2 §8.2.4

标签 → ISO 32000-2 §14.9 交叉引用

Figure 和 Caption 是标准结构类型。将 <figcaption> 嵌套为 Caption，即构成无障碍图形契约。

WCAG 2.2 映射

带有替代文本和关联标题的图形在内容层面支持 WCAG 2.2 SC 1.1.1（非文本内容）和 SC 1.3.1（信息与关系）。

无障碍工具给出的通过结果表示一次无障碍检查通过，而不是合规认证。该判定由独立的检查工具作出。

商业背景

无障碍检查工具属于 Pro 级，仅当 nextpdf/premium 与服务器一同安装时才会注册。

Connect 专项说明

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

你通过共享工具执行器在 MCP、REST 和 gRPC 上以完全相同的方式调用 create_pdf、add_html 和无障碍检查。

HITL 风险等级

文档创建和 HTML 摄取属于谨慎级别。无障碍检查是只读的。默认情况下，它们都不是 approval_required。参见 /connect/hitl-risk-tiers/。

确认门控 JSON 信封

除非操作员通过覆盖配置将某个工具提升为 approval_required，否则这些工具不会触发该门控。该信封和一次性令牌契约见 /connect/hitl-risk-tiers/。

另请参阅

/cookbook/connect/aria-tagged-pdf/：地标角色映射。
/cookbook/connect/aria-noteref-pattern/：脚注引用和正文角色。
/cookbook/connect/page-artifacts/：将装饰性图像标记为伪影。
/connect/tool-catalog/：按层级计算的工具集。