Connect 上的带标签 PDF 教程

Connect 上的带标签 PDF 教程

符合性边界（请先阅读）。 NextPDF 会生成带标签结构、替代文本，以及 PDF/UA-2 要求的元数据。这表示输出旨在符合 PDF/UA-2（ISO 14289-2）。但这 并不表示文件本身已经「符合」。只有独立的检查工具——以严格 PDF/UA-2 模式运行的 veraPDF——才能判定符合性。因此请将下文中每一处「PASS」、「conformant」或「compliant」的表述理解为「该文件旨在符合；结果由 veraPDF 判定」。

概览

在本教程中，你会在 Connect 传输层上编写一份带标签 PDF。你会启用标签模式、设置标题、加入具备语义结构的 HTML，然后使用标准检查工具与 veraPDF 验证结果。这里使用的标签模式工具和内容工具属于核心版。标准检查验证工具属于 Pro/Enterprise 级；只有在 nextpdf/premium 与服务器一并安装时，才会通过 class_exists() 注册。

安装

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" }
  }
}

请在第一次内容调用之前启用标签模式。写入器在输出第一页时会冻结模式，因此之后再开启，并不会回头为已输出的内容加上标签。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 风险等级

启用标签模式和使用内容工具属于 caution 等级。标准检查为只读。写入文件的输出路径需要经过批准，但 base64 模式不需要。请参阅 /connect/hitl-risk-tiers/.

确认闸的 JSON 信封

当写入文件的输出路径受到闸门控制时，闸门会返回一个质询信封和一个一次性令牌。该令牌会绑定到工具名称、一个 nonce，以及 300 秒的存活时间（TTL）。若要继续，请带上 arguments._confirmation_token 重新调用该工具。请参阅 /connect/hitl-risk-tiers/.

另请参阅

• /cookbook/connect/conformance-mode/ — 标签模式背后的模式判别器。
• /cookbook/connect/aria-tagged-pdf/ — 地标角色映射。
• /cookbook/connect/page-artifacts/ — 将装饰性内容从结构树中排除。
• /connect/tool-catalog/ — 各层级工具集的计算。