CSS 字体加载 API

CSS 字体加载 API 为你提供了动态加载字体资源的事件和接口。

概念和用法

在 CSS 中你可以使用 @font-face 规则下载字体，并使用 font-family 属性将字体应用于元素。但是，下载字体流程由客户端控制，大多数客户端仅会在首次需要该字体时才获取、加载该字体，这可能会导致明显的延迟。

CSS 字体加载 API 提供了控制和跟踪字体加载过程的能力，并允许你将其添加到 Document 或 Worker 的字体集中。将字体添加到 Document 或 Worker 的字体集中会让客户端在需要时自动获取、加载字体。字体可以在其被加入字体集之前或之后被加载，但是你必须先将字体添加到字体集，再将其用于绘图。

你可以通过为 FontFace 对象指定字体文件或 URL 字体源及其他属性来定义字体，其使用方式与 CSS @font-face 规则大致相同。FontFace 对象可以通过 Document.fonts 或 WorkerGlobalScope.fonts (en-US) 被添加到 Document 或 Web Worker 的 FontFaceSet 中。你可以使用 FontFace 或 FontFaceSet 对象下载字体，并监听加载完成事件。FontFaceSet 还可用于确定加载页面所需的所有字体以及文档布局何时完成。

FontFace.status 属性标识了字体加载状态：unloaded、loading、loaded 或 failed。此状态最初为 unloaded，下载文件或处理字体数据时为 loading，如果字体定义无效或无法加载字体数据则设置为 failed，成功获取（如果需要）并加载字体数据后，状态设置为 loaded。

1、定义字体

你可以使用 FontFace 构造函数 建字体，该函数有 3 个参数：字体家族、字体源和可选的描述符。这些参数与 @font-face 的参数一致。

其中，字体源可以是字体文件的 ArrayBuffer，也可以是 URL 指向的字体文件。请注意，URL 字体源需要使用 url() 函数包裹 URL。

const font = new FontFace("myfont", "url(myfont.woff)", {
  style: "italic",
  weight: "400",
  stretch: "condensed",
});

对于二进制字体，如果字体定义有效并且成功加载会把 FontFace.status 设置为 loaded，否则会设置为 failed。对于 URL 字体，字体有效，且未被加载时 FontFace.status 会被设置为 unloaded，若字体无效则设置为 failed。

2、向 Document 或 Worker 添加字体

你可以将字体添加到 Document 或 Worker 的 FontFaceSet 中，以允许客户端在需要时自动加载字体。你只能使用添加到 FontFaceSet 中的字体来渲染文本。

下面的代码显示如何添加字体到文档中。

// 定义字体
const font = new FontFace("myfont", "url(myfont.woff)", {
  style: "italic",
  weight: "400",
  stretch: "condensed",
});


// 把字体添加到 document.fonts（FontFaceSet）中
document.fonts.add(font);

3、加载字体

你可以通过调用 FontFace.load() 加载字体，或者通过调用 FontFaceSet.load() 加载已添加到 FontFaceSet 中的字体。注意，尝试加载已加载的字体不会生效。

以下代码演示如何定义字体并将其添加到 document 的字体中，然后加载字体。

// 定义字体
const font = new FontFace("myfont", "url(myfont.woff)");


// 把字体添加到 document.font（FontFaceSet）中
document.fonts.add(font);


// 加载字体
font.load();


// 等待到所有的字体都加载完毕
document.fonts.ready.then(() => {
  // 使用该字体渲染文字（如：在 canvas 中绘制）
});

注意，font.load() 返回一个 Promise，你可以通过调用 .then() 来处理字体加载的回调函数。在一些情况下，使用 document.fonts.ready 会更好，因为它会在文档布局完成且所有的字体都加载完成时触发。

4、示例

这是一个非常简单的示例，展示了从 Google Fonts 加载字体，并使用该字体在画布上绘制文本。并且该示例还会在字体创建和加载后，在文本框中打印字体状态的日志。

const canvas = document.getElementById("js-canvas");


// load the "Bitter" font from Google Fonts
const fontFile = new FontFace(
  "FontFamily Style Bitter",
  "url(https://fonts.gstatic.com/s/bitter/v7/HEpP8tJXlWaYHimsnXgfCOvvDin1pK8aKteLpeZ5c0A.woff2)",
);
document.fonts.add(fontFile);


fontFile.load().then(
  () => {
    // font loaded successfully!
    canvas.width = 650;
    canvas.height = 100;
    const ctx = canvas.getContext("2d");


    ctx.font = '36px "FontFamily Style Bitter"';
    ctx.fillText("Bitter font loaded", 20, 50);
  },
  (err) => {
    console.error(err);
  },
);

在 canvas 使用自定义字体必须等字体加载完成，否则将不生效。