在 Web 项目中集成 IBM Plex Sans Thai:安装、SCSS 定制与源码构建全指南
在 Web 项目中集成 IBM Plex Sans Thai:安装、SCSS 定制与源码构建全指南
本篇技术指南围绕 IBM Plex 开源字体家族中的泰语字体包 @ibm/plex-sans-thai 展开,完整覆盖从设备安装、npm 集成、CSS/SCSS 按需加载、字重(weight)精细化控制,到基于 FontLab + AFDKO 从 .vfb 源码重新构建字体的全流程,并结合本仓库(IBM Plex)的生成脚本与数据结构,讲解 SCSS/CSS 产物背后的实现原理。读完本文,你将能在前端项目中正确引入 IBM Plex Sans Thai、按需裁剪字重体积,并理解该字体包在仓库中的构建管线。
认识 IBM Plex Sans Thai 与它的包结构
IBM Plex Sans Thai 是 IBM 企业字体家族中面向泰文(Thai)脚本的 Sans 字体子集。在整个 IBM Plex 体系中,它由 Sans Thai 与 Sans Thai Looped 两个泰文变体组成(见 scripts/data/families.js 与 scripts/families.js 中的 type: 'Sans Thai'、packageName: 'plex-sans-thai' 定义),并且不包含 Italic 斜体(hasItalic: false),也不像拉丁扩展子集那样拆分为多段 unicode-range(unicodes: [])。
以本仓库 packages/plex-sans-thai/ 目录为例,该包的实体内容包括:
fonts/complete/:8 个字重 × 5 种格式(eot、otf、ttf、woff、woff2),文件命名形如IBMPlexSansThai-Bold.otf、IBMPlexSansThai-Regular.woff2;README.md、LICENSE.txt(OFL-1.1 开源字体许可)、telemetry.yml(遥测配置);package.json:npm 元信息,包名@ibm/plex-sans-thai,版本1.1.0(见 packages/plex-sans-thai/package.json)。
需要注意:仓库内的 scss/、css/ 目录是构建期由脚本生成的,但 package.json 的 files 字段已声明发布到 npm 时包含 css、scss、fonts/complete/woff/*、fonts/complete/woff2/*、telemetry.yml,即 npm 安装包内只提供 woff/woff2 两种 Web 字体格式,这正是文档强调的“因 NPM 包体积限制仅包含 woff2 与 woff”的原因。
获取字体:设备安装与 npm 安装
安装到本机设备
如需将 IBM Plex Sans Thai 安装到操作系统(如用于设计软件或桌面排版),请从项目的 releases 页面下载最新 zip 安装包,解压后按系统常规方式安装 otf/ttf 文件(packages/plex-sans-thai/fonts/complete/otf/ 与 ttf/ 目录下提供了全 8 个字重)。
通过 npm 安装用于 Web 开发
在 Node.js 环境下,安装命令为:
npm install @ibm/plex-sans-thai
安装完成后,node_modules 中即包含可直接引用的 woff/woff2 字体文件、预编译 CSS 以及 SCSS 模块。如果你不通过 npm 而是手动下载,请选择 releases 页面提供的 web zip,并将字体文件与 CSS/SCSS 保持原有目录结构,以保证 url() 引用能正确解析。
使用预编译 CSS 快速接入
包内通过编译 SCSS 产出了两份开箱即用的 CSS:
ibm-plex-sans-thai-all.css:引入全部 8 个字重;ibm-plex-sans-thai-default.css:仅引入默认字重(见下文“字重控制”)。
这份 CSS 由 scripts/compile-css.js 读取每个 family 的 scss/css-all.scss 与 scss/css-default.scss 编译生成(同时产出压缩版 .min.css),输出文件命名规则为 family.name.replace(/\s/g, '-').toLowerCase(),即 IBM Plex Sans Thai → ibm-plex-sans-thai。也就是说,包内 CSS 与字体文件的相对目录关系是构建期就固定好的,使用 CSS 时请保持包的目录结构原样,浏览器才能按 url() 找到 fonts/complete/woff 与 fonts/complete/woff2 下的字体文件。
SCSS 定制:控制字体路径、字重与产物体积
通过 $font-prefix 指定字体路径
当你的构建系统(如 Webpack、Vite、Gulp)需要把字体文件托管到自定义目录时,可以借助 SCSS 模块化配置。SCSS 入口默认把 $font-prefix 设为 '..'(相对自身目录),你可以通过 @use ... with (...) 覆盖它:
@use '@ibm/plex-sans-thai/scss' as PlexSansThai with (
$font-prefix: 'font-path'
);
@include PlexSansThai.all();
这里 $font-prefix 会被拼接到每个 @font-face 的 url() 前缀上,最终指向 ${font-prefix}/fonts/complete/woff2/xxx.woff2(参见 scripts/tools/index.js 中的 URL 模板构造逻辑)。由于泰文字体没有 split 子集,SCSS 生成的 @font-face 只引用 complete 目录下的 woff2/woff 文件。
两种引入粒度:all() 与 default()
SCSS 模块对外暴露两个 mixin:
PlexSansThai.all():引入全部可用字重;PlexSansThai.default():仅引入 light、regular、semibold 三个默认字重,适合对首屏体积敏感的页面。
说明:原 README 的字重表中
default()一列同时勾选了 bold,这与 README 正文“只导入 light、regular、semibold”的描述不一致。从生成脚本看,scripts/tools/index.js 中硬编码了fontWeightsListDefault = ['light', 'regular', 'semibold'],即实际实现以 light、regular、semibold 为准,表格中的 bold 勾选应视为文档笔误。
按需禁用(disable)字重
你可以在 @use 配置中通过 $font-weights map 把不需要的字重设为 false,从而进一步裁剪 CSS 体积:
// 禁用不需要的字重
@use '@ibm/plex-sans-thai/scss' as PlexSansThai with (
$font-weights: (
bold: false,
extralight: false,
light: false,
medium: false,
regular: false,
semibold: false,
text: false,
thin: false,
)
);
@include PlexSansThai.all();
该机制的原理位于 scripts/generate-scss.js 生成的入口 SCSS 中:$font-weights: () !default; 与内置权重 map map.merge 合并后,all()/default() 内部通过 tools.enabled($font-weights, 'weight') 判断每个字重是否开启,未开启的字重直接跳过 @font-face 生成(见 scripts/tools/index.js 的 enabled() 函数实现)。
底层实现链路
理解上述 SCSS 行为,有助于你在修改自定义字体包时举一反三。本仓库的 SCSS 并非手写,而是由 scripts/generate-scss.js 根据三份数据驱动生成:
- scripts/data/families.js:family 定义(名称、包名、是否有斜体、unicode 子集列表);
- scripts/data/weights.js:字重与 CSS 数值映射;
- scripts/tools/index.js:
createEntryScss、creatWeightScss等模板函数,负责拼出@font-face、all()/default()mixin 与权重开关逻辑。
生成的 SCSS 会写入 packages/<family>/scss/,随后 scripts/compile-css.js 用 sass 编译器产出 css/ 下的最终 CSS。而 scripts/generate-cdn.js 则会针对每个字重单独编译一份独立 CSS(如 cdn/sans-thai-bold.css),供 CDN 按需引入。泰文字体由于没有 Italic 与 unicode 拆分,其生成分支会走 hasItalic: false、unicodes: [] 的简化路径。
字重速查表与 font-family 规则
IBM Plex Sans Thai 共提供 8 个字重,SCSS 配置中的键名为小写形式。字重与 CSS font-weight 数值的映射以 scripts/data/weights.js 为准(Thai 不含 Italic,故只取其中非斜体条目):
| 字重(SCSS 键) | CSS font-weight | all() 是否引入 |
default() 是否引入 |
|---|---|---|---|
| bold | 700 | ✅ | ❌ |
| extralight | 200 | ✅ | ❌ |
| light | 300 | ✅ | ✅ |
| medium | 500 | ✅ | ❌ |
| regular | 400 | ✅ | ✅ |
| semibold | 600 | ✅ | ✅ |
| text | 450 | ✅ | ❌ |
| thin | 100 | ✅ | ❌ |
上表
default()列按生成脚本 scripts/tools/index.js 的实现整理(light/regular/semibold);如需完整对照原 README 表格可查看 packages/plex-sans-thai/README.md。
在 CSS 中声明字体族时使用:
font-family: 'IBM Plex Sans Thai';
该名称由 family 定义中的 name: 'IBM Plex Sans Thai' 写入每个 @font-face,SCSS 生成的 src 同时包含 local()(本地已安装字体名,如 IBM Plex Sans Thai Bold)与 url()(woff2 → woff 的回退顺序)两级来源。
从源码构建字体(FontLab + RoboFab + AFDKO)
如果你希望基于字体源文件(.vfb)重新导出二进制字体,仓库提供了完整工具链说明:
构建环境要求
- FontLab Studio 5:用于编辑与导出
.vfb源文件; - RoboFab 库:运行导出脚本所需;
- Adobe Font Development Kit for OpenType(AFDKO):用于生成 OpenType 字体。
构建步骤
- 在 FontLab 中运行仓库根目录
scripts/下的IBM Plex export FDK files.py脚本(即 scripts/IBM Plex export FDK files.py),选择包含 IBM Plex.vfb源文件的目录; - 脚本会新建名为
fdk的目录,并为每个字体创建子目录,导出 AFDKO 所需的中间文件; - 在命令行中使用 AFDKO 工具集中的
makeotf生成 OTF 或 TTF,具体用法参见makeotf -h。
整个流程从字体设计稿到 Web 字体(woff/woff2)的最终产物,正是通过仓库内的 gulp 构建任务(见 gulpfile.js 与 gulp-tasks/config.js)以及 packages/* 下的发布脚本串联起来的。
关于 IBM Telemetry 遥测
@ibm/plex-sans-thai 在安装时通过 postinstall 钩子(ibmtelemetry --config=telemetry.yml,见 packages/plex-sans-thai/package.json)运行 IBM Telemetry,用于收集去标识化、匿名化的指标数据。其配置位于 packages/plex-sans-thai/telemetry.yml:
version: 1:配置结构版本;projectId: 71c42c7f-0cc9-45ac-8f39-bdfebd13efdc:该项目在 IBM Telemetry 中的唯一标识;endpoint: https://www-api.ibm.com/ibm-telemetry/v1/metrics:上报端点;collect.npm.dependencies:本次采集范围为 npm 依赖信息。
将该包声明为依赖即视为同意遥测采集;如需退出采集,请参照 IBM Telemetry 官方文档中的 opt-out 说明(可通过环境变量或配置方式关闭,具体以官方文档为准)。
小结
围绕 @ibm/plex-sans-thai,本文完整覆盖了四条实用路径:安装到设备(releases zip)、npm 快速集成(预编译 CSS)、SCSS 深度定制($font-prefix 路径重定向、all()/default() 粒度控制、$font-weights 按需禁用)以及从源码重建字体(FontLab + RoboFab + AFDKO + makeotf)。同时结合仓库中的 scripts/data/weights.js、scripts/generate-scss.js、scripts/tools/index.js、scripts/compile-css.js 等源码,讲清了 SCSS 开关、@font-face 生成与 CSS 编译的底层逻辑,让你在真实项目中既能“拿来即用”,也能按需改造、缩小字体加载体积。