DieCSS Font Loading API bietet Ereignisse und Schnittstellen zum dynamischen Laden von Schriftarten-Ressourcen.

Konzepte und Verwendung

CSS Stylesheets ermöglichen es Autoren, benutzerdefinierte Schriftarten zu verwenden; indem sie Schriftarten zum Herunterladen mit der@font-face-Regel spezifizieren und diese mit derfont-family-Eigenschaft auf Elemente anwenden. Der Zeitpunkt, zu dem eine Schriftart heruntergeladen wird, wird vom Benutzeragenten gesteuert. Die meisten Agenten laden Schriftarten erst herunter, wenn sie das erste Mal benötigt werden, was zu einer wahrnehmbaren Verzögerung führen kann.

Die CSS Font Loading API überwindet dieses Problem, indem sie Autoren die Kontrolle überlässt und sie nachverfolgen lässt, wann ein Schriftschnitt geladen wird und wann er zu der Schriftschnittmenge des Dokuments oder Arbeiters hinzugefügt wird. Das Hinzufügen eines Schriftschnitts zur Dokumentschriftmenge oder zur Arbeiterschriftmenge ermöglicht es dem Benutzeragenten, die zugehörige Schriftartressource bei Bedarf automatisch zu laden. Ein Schriftschnitt kann entweder vor oder nach dem Hinzufügen zu einer Schriftschnittmenge geladen werden, aber ermuss zur Menge hinzugefügt werden, bevor er zum Zeichnen verwendet werden kann.

Schriftschnitte werden inFontFace-Objekten definiert, die eine binäre Schriftquelle oder eine URL und andere Eigenschaften der Schriftart auf ähnliche Weise spezifizieren wie die CSS-Regel@font-face.FontFace-Objekte werden dem Dokument oder dem ArbeiterFontFaceSet mitDocument.fonts undWorkerGlobalScope.fonts hinzugefügt. Autoren können den Download von Schriftarten entweder mitFontFace oderFontFaceSet auslösen und den Abschluss des Ladevorgangs überwachen.FontFaceSet kann auch verwendet werden, um festzustellen, wann alle von einer Seite benötigten Schriftarten geladen sind und das Layout des Dokuments abgeschlossen ist.

DieFontFace.status-Eigenschaft zeigt den Ladezustand des Schriftschnitts an:unloaded,loading,loaded oderfailed. Dieser Status ist anfänglichunloaded. Er wird aufloading gesetzt, wenn die Datei heruntergeladen oder die Schriftdaten verarbeitet werden, und auffailed, wenn die Schriftdefinition ungültig ist oder die Schriftdaten nicht geladen werden können. Der Status wird aufloaded gesetzt, wenn die Schriftdaten erfolgreich abgerufen (falls erforderlich) und geladen wurden.

Definieren eines Schriftschnitts

Schriftschnitte werden mit demFontFace Konstruktor erstellt, der als Parameter die Schriftfamilie, die Schriftquelle und optionale Deskriptoren erhält. Das Format und die Grammatik dieser Argumente entsprechen der äquivalenten@font-face-Definition.

Die Schriftquelle kann entweder binäre Daten in einemArrayBuffer oder eine Schriftressource unter einer URL sein. Eine typische Definition eines Schriftschnitts mit einer URL-Quelle könnte wie unten gezeigt aussehen. Beachten Sie, dass dieurl()-Funktion für URL-Schriftquellen erforderlich ist.

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

Schriftschnitte mit einerbinären Quelle werden automatisch geladen, wenn die Schriftdefinition gültig ist und die Schriftdaten geladen werden können —FontFace.status wird bei Erfolg aufloaded und andernfalls auffailed gesetzt. Schriftschnitte mit einer URL-Quelle werden validiert, aber nicht automatisch geladen —FontFace.status wird aufunloaded gesetzt, wenn die Schriftschnittdefinition gültig ist und andernfalls auffailed.

Hinzufügen einer Schrift zu einem Dokument oder Arbeiter

Schriftschnitte werden normalerweise dem Dokument oder ArbeiterFontFaceSet hinzugefügt, um dem Benutzeragenten zu ermöglichen, die Schrift bei Bedarf automatisch zu laden, undmüssen hinzugefügt werden, damit die Schrift zum Rendern von Text verwendet werden kann.

Der Code unten zeigt, wie ein Schriftschnitt dem Dokument hinzugefügt wird.

// Define a FontFaceconst 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);

Laden einer Schrift

Ein Schriftschnitt kann manuell durch Aufrufen vonFontFace.load() oder durch Aufrufen vonFontFaceSet.load() geladen werden, wenn der Schriftschnitt demFontFaceSet hinzugefügt wurde. Beachten Sie, dass das Laden einer bereits geladenen Schrift keine Wirkung hat.

Der Code unten zeigt, wie man einen Schriftschnitt definiert, ihn zu den Dokumentenschriftarten hinzufügt und dann einen Schriftladevorgang initiiert.

// Define a FontFaceconst font = new FontFace("my-font", 'url("my-font.woff")');// Add to the document.fonts (FontFaceSet)document.fonts.add(font);// Load the fontfont.load();// Wait until the fonts are all loadeddocument.fonts.ready.then(() => {  // Use the font to render text (for example, in a canvas)});

Beachten Sie, dassfont.load() ein Promise zurückgibt, sodass wir den Abschluss des Schriftladevorgangs durch anschließendes Ketten vonthen handhaben könnten. Die Verwendung vondocument.fonts.ready kann in einigen Fällen besser sein, da dies nur aufgerufen wird, wenn alle Schriftarten im Dokument gelöst wurden und das Layout abgeschlossen ist.

Schnittstellen

FontFace

Repräsentiert einen einzigen verwendbaren Schriftschnitt.

FontFaceSet

Eine Schnittstelle zum Laden von Schriftschnitten und Überprüfung ihres Download-Status.

FontFaceSetLoadEvent

Wird ausgelöst, wann immer einFontFaceSet geladen wird.

Beispiele

Einfaches Schriftladen

Dies ist ein sehr einfaches Beispiel, das zeigt, wie eine Schrift von Google Fonts geladen und zum Zeichnen von Text auf einem Canvas verwendet wird. Das Beispiel protokolliert außerdem denstatus unmittelbar nach der Erstellung und nach dem Laden.

HTML

Dieser Code definiert ein Canvas zum Zeichnen und ein Textbereich zum Protokollieren.

<canvas></canvas><textarea rows="3" cols="100"></textarea>

JavaScript

Zuerst holen wir uns das Element, in das wir protokollieren werden, und das Canvas, das zum Rendern von Text in der heruntergeladenen Schrift verwendet wird.

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

Als nächstes definieren wir eineFontFace, die eine URL-Quelle ist, die eine Google-Schriftart darstellt, und fügen siedocument.fonts hinzu. Wir protokollieren dann den Schriftstatus, derunloaded sein sollte.

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

Dann rufen wir die MethodeFontFace.load() auf, um den Schriftschnitt zu laden, und warten auf das zurückgegebene Promise. Sobald das Promise aufgelöst wird, protokollieren wir den geladenen Status (derloaded sein sollte) und zeichnen Text in der geladenen Schrift auf das Canvas.

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);  },);

Beachten Sie, dass wir ebenso auf das Promise warten konnten, das durch die EigenschaftFontFace.loaded zurückgegeben wird, oder aufFontFaceSet.ready.

Ergebnis

Das Ergebnis wird unten gezeigt. Es sollte den Namen der Schrift auf dem Canvas in der heruntergeladenen Schrift zeigen und ein Protokoll, das den Ladezustand vor und nach dem Laden zeigt.

Schriftladen mit Ereignissen

Dieses Beispiel ist ähnlich wie das vorherige, außer dass esFontFaceSet.load() verwendet, um die Schrift zu laden. Es zeigt auch, wie man Ereignisse für das Laden von Schriften abhört.

HTML

<canvas></canvas><textarea rows="25" cols="100"></textarea>

JavaScript

Der folgende Code definiert einen Canvas-Kontext zum Zeichnen von Text, definiert einen Schriftschnitt und fügt ihn dem Dokument-Schriftsatz hinzu.

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`;

Als nächstes verwenden wirload() auf dem Schriftsatz, um die Schrift zu laden und anzugeben, welche der Schriften geladen werden sollen. Die Methode gibt einPromise zurück. Wenn das Promise aufgelöst wird, verwenden wir die Schrift, um etwas Text zu zeichnen. Wenn es abgelehnt wird, wird der Fehler protokolliert.

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);  },);

Anstatt auf ein Promise zu warten, könnten wir stattdessen Ereignisse verwenden, um die Schriftladeoperation zu verfolgen. Der folgende Code lauscht auf die Ereignisseloading undloadingerror und protokolliert die Anzahl der Schriftschnitte für jeden Fall. Imloadingdone-Ereignis-Listener iterieren wir zusätzlich durch die Schriftschnitte und protokollieren die Familiennamen.

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`;  });});

Der letzte Code-Abschnitt zeigt, wie Sie den Abschluss des Schriftladevorgangs mithilfe des Promise überwachen können, das vonFontFaceSet.ready zurückgegeben wird. Im Gegensatz zu den anderen Mechanismen wird dies zurückgegeben, wenn alle im Dokument definierten Schriftarten heruntergeladen wurden und das Layout abgeschlossen ist.

Wenn das Promise aufgelöst wird, iterieren wir die Werte der Schriftschnitte des Dokuments.

document.fonts.ready.then(() => {  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`;    }  }});

Ergebnis

Das unten gezeigte Ergebnis zeigt den in "Oxygen"-Schriftart gezeichneten Text. Dies zeigt auch das Protokollieren von den Ereignissen und wann das Promise, das vondocument.fonts.ready zurückgegeben wird, gelöst wird.

Spezifikationen

Browser-Kompatibilität