在 Web 项目中集成 IBM Plex Sans Thai:安装、SCSS 定制与源码构建全指南

原创2026-09-22 21:13:26386 阅读
文章标签:设计系统

在 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 根据三份数据驱动生成:

  1. scripts/data/families.js:family 定义(名称、包名、是否有斜体、unicode 子集列表);
  2. scripts/data/weights.js:字重与 CSS 数值映射;
  3. 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 字体。

构建步骤

  1. 在 FontLab 中运行仓库根目录 scripts/ 下的 IBM Plex export FDK files.py 脚本(即 scripts/IBM Plex export FDK files.py),选择包含 IBM Plex .vfb 源文件的目录;
  2. 脚本会新建名为 fdk 的目录,并为每个字体创建子目录,导出 AFDKO 所需的中间文件;
  3. 在命令行中使用 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 编译的底层逻辑,让你在真实项目中既能“拿来即用”,也能按需改造、缩小字体加载体积。

登录后查看全文
plex