AST Explorer 定制图标字体指南:使用 Font Custom 为解析器分类构建专属 Web 图标字体

原创2026-10-14 17:22:091,409 阅读
文章标签:开发工具

AST Explorer 定制图标字体指南:使用 Font Custom 为解析器分类构建专属 Web 图标字体

本文聚焦 AST Explorer(astexplorer)前端中一套特殊的定制化基础设施——基于 Font Custom 将 SVG 矢量图批量编译为自托管 Web 图标字体(icon font)的完整流程。AST Explorer 支持数十种语言解析器,其工具栏需要为 GraphQL、Handlebars、Java、Rust 等语言类别展示专属 Logo 图标,而现成图标库(如 Font Awesome)无法覆盖这类小众需求。阅读本文后,你将掌握从安装 Font Custom、投放入口 SVG、执行编译、预览校验到在 React 组件与 CSS 中引用图标的完整实操链路,并理解 config.yml 中每一项字体配置对生成结果的影响。

为什么 AST Explorer 需要自定义字体

AST Explorer 是一个在浏览器中实时查看各种解析器生成 AST 的可视化工具,其语言类别(Category)覆盖 JavaScript、GraphQL、Handlebars、ICU、Java、OCaml、Reason、Rust、Scala 等。界面中的分类按钮需要为每种语言显示对应的 Logo 或图标。

当时主流图标方案 Font Awesome 并不支持针对字体本身的便捷定制(官方 wiki 中也没有令人满意的定制途径),因此项目引入了 Font Custom 目录下,与该工具配套的构建脚本则声明在 website/package.json 中。

工作区结构:一次字体编译的前后形态

在动手之前,先认识 website/fontcustom/ 目录下的关键文件及其角色:

文件/目录 角色
input-svg/ 待编译的 SVG 矢量图入口目录,是构建的唯一输入源
config.yml Font Custom 编译配置,决定字体名、选择器、输出位置、字体度量等
fontcustom.css 编译生成的图标字体 CSS(@font-face 与各图标类声明)
fontcustom-preview.html 自动生成的预览页,逐字展示全部 glyph 及对应类名/Unicode 码点
fontcustom_*.eot/ttf/woff/woff2/svg 编译产出的多格式字体文件,供不同浏览器按需加载

input-svg/ 目前收录了 8 个语言的官方 Logo:GraphQL_Logo.svg、handlebars.svg、icu.svg、java.svg、ocaml.svg、reason.svg、rust.svg、scala.svg。这些 SVG 来源各异(例如 java.svg 是 Illustrator 导出的矢量路径,handlebars.svg 则带有 Inkscape 命名空间),但 Font Custom 均能统一消化——这正是它优于手工抠图转字体的地方。

四步构建流程

原文档给出了从零到可用的构建步骤,这里结合仓库实际配置逐条展开。

第一步:安装 Font Custom

首先在开发机安装 Font Custom 命令行工具。它是一个依赖 Ruby、FontForge 等组件的命令行程序,安装方式请参考其官方安装文档(README 中给出的安装指引地址)。安装完成后可用 fontcustom --version 验证命令可用。

第二步:放入待编译的 SVG

把要转成图标字体的 SVG 文件放入 website/fontcustom/input-svg/ 目录。SVG 的文件名将直接决定生成图标类的类名:例如放入 myfoo.svg,编译后会得到 icon-myfoo 类;放入 GraphQL_Logo.svg,则生成 icon-GraphQL_Logo(见下文产物分析)。放入多个 SVG 即可一次编译出包含多个 glyph 的字体。

第三步:在项目根目录执行编译

在 AST Explorer 仓库根目录运行:

yarn run fontcustom

该命令实际由 website/package.json 中的 scripts 定义解析为:

fontcustom compile ./fontcustom/input-svg/ --config=./fontcustom/config.yml

即以 input-svg/ 为输入向量目录、以 config.yml 为配置文件执行 fontcustom compile。编译产物(字体文件、fontcustom.css、预览页)会按配置默认输出到工作目录中。

第四步:预览验证

运行:

open ./fontcustom/fontcustom-preview.html

(Linux 环境下可改用浏览器直接打开 website/fontcustom/fontcustom-preview.html。)该页面会以 12px 到 72px 十档字号渲染每个 glyph,并给出每个图标的类名与对应 Unicode 字符引用(如 .icon-GraphQL_Logo ↔ ),便于即时核对图形与命名是否符合预期。

引用图标:与 Font Awesome 几乎一致的用法

原文档给出了两种图标库的引用对比:

  • Font Awesome 写法:<i class="fa-html5 fa"></i>
  • Font Custom 写法:<i class="icon-myfoo"></i>(前提是已放入 myfoo.svg)

也就是说,你不需要 <img> 或背景图,只需在元素上挂一个以 icon- 前缀命名的类即可渲染图标。

AST Explorer 前端正是这样实践的。工具栏的分类按钮组件 CategoryButton.js 中维护了一张 categoryIcon 映射表,把语言分类 ID 对应到自定义图标类或 Font Awesome 类:

const categoryIcon = {
  'text/x-scala': 'icon-scala',
  css: 'fa-css3',
  graphql: 'icon-GraphQL_Logo',
  handlebars: 'icon-handlebars',
  htmlmixed: 'fa-html5',
  icu: 'icon-icu',
  java: 'icon-java',
  javascript: 'fa-jsfiddle',
  ocaml: 'icon-ocaml',
  reason: 'icon-reason',
  rust: 'icon-rust',
  sql: 'fa-database',
  webidl: 'fa-th-list',
  yaml: 'fa-yc',
};

渲染时图标元素被组装为 icon-* 与 fa fa-lg fa-fw 的组合类(见同文件第 38-44 行),分类下拉菜单的每个条目也复用同一张映射表(第 50-56 行)。由此可以清楚地看到:Font Custom 图标与 Font Awesome 图标在项目中是混用共存的,覆盖了 Font Awesome 无法提供的语言 Logo,而通用类图标(如 fa-code、fa-cog、fa-database)仍沿用 Font Awesome。

CSS 层面,website/css/style.css 通过 @import "../fontcustom/fontcustom.css"; 在全局样式表中引入了字体定义,因此所有组件都能直接使用 icon-* 类。

编译产物剖析:字体、CSS 与码点分配

以仓库当前已生成的产物为例,理解 Font Custom 到底产出了什么。

fontcustom.css 首先声明 @font-face,字体族名为 fontcustom,并依次列出 .eot(含 IE 的 ?#iefix)、.woff2、.woff、.ttf、.svg 五种格式的 src,随后是一个针对 WebKit 高像素密度场景的 SVG 字体回退块(第 17-22 行)。

接下来是图标类的核心声明(第 26-47 行):[data-icon]:before 使元素可通过 data-icon 属性直接书写字形,而 icon-GraphQL_Logo 等 8 个类则统一注入 font-family: "fontcustom" 与抗锯齿、文本修饰归一化等样式。每个图标类的字形码点落在 Unicode 私有使用区(PUA):

图标类 码点 输入 SVG
.icon-GraphQL_Logo \f100 GraphQL_Logo.svg
.icon-handlebars \f101 handlebars.svg
.icon-icu \f102 icu.svg
.icon-scala \f103 scala.svg
.icon-rust \f104 rust.svg
.icon-reason \f105 reason.svg
.icon-ocaml \f106 ocaml.svg
.icon-java \f107 java.svg

码点顺序与 input-svg/ 目录中的文件枚举顺序一一对应,由 Font Custom 自动分配。这些字形的实际渲染效果与类名、码点的对照关系,可以在 fontcustom-preview.html 的预览页中逐一确认(页面标题明确标注 "fontcustom contains 8 glyphs")。

值得一提的是,字体文件的打包也已被 webpack 覆盖:website/webpack.config.js 中,\.woff2? 由 url-loader 以内联阈值 10000 字节处理,\.(ttf|eot|svg) 交给 file-loader 输出为独立资源文件,确保 @import 进来的字体定义在构建后能正确解析到产物文件。

config.yml 配置项详解

website/fontcustom/config.yml 是一份带完整注释的 Font Custom 标准配置模板,当前全部配置项均处于注释状态(即使用默认值)。逐项解读如下。

项目信息类

配置项 默认值 说明
font_name icons 字体名称,同时决定生成模板文件的命名
css_selector .i-{{glyph}} CSS 选择器格式,{{glyph}} 会被替换为图标名
no_hash false 若为 true,生成字体时去掉防缓存哈希后缀
base64 false 若为 true,将 WOFF 字体以 base64 内嵌进生成的 CSS
force false 即使输入未变化也强制重新编译
debug false 输出可能有用处的调试信息
quiet false 隐藏状态提示信息

输入/输出位置

#input:
#  vectors: my/vectors        # SVG 输入目录
#  templates: my/templates    # 自定义模板目录
#output:
#  fonts: app/assets/fonts          # 字体输出目录
#  css: app/assets/stylesheets      # CSS 输出目录
#  preview: app/views/styleguide    # 预览页输出目录
#  my-custom-template.yml: path/to/template/output

注意:INPUT[:vectors] 与 OUTPUT[:fonts] 是必填项,其余可选;自定义模板的输出位置以"文件名作为键"的方式指定。AST Explorer 之所以能在 package.json 的脚本里用 ./fontcustom/input-svg/ 显式传入输入目录,正是因为向量输入目录也可以作为命令行参数覆盖。

模板与预处理器路径

#templates:
#- scss-rails
#- preview
#- my-custom-template.yml

#preprocessor_path: ../fonts/

templates 是一个 YAML 数组,列出随字体一起生成的文件;Font Custom 内置 preview、css、scss、scss-rails 等模板,默认同时生成 css 与 preview(这也解释了仓库中 fontcustom.css 与 fontcustom-preview.html 为何会成对出现)。自定义模板需放在 INPUT[:templates] 目录并按文件名引用。若使用 Rails/Compass 模板,还需通过 preprocessor_path 给出从 CSS 输出目录到字体输出目录的相对路径。

字体度量设置

#font_design_size: 16    # 字体设计尺寸(pica 点)
#font_em: 512            # em 尺寸,设置后整体缩放字体到该尺寸
#font_ascent: 448        # 上升部,用于计算基线
#font_descent: 64        # 下降部
#autowidth: false        # 若为 true,字形水平方向按各自矢量宽度贴合

这四个度量参数共同决定字形在 em 方框中的布局与基线位置,影响图标在行内垂直对齐的表现。对于以 Logo 为主的单色矢量图,保持默认值即可获得与 Font Awesome 一致的观感。

使用要点与注意事项

  1. 命名即类名:SVG 文件名直接决定 icon-* 类名,因此文件名应遵循项目既有风格(小写短横线,或如 GraphQL_Logo 这样的专有命名),并在投放前规划好,避免编译后再改名造成引用处连锁修改。
  2. 混用而非替代:Font Custom 图标只覆盖语言 Logo 这类 Font Awesome 缺失的图形,通用 UI 图标仍走 fa-* 体系,二者在 CategoryButton.js 中和平共处。
  3. 产物是编译结果:fontcustom.css、各格式字体文件与预览页均由编译生成,不要手工编辑;新增图标后应重新运行 yarn run fontcustom 让产物保持一致。
  4. 构建链路闭环:修改 input-svg/ 或 config.yml 后,编译、预览、webpack 打包三步即可完成从前端样式到构建产物的全链路更新,无需任何人工介入字体处理。
登录后查看全文
astexplorer