透過 Connect 將 ARIA 地標角色對應至標記式 PDF

概覽

透過 Connect 傳輸層提交使用 HTML5 分段元素與 ARIA 地標角色的 HTML。標記內容管線會將其對應至 PDF 2.0 標準結構類型，讓輔助技術能依循地標，而不是視覺位置瀏覽。此處使用的無障礙檢查屬於 Pro 層級：該工具透過 class_exists() 探測發現，且僅在 nextpdf/premium 與伺服器一同安裝時才會註冊。文件建立與 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/ — 風險模型與關卡。