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/ — 各層級的工具集計算。