# @cantoo/fontkit 中文文档

规范地址：https://npmcn.com/package/%40cantoo/fontkit/

版本：2\.0\.12
npm 元数据更新时间：2026-09-11T01:22:32.784Z
中文译文更新时间：2026-11-09T01:21:15.547Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：12.5 MB，207 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-09-09T16:24:02.457Z
- 最新版本发布：2026-09-11T01:22:32.593Z
- 近 30 天下载量：210917（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

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

## 安装

```sh
npm install @cantoo/fontkit
```

也可以使用：`pnpm add @cantoo/fontkit`、`yarn add @cantoo/fontkit`、`bun add @cantoo/fontkit`

## README

# 字体kit

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

此软件包作为 **`@cantoo/fontkit`**,保持原有的叉子 [foliojs/fontkit (法语)](https://github.com/foliojs/fontkit)。 。 。 .

## 有何改进 `@cantoo/fontkit`

与未保持的上游相比,这个分叉的用法是用来方便和更安全的:

-   **打开框中的脚本** - 用包打入船舶(无) `@types/fontkit`。公共 API 类型匹配运行时间( )`Subset.encode()` 正在同步, TTC/ DFont 收藏已输入, 默认导出工程 .
-   **以进口的方式工作** - 指定出口和实际违约出口(`import fontkit from '@cantoo/fontkit'` 编号 : `import * as fontkit`) (中文(简体) ).
-   **节点和浏览器已准备好** ——CJS + 无害环境管理,外加一个在unpkg / jsDelivr上的CDN UMD捆(包括精密).
-   **运行时惊喜减少** 修正WOFF/WOFF2变体、COLR/CBDT emoji相撞、cmap quirks、CFF子设定和若干成形/格氏边外壳.
-   **较丰富的衡量标准** ——更完整的字体和glyph度量平面用于布局.
-   **包含 Unicode 帮助** ——可选子路径导入而无需额外安装 :
    -   `@cantoo/fontkit/unicode-trie`
    -   `@cantoo/fontkit/unicode-properties`

## 特征

-   支持 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变换格子,允许对重量,宽度和其他轴进行几乎无限的设计控制.
-   字体子设置支持 - 创建一个只包含指定格言的新字体

## 安装

```
npm install @cantoo/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);
});

let buffer = subset.encode();
```

## API 密码

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

同步打开字体文件并返回 `Promise` 带有字体对象。 对于收藏字体(例如 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` - 如果这是斜体字体,应该从光标上取出与字体设计相匹配的角度
-   `lineHeight` - 文本相邻行(它们的基线)之间的垂直空间,也称为领导. 见 [这里](https://en.wikipedia.org/wiki/Leading) 更多细节.
-   `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` - 字体中的格子标识
-   `name` - 字体中的格言名称
-   `codePoints` - 由这个格言代表的一连串单码码点。 对于代表多个视觉字符的结接物和其他格子可以有多个代码点.
-   `path` - 代表glyph的矢量路径对象
-   `bbox` - glyph 的边框,即尽可能紧紧地将 glyph 轮廓接入的矩形.
-   `cbox` - Glyph的控制箱。 这往往与边框相同,但计算速度快. 由于比齐尔曲线的定义方式,一些控制点可以位于边框外. 何处 `bbox` 考虑到这一点, `cbox` 没有。 因此, `cbox` 准确度较低,但计算速度更快。 见 [这里](http://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html#section-2) 更详细描述.
-   `width` - glyph的宽度.
-   `height` - glyph的身高.
-   `advanceWidth` - glyph 的高级宽度.
-   `advanceHeight` - glyph的先行高度.
-   `leftBearing` - glyph的左侧方向.
-   `topBearing` - glyph的上侧轴.
-   `rightBearing` - glyph的右侧轴.
-   `bottomBearing` - 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.encode()`

回返a `Uint8Array` 包含已编码字体文件.

## 许可证

麻省理工学院

## 常见问题

### @cantoo/fontkit 是什么？

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

### 如何安装 @cantoo/fontkit？

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

### @cantoo/fontkit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cantoo/fontkit 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cantoo/fontkit 可以商用吗？

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

### @cantoo/fontkit 的下载量有多少？

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

### @cantoo/fontkit 还在维护吗？

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