透過 Connect 處理 CJK 直書

概覽

本範例透過 Connect 傳輸層嵌入含直書度量的 CJK CIDFont。接著引擎會在 CIDFont 字典上輸出 PDF 2.0 的直書度量項目（/W2 為逐字符值，/DW2 為預設值），並算繪由上而下的字符堆疊。CJK 字型嵌入屬於 Enterprise 等級。系統會透過 class_exists() 探測來發現 CJK 字型工具，且只有在伺服器旁安裝了 nextpdf/premium 時才會註冊。只有當作用中的 CID 編碼為直書 Identity 編碼時，引擎才會輸出直書度量；橫書文字段不受影響。

安裝

composer require nextpdf/server

呼叫 tools/list，確認 Enterprise CJK 字型工具已就緒。請參閱 /connect/tool-catalog/.

概念總覽

在直書模式下，CIDFont 會使用 /W2（逐字符）與 /DW2（預設）直書度量（ISO 32000-2 §9.7）。CMap 會選擇橫書或直書模式（ISO 32000-2 §9.7），而直書模式會將字符前進量移至垂直軸（ISO 32000-2 §9.7）。當你註冊字型時，管線會剖析該字型的直書度量表格；只有在你選取直書 CID 編碼後，才會輸出這些字典項目。

API 介面

使用 tools/list 對照執行中的登錄檔，驗證工具名稱。正式目錄請見 /connect/tool-catalog/. 本範例不再重述工具數量。

程式碼範例 — 快速上手

建立文件、註冊 CJK 字型，並選取直書編碼：

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_cjk_font",
    "arguments": {
      "document_id": "<id>",
      "family": "NotoSansCJKjp",
      "source": "/usr/share/fonts/opentype/noto/NotoSansCJKjp-Regular.otf",
      "subset": true
    }
  }
}

程式碼範例 — 生產環境

選取直書編碼、設定字型、寫入一段直書文字，接著輸出並檢視 CIDFont 字典：

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "set_cid_encoding",
    "arguments": { "document_id": "<id>", "font_key": "NotoSansCJKjp", "encoding": "/Identity-V" }
  }
}

輸出的 CIDFont 字典會帶有 /W2 與 /DW2。同一份來源若以橫書編碼算繪，這兩個項目都會省略。唯一差異是編碼閘；也正因如此，此處的 structural 可重現性設定檔才名實相符。

邊界案例與注意事項

字型缺少直書度量表格。 字型工具會提出警告。請挑選隨附這些表格的 CJK 字型；僅含拉丁字的字型不會有這些表格。
在沒有直書度量的字型上選取直書編碼 屬於錯誤。請改回橫書編碼，或挑選另一款字型。
在橫書編碼作用中時請求直書文字 屬於錯誤。請在首次輸出直書文字之前選取直書編碼。
在首次輸出文字之後切換編碼 會以「編碼已凍結」錯誤遭到拒絕。請在註冊字型後立即設定編碼。
工具不存在。 若沒有 nextpdf/premium，Enterprise CJK 字型工具便不會註冊，呼叫會以「未知工具」錯誤失敗。

效能

前置資料中的預算是文件層級上限。子集化會限制逐字符度量陣列的大小。只有當某段直書文字需要子集化會捨棄的字符時，才停用子集化。

安全性注意事項

除一般 Connect 傳輸層指引外，沒有其他適用事項。

符合性

主張	條款	reference_id
直書 CIDFont 使用 `/W2` 與 `/DW2` 度量	ISO 32000-2 §9.7
CMap 會選擇橫書或直書模式	ISO 32000-2 §9.7
直書模式會在垂直軸上推進字符	ISO 32000-2 §9.7

輸出直書度量項目，就是對所引用條款的實作。這並非全面性的符合性主張。整份文件是否符合，則由驗證器判定。

商業脈絡

CJK 字型嵌入屬於 Enterprise 等級；CJK 字型工具僅在伺服器旁安裝了 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/font-typography/ — 橫書文字與字型選取基礎。
/cookbook/connect/conformance-mode/ — 直書 CJK 文字段仍需加上標記，才能符合 PDF/UA-2。
/connect/tool-catalog/ — 各等級工具集的計算方式。
/connect/hitl-risk-tiers/ — 風險模型與閘門。