字体配置

← 注意事项与格式 | 批注修订 →

公文、合同等场景常依赖 仿宋、楷体、方正小标宋 等系统字体。OnlyOffice 静态 SDK 默认只内置部分字形；要让文档正确显示与导出，需要注册自定义字体。

本组件库通过 SDK 侧的 __custom_font_registry__ 完成注册（下文亦称 register font / 字体注册表），并配合 ttf-to-catalog-font.mjs 将 TTF/OTF 转为 OnlyOffice 可加载的 catalog 线格式。

字体文件须符合相关许可协议；请勿上传无授权的字形。

工作原理

TTF/OTF  ──ttf-to-catalog-font.mjs──►  fonts/{id}（无扩展名 catalog 线格式）
                                              ▲
__custom_font_registry__  ──AllFonts.js──►  __fonts_files / __fonts_infos
                                              │
                                         编辑器按别名解析文档内字体名

1. 将源字体编码为 public/packages/onlyoffice/9.4.0-develop/fonts/{id}（无扩展名）。
2. 在 AllFonts.js 的 window["__custom_font_registry__"] 中，用 {id} 作键、文档内出现的字体名为别名数组。
3. SDK 加载 AllFonts.js 时自动把 registry 同步进 __fonts_files / __fonts_infos，Word / Excel / Slide 三套管线按别名匹配。

步骤一：TTF/OTF 转为 catalog 线格式

脚本位置

将源字体放到脚本同目录（如 1001.ttf），或显式传入路径：

# 从同目录读取 1001.ttf → public/packages/onlyoffice/9.4.0-develop/fonts/1001
node public/packages/onlyoffice/9.4.0-develop/fonts/ttf-to-catalog-font.mjs --id 1001 --verify

# 指定源文件
node public/packages/onlyoffice/9.4.0-develop/fonts/ttf-to-catalog-font.mjs ./MyFont.ttf --id 1001 --verify

产物为 无扩展名 的 catalog 文件：

public/packages/onlyoffice/9.4.0-develop/fonts/1001

--verify 会解码校验线格式是否正确。脚本还会在控制台输出 __fonts_files 下标、__fonts_infos 行等维护提示。

常用参数

node .../ttf-to-catalog-font.mjs <input.ttf> --id <fileId> [--out <path>] [--verify]
node .../ttf-to-catalog-font.mjs --decode --id <fileId>   # 解码验证

• --id：与 fonts/ 下文件名、__custom_font_registry__ 的键一致（建议用数字字符串，如 "1001"，避免与内置索引冲突）。
• --out / --fonts-dir：输出目录，默认 public/packages/onlyoffice/9.4.0-develop/fonts/。
• --allfonts：指定 AllFonts.js 路径，编码后可自动 patch catalog 条目。

步骤二：在 __custom_font_registry__ 中注册别名

编辑：

public/packages/onlyoffice/9.4.0-develop/sdkjs/common/AllFonts.js

在文件中的 registry 对象里追加条目（本仓库已预置部分公文字体示例）：

window["__custom_font_registry__"] = {
  "1001": [
    "仿宋_GB2312",
    "FangSong_GB2312",
    "Slidefu",
    "Slidefu Regular",
    "演示佛系体",
  ],
  "1002": ["FZXiaoBiaoSong-B05S", "方正小标宋简体"],
  // ...
};

AllFonts.js 在 registry 定义之后会执行同步逻辑，将自定义 id 写入 __fonts_files 与 __fonts_infos，无需在业务代码里再调用单独的 registerFont() API。

别名怎么写

1. 用 Word 打开样例文档，查看「字体」面板中的显示名称。
2. 运行 ttf-to-catalog-font.mjs 时控制台会打印 TTF 内部 family 名，一并加入 aliases。
3. 同一字形在 Word / Excel / Slide 中名称可能不同，宁可多写别名，不要漏写。

步骤三：内置字体替换（可选）

SDK 内置字形通过 AllFonts.js 里 __fonts_files 的数字索引引用。若需替换某一内置字形：

1. 在 __fonts_files 数组中查到目标索引。
2. 将 catalog 线格式文件放到 public/packages/onlyoffice/9.4.0-develop/fonts/{索引号}（无扩展名）。

自定义字体优先使用 非数字或高位 id（如 1001、1002），避免与内置索引冲突。

验证清单

• fonts/{id} 文件存在且无扩展名，--verify 通过
• __custom_font_registry__ 的键与 {id} 一致
• 别名包含文档中出现的全部字体名
• 本地 pnpm dev 打开含该字体的文档，编辑区与导出文件字形一致
• 部署后静态资源路径与 STATIC_RESOURCE.onlyoffice.root 一致（可用 NEXT_PUBLIC_APP_ROOT 覆盖）

相关文件