通过 Connect 标记页面成品

概览

本配方通过 Connect 传输通道，将分页装饰元素（连续出现的页眉和页脚、页码、水印、背景）包裹到成品标记内容中。这些装饰元素仍会显示在页面上，但会保持在结构树与辅助技术阅读顺序之外。成品工具属于 Enterprise 层级：NextPDF 通过 class_exists() 探测发现该工具，且只有在服务器旁安装了 nextpdf/premium 时才会注册。此子类型使用类型化枚举（Pagination、Layout、Page、Background）。

若要验证，请使用 Enterprise 标准检查工具，它会依据 PDF/UA-2 生成报告。通过结果只表示该工具检查通过，并不等同于独立的符合性认证。

安装

composer require nextpdf/server

通过一次 tools/list 调用确认 Enterprise 成品工具是否存在。请参阅 /connect/tool-catalog/。

概念总览

不属于逻辑结构一部分的内容会被标记为成品，并从阅读顺序中排除（PDF/UA-2 §8.3）。成品是分页、版面配置、页面或背景内容，区别于真实内容（PDF/UA-2 §8.3）。真实内容会反映在结构树中，成品则不会（PDF/UA-2 §8.2.4）。

此工具会开启一段指定子类型的成品标记内容序列。在对应的关闭操作之前，你发出的任何绘制操作都会被包裹在其中。

API 接口

使用 tools/list 对照运行中的注册表来验证工具名称。权威目录是 /connect/tool-catalog/。本配方不重述工具数量。

代码示例 — 快速入门

开启一个 Background 成品，绘制水印，然后关闭它：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

代码示例 — 生产环境

每次开启都必须配对一次关闭，并验证页面不含任何孤立内容：

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

绘制页脚文字后，使用结束成品工具将其关闭，并依据 PDF/UA-2 执行标准检查。结构树必须只包含主体内容；水印和页脚必须被排除。

边界情况与陷阱

未知的子类型（例如 "Header"）会被拒绝。请传入 Pagination、Layout、Page、Background 其中之一。
在没有开启的情况下关闭会以深度为零的消息报错。请务必让开启与关闭成对出现。
在任何成品或结构上下文之前绘制会产生孤立内容，并导致结构规则失败。请先开启一个结构或成品上下文。
工具不存在。 若没有 nextpdf/premium，Enterprise 成品工具就不会被注册，调用会因未知工具错误而失败。

性能

front-matter 预算是文档级上限。成品包裹不会增加可单独测量的阶段。

安全性注意事项

除了一般的 Connect 传输指引之外，不适用其他内容。

符合性

PDF/UA-2 对应

子类型	使用情境
`Pagination`	连续 headers/footers、页码、导航装饰元素
`Layout`	尺规、分隔线、装饰性边框
`Page`	页面绑定的辅助元素（裁切标记、套准）
`Background`	浮水印、背景填色、品牌标识

标签 → ISO 32000-2 §14.9 对照

宣称	条款	reference_id
非结构性内容标记为成品，从阅读顺序中排除	PDF/UA-2 §8.3
成品子类型：pagination/layout/page/background	PDF/UA-2 §8.3
真实内容在结构树中；成品则不在	PDF/UA-2 §8.2.4

WCAG 2.2 对应

将装饰性元素从阅读顺序中排除，可在内容层面支持 WCAG 2.2 SC 1.3.1（信息和关系）。

通过的标准检查结果只是一项检查，并非符合性认证。该判定应由独立的检查工具做出。

商业上下文

成品工具属于 Enterprise 层级，只有在服务器旁安装了 nextpdf/premium 时才会注册。

Connect 细节

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

你可以通过 MCP tools/call、REST 工具端点与 gRPC 服务以相同方式调用这些工具，它们全部经由共用的工具执行器。

HITL 风险层级

发出成品与绘制内容属于警示层级；标准检查为只读。默认情况下，其中任何一个都不是 approval_required。请参阅 /connect/hitl-risk-tiers/。

确认闸门 JSON 信封

除非操作者通过覆写将其中某个工具提升为 approval_required，否则这些工具不会触发闸门。信封与一次性令牌契约记载于 /connect/hitl-risk-tiers/。

另请参阅

/cookbook/connect/aria-tagged-pdf/ — 地标角色对应。
/cookbook/connect/figure-caption/ — 无障碍图像分组。
/connect/tool-catalog/ — 各层级工具集的计算。
/connect/hitl-risk-tiers/ — 风险模型与闸门。