使用 Connect 进行 CJK 竖排

概览

本示例通过 Connect 传输层嵌入含竖排度量的 CJK CIDFont。随后，引擎会在 CIDFont 字典中输出 PDF 2.0 竖排度量条目（/W2 为逐字形值，/DW2 为默认值），并渲染自上而下的字形堆叠。CJK 字体嵌入属于 Enterprise 等级。CJK 字体工具通过 class_exists() 探测发现，并且只有在服务器端同时安装 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 字体工具就不会注册，调用会以“未知工具”错误失败。

性能

frontmatter 中的预算是文档级上限。子集化会限制逐字形度量数组的大小。只有当某段竖排文本需要本会被子集丢弃的字形时，才禁用子集化。

安全性注意事项

除一般 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/ — 风险模型与门控。