# @foliojs-fork/fontkit 中文文档

规范地址：https://npmcn.com/package/%40foliojs-fork/fontkit/

版本：1\.9\.2
npm 元数据更新时间：2024-03-07T14:25:24.773Z
中文译文更新时间：2026-11-15T04:06:06.722Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40foliojs-fork/fontkit
原文对照：https://npmcn.com/package/%40foliojs-fork/fontkit/?lang=original
项目主页：https://github.com/foliojs-fork/fontkit#readme
源码仓库：https://github.com/foliojs-fork/fontkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.4 MB，132 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：8 个
- 首次发布：2021-07-01T10:21:03.781Z
- 最新版本发布：2024-03-07T14:25:24.325Z
- 近 30 天下载量：7530084（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

节点和浏览器的高级字体引擎

## 安装

```sh
npm install @foliojs-fork/fontkit
```

也可以使用：`pnpm add @foliojs-fork/fontkit`、`yarn add @foliojs-fork/fontkit`、`bun add @foliojs-fork/fontkit`

## README

# 字体组合 [![npm](https://img.shields.io/npm/v/@foliojs-fork/fontkit.svg)](https://www.npmjs.com/package/@foliojs-fork/fontkit)

Fontkit是用于节点和浏览器的高级字体引擎,用于 [PDF Kit 软件](https://github.com/foliojs-fork/pdfkit)。它支持许多字体格式,高级的glyph替代和布局特性,glyph路径提取,彩色 emoji glyphs,字体子设置等等.

## 特征

-   Suports TrueType (.ttf), OpenType (.otf), WOFF, WOFF2, TrueType Collection (.ttc), 和 Datafork TrueType (.dfont) 字体文件
-   支持将字符映射到glyphs,包括支持粘结等高级替代(见下文)
-   支持读取glyph 度量衡并设置glyph,包括支持克宁等高级布局特性(见下文)
-   高级 OpenType 特性,包括甘油替代(GSUB)和定位(GPOS)
-   Apple Advance Typography (AAT) 甘油替代特性(morx表)
-   支持获取 glyph 矢量路径并将其转换为 SVG 路径, 或将其渲染为图形上下文
-   支持 TrueType (glyf) 和 PostScript (CFF) 大纲
-   支持彩色甘油(如emoji),包括苹果的SBIX表和微软的COLR表
-   支持AAT变换格子,允许对重量,宽度和其他轴进行几乎无限的设计控制.
-   字体子设置支持 - 创建一个只包含指定格言的新字体

## 为什么是叉子?

因为原来的repo已经不再维持,并且存在许多带有改进/修饰的PR.

此叉包含这些更改 :

-   [更新构建到 Bail 7](https://github.com/foliojs/fontkit/pull/196)
-   [修复贬值的用法新缓冲](https://github.com/foliojs/fontkit/pull/227)
-   [Mocha: 不存在字体报告为待决](https://github.com/foliojs/fontkit/pull/226)
-   [更新重组到 v2](https://github.com/foliojs/fontkit/pull/225)
-   移动到 [foliojs-fork/结构](https://github.com/foliojs-fork/restructure) (见 [为什么是叉子?](https://github.com/foliojs-fork/restructure#why-fork)(中文(简体) )
-   [GitHub 移动动作](https://github.com/foliojs-fork/fontkit/pull/4)
-   [修复诺托字体错误](https://github.com/foliojs/fontkit/pull/230)
-   将 brufs 软件包作为 devdependents 移动

## 安装

```
npm install @foliojs-fork/fontkit
```

## 示例

```javascript
var fontkit = require('fontkit');

// open a font synchronously
var font = fontkit.openSync('font.ttf');

// layout a string, using default shaping features.
// returns a GlyphRun, describing glyphs and positions.
var run = font.layout('hello world!');

// get an SVG path for a glyph
var svg = run.glyphs[0].path.toSVG();

// create a font subset
var subset = font.createSubset();
run.glyphs.forEach(function(glyph) {
  subset.includeGlyph(glyph);
});

subset.encodeStream()
      .pipe(fs.createWriteStream('subset.ttf'));
```

## API 密码

### `fontkit.open(filename, postscriptName = null, callback(err, font))`

同步打开字体文件,并用字体对象调用回调。 对于收藏字体(例如 TrueType 收藏文件),您可以通过 `postscriptName` 从收藏中取出字体而不是收藏对象.

### `fontkit.openSync(filename, postscriptName = null)`

同步打开字体文件,并返回字体对象。 对于收藏字体(例如 TrueType 收藏文件),您可以通过 `postscriptName` 从收藏中取出字体而不是收藏对象.

### `fontkit.create(buffer, postscriptName = null)`

返回给定缓冲器的字体对象。 对于收藏字体(例如 TrueType 收藏文件),您可以通过 `postscriptName` 从收藏中取出字体而不是收藏对象.

## 字体对象

根据字体格式的不同,有几种不同的字体对象通过字体kit返回. 他们都继承了 `TTFFont` 并且有同样的公共API, 描述如下.

### 元数据属性

下列属性是字符串(如果字体不包含字符串,则无效),描述字体,由字体创建者指定.

-   `postscriptName`
-   `fullName`
-   `familyName`
-   `subfamilyName`
-   `copyright`
-   `version`

### 计量

以下属性描述字体的一般度量. 见 [这里](http://www.freetype.org/freetype2/docs/glyphs/glyphs-3.html) 以很好地概括所有这些财产如何相互联系.

-   `unitsPerEm` - 字体内部坐标网格的大小
-   `ascent` - 该字体 [升华器](http://en.wikipedia.org/wiki/Ascender_\(typography\))
-   `descent` - 该字体 [递减器](http://en.wikipedia.org/wiki/Descender)
-   `lineGap` - 应包含行与行之间的间距
-   `underlinePosition` - 从应使用的正常下划线位置抵消
-   `underlineThickness` - 应使用的下划线的重量
-   `italicAngle` - 如果这是斜体字体,应该从光标上取出与字体设计相匹配的角度
-   `capHeight` - 基线以上大写字母的高度。 见 [这里](http://en.wikipedia.org/wiki/Cap_height) 更多细节.
-   `xHeight`\- 小写字母的高度。 见 [这里](http://en.wikipedia.org/wiki/X-height) 更多细节.
-   `bbox` - 字体的边框,即将字体中的所有格子都包含的框

### 其他属性

-   `numGlyphs` - 字体中的格言数
-   `characterSet` - 由字体支持的所有 unicode 代码点的阵列
-   `availableFeatures` - 一组所有 [OpenType 特性标记](https://www.microsoft.com/typography/otspec/featuretags.htm) (或被映射的 AAT 标记) 由字体支持(此描述见下文)

### 格氏映射的字符

Fontkit包含几种字符进行glyph映射的方法,包括支持先进的OpenType和AAT替代.

#### `font.glyphForCodePoint(codePoint)`

将单一的unicode代码点(数字)映射到Glyph对象. 不执行任何高级替代(没有上下文).

#### `font.hasGlyphForCodePoint(codePoint)`

返回给定的 Unicode 代码点字体中是否有格言 .

#### `font.glyphsForString(string)`

这种方法返回给定字符串的 Glyph 对象数组 。 这只是一个一对一的字符映射 给格莱弗斯。 对于大多数用途,你应该使用 `font.layout` (见下文),它提供了更先进的绘图 支持 AAT 和 OpenType 塑造 .

### Glyph 度量和布局

Fontkit包括了几种访问glyph度量和进行布局的方法,包括支持克宁等高级OpenType定位调整.

#### `font.widthOfGlyph(glyph_id)`

返回单个 glyph ID 的提前宽度( 上面描述) .

#### `font.layout(string, features = [] | {})`

此方法返回 a `GlyphRun` 对象,包括一组 `Glyph`s 和 `GlyphPosition`s 对于给定的字符串. `Glyph` 物体说明如下. `GlyphPosition` 对象包括4个属性 : `xAdvance`, (中文(简体) ), `yAdvance`, (中文(简体) ), `xOffset`, (中文(简体) ), 财务报告和审定财务报表 `yOffset`。 。 。 .

这个 `features` 参数是 [OpenType 特性标记](https://www.microsoft.com/typography/otspec/featuretags.htm) 将适用 除默认集外,或将 OpenType 特性映射到布尔启用或禁用每个特性。 如果这是AAT字体,OpenType特性标记被映射到AAT特性.

### 变形字体

Fontkit 支持 AAT 变异字体, glyphs 可以根据用户定义的设置调整其形状 各种轴,包括重量、宽度和斜面。 字体设计者为每个字体指定最小值、默认值和最大值 它们支持轴,并允许用户对已传送的文本进行精细的逐条控制.

#### `font.variationAxes`

返回描述可用变异轴的对象。 键为 4 个字母轴标记,值包括 `name`, (中文(简体) ), `min`, (中文(简体) ), `default`,以及 `max` 属性.

#### `font.namedVariations`

字体设计师可能选择了一些他们认为特别好看的变体,例如光线,常态, 粗体的重量 传统上是单独的字体 此属性返回描述这些命名变量的对象 设计者指定的示例。 键是变量名称,值是带有轴设置的对象.

#### `font.getVariation(variation)`

返回代表此变量的新字体对象,您可以从中获取glyphs并正常执行布局. 这个 `variation` 参数可以是变量设置对象,也可以是字符串变量名称. 变化设置对象 以轴名为按键,以数字为值(应在指定的范围内) `font.variationAxes`) (中文(简体) ).

### 其他方法

#### `font.getGlyph(glyph_id, codePoints = [])`

返回给定的glyph id 的 glyph 对象。 您可以通过这个glyph 代表的代码数组, 供您稍后使用, 它将被存储在glyph 对象中 .

#### `font.createSubset()`

返回此字体的子集对象, 描述如下 .

## 字体收藏对象

对于一个文件中包含多个字体的字体收藏文件,如TrueType Collection(.ttc)和Datafork TrueType(.dfont)文件,一个字体收藏对象可以被Fontkit还原.

### `collection.getFont(postscriptName)`

从收藏中以邮标名称获取字体。 返回上述字体对象.

### `collection.fonts`

此属性是收藏中所有字体的懒散数组.

## Glyph 对象

Glyph 对象代表字体中的glyph. 它们有各种属性,可以访问度量衡和glyph代表的实际矢量路径,以及将glyph渲染成图形上下文的方法.

您不直接创建 glyph 对象 。 它们是由上述字体对象上的各种方法所创造的. 基地有几个子类 `Glyph` 根据字体格式可以返回的内部分类,但它们都包括以下的 API.

### 属性

-   `id` - 字体中的格子标识
-   `codePoints` - 由这个格言代表的一连串单码码点。 对于代表多个视觉字符的结接物和其他格子可以有多个代码点.
-   `path` - 代表glyph的矢量路径对象
-   `bbox` - glyph 的边框,即尽可能紧紧地将 glyph 轮廓接入的矩形.
-   `cbox` - Glyph的控制箱。 这往往与边框相同,但计算速度快. 由于比齐尔曲线的定义方式,一些控制点可以位于边框外. 何处 `bbox` 考虑到这一点, `cbox` 没有。 因此, `cbox` 准确度较低,但计算速度更快。 见 [这里](http://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html#section-2) 更详细描述.
-   `advanceWidth` - glyph 的高级宽度.

### `glyph.render(ctx, size)`

按指定的字体大小将格子渲染到给定的图形上下文.

### 彩色甘油( 如 emoji)

Fontkit有几种不同颜色的emoji字体格式的支持. 目前,这些包括苹果的SBIX表(由"Apple Color Emoji"字体所使用)和微软的COLR表(由Windows 8.1支持). [给](http://blog.symbolset.com/multicolor-fonts) 是外出各种颜色字体格式的概述.

#### `glyph.getImageForSize(size)`

对于基于位图的SBIX glyphs,此返回一个包含图像的一些属性的对象,连同图像数据本身(通常是PNG).

#### `glyph.layers`

对于基于向量的COLR glyphs,此函数返回代表每层的glyphs和颜色的一系列对象,以渲染为序.

## 路径对象

路径对象由glyphs返回,并代表字体中每个glyph的实际向量轮廓. 路径可以被转换为SVG路径数据字符串,也可以被转换为可以应用来将路径转化为图形上下文的函数.

### `path.moveTo(x, y)`

将虚拟笔移动到给定的x,y坐标.

### `path.lineTo(x, y)`

从当前点到给定 x, y 坐标的路径中添加一行.

### `path.quadraticCurveTo(cpx, cpy, x, y)`

从当前点到给定 x 的路径中添加一个四相曲线,y 坐标使用 cpx, cpy 作为控制点.

### `path.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)`

将当前点到给定x的路径中加入贝塞尔曲线,y坐标使用cp1x,cp1y和cp2x,cp2y作为控制点.

### `path.closePath()`

通过将直线画回起点来关闭当前子路径.

### `path.toFunction()`

编译可使用图形上下文应用的 JavaScript 函数的路径,以渲染路径.

### `path.toSVG()`

将路径转换为 SVG 路径数据字符串.

### `path.bbox`

此属性代表路径的边框, 即包含整个路径形状的最小矩形 。 这是精确的边框,考虑到可能位于可见外形的控制点.

### `path.cbox`

此属性代表路径控制框 。 它就像边框,但它包括路径的所有点,包括比齐尔段的控制点. 计算速度要快于真正的边框,但如果在可见形状外有控制点,则准确性会更低.

## 子集

Fontkit可以执行字体子设置,即从现有字体中创建新字体的过程,其中只包含指定的格子. 这有利于缩小大字体的大小,例如在PDF生成中或用于网页.

目前子集产生为PDF嵌入而设计的最小字体,这些字体可能不作为独立文件工作. 它们没有可供单独使用的图表和其他基本表。 今后将取消这一限制.

您通过调用创建子集对象 `font.createSubset()`,上文介绍。 子集对象上的API如下.

### `subset.includeGlyph(glyph)`

包括子集中给定的glyph对象或glyph ID.

### `subset.encodeStream()`

回返a [流线](https://nodejs.org/api/stream.html) 包含可管道到目的的编码字体文件,例如文件.

## 许可证

麻省理工学院

## 常见问题

### @foliojs-fork/fontkit 是什么？

节点和浏览器的高级字体引擎

### 如何安装 @foliojs-fork/fontkit？

在项目目录运行 npm install @foliojs-fork/fontkit，或使用 pnpm add / yarn add / bun add。

### @foliojs-fork/fontkit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/foliojs-fork\_\_fontkit 是否存在。

### @foliojs-fork/fontkit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @foliojs-fork/fontkit 可以商用吗？

@foliojs-fork/fontkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @foliojs-fork/fontkit 的下载量有多少？

根据 npm 官方下载统计，@foliojs-fork/fontkit 在 2026/10/15 – 2026/11/13 这 30 天内被下载 7,530,084 次，日均约 251,003 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @foliojs-fork/fontkit 还在维护吗？

最新版本 1\.9\.2 发布于 2024/03/07（2 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/07/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。