透過 Connect 處理註腳參照與註腳本文的模式

概覽

透過 Connect 傳輸層產生註腳參照與註腳本文，讓結構樹具備 PDF 2.0 的註腳角色。行內標記會成為 footnote/endnote 參照；註腳文字則成為註解本文，兩者之間會帶有互相對應的回向參照。有三種 HTML 形態會驅動相同的輸出：上標內的連結、明確的 ARIA role="doc-noteref"，以及 <aside class="footnote"> 本文容器。驗證時會使用 Pro 層級 的無障礙工具。NextPDF 會透過 class_exists() 探索此工具，而且只有在伺服器旁同時安裝 nextpdf/premium 時才會註冊。

無障礙工具通過代表完成一項無障礙檢查，並非獨立的相符性認證。

安裝

composer require nextpdf/server

透過 tools/list 呼叫確認 Pro 無障礙工具存在；請參閱 /connect/tool-catalog/。

概念概覽

PDF 2.0 定義了專屬的 footnote/endnote 結構類型，以及參照與其本文之間的關係（PDF/UA-2 §8.2.5）。註腳參照必須與其本文建立關聯（PDF/UA-2 §8.2.5），如此螢幕報讀器才能宣讀該參照，並循著連結讀取註解。參照與本文都必須可透過結構樹觸及（PDF/UA-2 §8.2.4）。

管線可辨識三種參照形態：

<sup><a href="#fn-N">N</a></sup> — 上標內連結的簡寫形式。
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — 明確的 DPUB-ARIA 角色；aria-describedby 會被轉送為回向參照的目標。
<aside class="footnote" id="fn-N">…</aside>（或 role="doc-footnote"）— 本文容器，會輸出為註解本文，並帶有指回對應參照的內部參照。

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": "Footnote Patterns", "language": "en" }
  }
}

程式碼範例 — 正式環境

在單次 HTML 加入動作中，同時輸出兩個參照與兩個本文，接著進行檢查：

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

無障礙檢查會回報成對的 reference/body 角色，以及彼此對應的回向參照。

邊界情況與陷阱

有參照卻沒有本文（或有本文卻沒有參照）會由檢查回報；每個參照都需要有對應的本文，反之亦然。
aria-describedby 與本文 id 之間的 id 不一致 會讓這組配對無法解析（區分大小寫）。
指向外部 URL 的上標錨點 會輸出一般連結，而非註腳參照；若目標是外部位置，請改用明確的角色。
沒有 class/role 的純 <aside> 會被視為地標，而非註解本文。請加上 class="footnote" 或 role="doc-footnote"。
工具不存在。 沒有 nextpdf/premium 時，Pro 無障礙工具不會被註冊，因此驗證會以「未知工具」錯誤失敗。

效能

前置資料中的預算是文件層級上限；註腳配對屬於一般結構處理流程的一部分。

安全性注意事項

除了一般的 Connect 傳輸層指引以外，並無其他適用內容。

相符性

PDF/UA-2 對應

主張	條款	reference_id
Footnote/endnote 結構類型與 reference/body 之間的關係	PDF/UA-2 §8.2.5
註腳參照與其本文建立關聯	PDF/UA-2 §8.2.5
參照與本文皆可透過結構樹觸及	PDF/UA-2 §8.2.4

標籤 → ISO 32000-2 §14.9 交叉參照

參照與本文使用 PDF 2.0 的 footnote/endnote 標準結構類型。互相對應的回向參照即是無障礙註腳的契約。

WCAG 2.2 對應

建立關聯的註腳參照與本文，在內容層級支援 WCAG 2.2 SC 1.3.1（資訊與關聯）以及 SC 2.4.1（略過區塊）。

無障礙工具通過代表完成一項無障礙檢查，並非相符性認證；該判定須由獨立檢查器作出。

商業情境

無障礙檢查工具屬於 Pro 層級，只有在伺服器旁同時安裝 nextpdf/premium 時才會註冊。

Connect 專屬細節

傳輸層可用性（MCP / REST / gRPC）

create_pdf、add_html 以及無障礙檢查，都會透過共用的工具執行器，在 MCP、REST 與 gRPC 上以相同方式呼叫。

HITL 風險層級

文件建立與 HTML 匯入屬於注意層級；無障礙檢查則為唯讀。預設情況下，沒有任何一個是 approval_required。請參閱 /connect/hitl-risk-tiers/。

確認關卡 JSON 封套

除非操作員以覆寫方式將其中之一提升為 approval_required，否則這些工具不會觸發關卡。封套與一次性權杖的契約記載於 /connect/hitl-risk-tiers/。

另請參閱

/cookbook/connect/aria-tagged-pdf/ — 地標角色對應。
/cookbook/connect/figure-caption/ — 巢狀的 Figure / Caption 結構。
/connect/tool-catalog/ — 各層級工具集的計算方式。
/connect/hitl-risk-tiers/ — 風險模型與關卡。