透過 Connect 產生含 Caption 的無障礙 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
可透過結構樹存取的 Caption	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（Non-text Content）與 SC 1.3.1（Info and Relationships）。

無障礙工具通過代表的是一項無障礙檢查結果，並非符合性認證。該判定由獨立的檢查工具做出。

商業情境

無障礙檢查工具屬於 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/ — 各層級工具集的運算。