透過 Connect 標記頁面成品

透過 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/ — 風險模型與閘門。