API загрузки шрифтов CSS

API загрузки шрифтов CSS предоставляет события и интерфейсы для динамической загрузки ресурсов шрифтов.

Стили CSS позволяют авторам использовать пользовательские шрифты; для указания шрифтов для загрузки используется правило @font-face, а для их применения к элементам используется свойство font-family. Момент загрузки шрифта контролируется агентом пользователя. Большинство агентов загружают шрифты только тогда, когда они впервые нужны, что может привести к заметной задержке.

API загрузки шрифтов CSS преодолевает эту проблему, позволяя авторам контролировать и отслеживать, когда происходит загрузка шрифта, и когда он добавляется в набор шрифтов документа или рабочего потока. Добавление шрифта в набор шрифтов документа или рабочего потока позволяет агенту пользователя автоматически загружать соответствующий ресурс шрифта при необходимости. Шрифт можно загрузить до или после добавления его в набор шрифтов, но он должен быть добавлен в набор перед использованием для отображения текста.

Шрифты определяются в объектах FontFace, которые задают двоичный или URL-источник шрифта и другие свойства шрифта аналогично правилу CSS @font-face. Объекты FontFace добавляются в документ или рабочий поток с помощью Document.fonts и WorkerGlobalScope.fonts соответственно. Авторы могут инициировать загрузку шрифтов с помощью FontFace или FontFaceSet, а также отслеживать завершение загрузки. FontFaceSet дополнительно может использоваться для определения того, когда все шрифты, необходимые странице, загружены, и макет документа завершен.

Свойство FontFace.status указывает статус загрузки шрифта: unloaded, loading, loaded или failed. Этот статус изначально unloaded. Он устанавливается в loading при загрузке файла или обработке данных шрифта и в failed если определение шрифта некорректно или данные шрифта не могут быть загружены. Статус устанавливается в loaded когда данные шрифта успешно загружены (если это необходимо).

Шрифты создаются с помощью конструктора FontFace, который принимает в качестве параметров: семейство шрифтов, источник шрифта и необязательные описатели. Формат и грамматика этих аргументов аналогичны определению @font-face.

Источник шрифта может быть двоичными данными в ArrayBuffer или ресурсом шрифта по URL. Типичное определение шрифта с использованием URL-источника показано ниже. Обратите внимание, что функция url() требуется для URL-источников шрифтов.

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

Шрифты с двоичным источником автоматически загружаются, если определение шрифта корректно и данные шрифта могут быть загружены — FontFace.status устанавливается в loaded при успехе и failed в противном случае. Шрифты с URL-источником проверяются, но не загружаются автоматически — FontFace.status устанавливается unloaded если определение шрифта корректно и failed в противном случае.

Шрифты обычно добавляются в набор шрифтов документа или рабочего потока FontFaceSet, чтобы позволить агенту пользователя автоматически загружать шрифт при необходимости, и обязательно должны быть добавлены для использования шрифта при отображении текста.

В приведенном ниже коде показано добавление шрифта в документ.

// Define a FontFace
const font = new FontFace("my-font", "url(my-font.woff)", {
  style: "italic",
  weight: "400",
  stretch: "condensed",
});

// Add to the document.fonts (FontFaceSet)
document.fonts.add(font);

Шрифт можно загрузить вручную, вызвав FontFace.load(), или вызвав FontFaceSet.load(), если шрифт был добавлен в FontFaceSet. Обратите внимание, что попытка загрузить уже загруженный шрифт не имеет эффекта.

В приведенном ниже коде показано, как определить шрифт, добавить его к шрифтам документа и инициировать загрузку шрифта.

// Define a FontFace
const font = new FontFace("my-font", "url(my-font.woff)");

// Add to the document.fonts (FontFaceSet)
document.fonts.add(font);

// Load the font
font.load();

// Wait until the fonts are all loaded
document.fonts.ready.then(() => {
  // Use the font to render text (for example, in a canvas)
});

Обратите внимание, что font.load() возвращает промис, поэтому мы могли бы обработать завершение загрузки шрифта, используя then после этого. В некоторых случаях лучше использовать document.fonts.ready, так как он вызывается только тогда, когда все шрифты на странице были обработаны и макет завершён.

FontFace

Представляет собой отдельный шрифт.

FontFaceSet

Интерфейс для загрузки шрифтов и проверки их статуса загрузки.

FontFaceSetLoadEvent

Срабатывает при загрузке FontFaceSet.

Это очень простой пример, который демонстрирует загрузку шрифта из Google Fonts и его использование для отображения текста на холсте. Пример также регистрирует status сразу после создания и после загрузки.

HTML

Этот код определяет холст для рисования и текстовое поле для регистрации.

<canvas id="js-canvas"></canvas>
<textarea id="log" rows="3" cols="100"></textarea>

JavaScript

Сначала мы получаем элемент, в который будем регистрировать, и холст, который будет использоваться для отображения текста загруженным шрифтом.

const log = document.getElementById("log");

const canvas = document.getElementById("js-canvas");
canvas.width = 650;
canvas.height = 75;

Далее мы определяем FontFace с URL-источником, являющимся шрифтом Google Fonts, и добавляем его в document.fonts. Затем мы регистрируем статус шрифта, который должен быть unloaded.

const bitterFontFace = new FontFace(
  "FontFamily Bitter",
  "url(https://fonts.gstatic.com/s/bitter/v7/HEpP8tJXlWaYHimsnXgfCOvvDin1pK8aKteLpeZ5c0A.woff2)",
);
document.fonts.add(bitterFontFace);
log.textContent += `Bitter font: ${bitterFontFace.status}\n`; // > Bitter font: unloaded

Затем мы вызываем метод FontFace.load() для загрузки шрифта и ожидаем возвращенного промиса. После выполнения промиса мы регистрируем статус загрузки (который должен быть loaded) и отображаем текст загруженным шрифтом на холсте.

bitterFontFace.load().then(
  () => {
    log.textContent += `Bitter font: ${bitterFontFace.status}\n`; // > Bitter font: loaded

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

Обратите внимание, что мы также могли бы дождаться выполнения промиса, возвращаемого свойством FontFace.loaded, или FontFaceSet.ready.

Результат

Результат показан ниже. Он должен отобразить название шрифта, нарисованного на холсте загруженным шрифтом, и журнал, показывающий статус загрузки до и после загрузки.

Этот пример похож на предыдущий, за исключением того, что он использует FontFaceSet.load() для загрузки шрифта. Он также демонстрирует, как прослушивать события загрузки шрифта.

HTML

<canvas id="js-canvas"></canvas>
<textarea id="log" rows="25" cols="100"></textarea>

JavaScript

Код ниже определяет контекст холста для рисования текста, определяет семейство шрифтов и добавляет его в набор семейств шрифтов документа.

const log = document.getElementById("log");

const canvas = document.getElementById("js-canvas");
canvas.width = 650;
canvas.height = 75;
const ctx = canvas.getContext("2d");

const oxygenFontFace = new FontFace(
  "FontFamily Oxygen",
  "url(https://fonts.gstatic.com/s/oxygen/v5/qBSyz106i5ud7wkBU-FrPevvDin1pK8aKteLpeZ5c0A.woff2)",
);
document.fonts.add(oxygenFontFace);
log.textContent += `Oxygen status: ${oxygenFontFace.status}\n`;

Далее мы используем load() в наборе семейств шрифтов для загрузки шрифта, указав, какие шрифты загружать. Метод возвращает Promise. Если promise выполняется успешно, мы используем шрифт для отрисовки текста. Если он отклоняется, ошибка регистрируется.

document.fonts.load("36px FontFamily Oxygen").then(
  (fonts) => {
    log.textContent += `Bitter font: ${fonts}\n`; // > Oxygen font: loaded
    log.textContent += `Bitter font: ${oxygenFontFace.status}\n`; // > Oxygen font: loaded
    ctx.font = '36px "FontFamily Oxygen"';
    ctx.fillText("Oxygen font loaded", 20, 50);
  },
  (err) => {
    console.error(err);
  },
);

Вместо ожидания promise мы можем использовать события для отслеживания операции загрузки шрифта. Код ниже прослушивает события loading и loadingerror и регистрирует количество семейств шрифтов для каждого случая. В обработчике событий loadingdone мы дополнительно перебираем семейства шрифтов и регистрируем имена семейств.

document.fonts.addEventListener("loading", (event) => {
  log.textContent += `loading_event: ${event.fontfaces.length}\n`;
});
document.fonts.addEventListener("loadingerror", (event) => {
  log.textContent += `loadingerror_event: ${event.fontfaces.length}\n`;
});
document.fonts.addEventListener("loadingdone", (event) => {
  log.textContent += `loadingdone_event: ${event.fontfaces.length}\n`;
  event.fontfaces.forEach((value) => {
    log.textContent += `  fontface: ${value.family}\n`;
  });
});

Последний фрагмент кода демонстрирует, как можно отслеживать завершение загрузки шрифта с помощью promise, возвращаемого FontFaceSet.ready. В отличие от других механизмов, он возвращается, когда все шрифты, определенные в документе, загружены и верстка завершена.

Когда promise выполняется успешно, мы перебираем значения в семействах шрифтов документа.

document.fonts.ready.then(function () {
  log.textContent += `\nFontFaces in document: ${document.fonts.size}.\n`;

  for (const fontFace of document.fonts.values()) {
    log.textContent += "FontFace:\n";
    for (const property in fontFace) {
      log.textContent += `  ${property}: ${fontFace[property]}\n`;
    }
  }
});

Результат

Вывод ниже показывает текст, нарисованный шрифтом "Oxygen". Он также показывает логирование из событий и когда promise, возвращаемый document.fonts.ready, выполняется успешно.