FontFaceSet.ready — Eigenschaft · JavaScript-Referenz

Signatur

FontFaceSet.ready

Beschreibung

Die Eigenschaft ready der Schnittstelle FontFaceSet, meist über document.fonts.ready aufgerufen, gibt ein Promise zurück. Es wird erfüllt, wenn alle Ladevorgänge für Schriften abgeschlossen sind, das Layout fertig ist und keine weiteren Schriften mehr geladen werden müssen. Der Erfüllungswert ist das FontFaceSet selbst.

Typische Anwendungsfälle:

Textmaße messen, zum Beispiel mit getBoundingClientRect() oder CanvasRenderingContext2D.measureText(). Erst wenn die Webfonts wirklich aktiv sind, stimmen die Werte.
Text in ein <canvas> zeichnen, und zwar mit der richtigen Schrift statt einer Ersatzschrift.
Einen „Flash of Unstyled Text“ vermeiden: Eine CSS-Klasse wird erst gesetzt, wenn die Schriften bereitstehen.
Layout-Bibliotheken (Masonry, Textfluss, Silbentrennung) erst nach dem Laden der Schriften starten.

Das Promise wird nur einmal pro Ladezyklus erfüllt. Starten später neue Ladevorgänge, etwa weil dynamisch Text mit einer anderen Schrift eingefügt wird, geht FontFaceSet.status wieder auf "loading". Ein erneuter Zugriff auf ready kann dann ein neues, noch offenes Promise liefern. Möchte man kontinuierlich reagieren, eignen sich die Ereignisse loadingdone und loadingerror besser.

Rückgabewert

Typ

Promise<FontFaceSet>

Beschreibung

Ein Promise, das mit dem jeweiligen FontFaceSet (z. B. document.fonts) erfüllt wird, sobald Laden und Layout abgeschlossen sind. Es wird auch dann erfüllt, wenn einzelne Schriften nicht geladen werden konnten. Fehler meldet das loadingerror-Ereignis.

Beispiele

Warten, bis alle Schriften geladen sind

const waitForFonts = async () => {
  const fontSet = await document.fonts.ready;
  console.log(`Status: ${fontSet.status}, Anzahl Schriften: ${fontSet.size}`);
  document.documentElement.classList.add('fonts-loaded');
};

waitForFonts();

Status: loaded, Anzahl Schriften: 3

Text mit Webfont ins Canvas zeichnen

const canvas = document.querySelector('#chart');
const ctx = canvas.getContext('2d');

// Ohne Warten würde möglicherweise die Ersatzschrift gezeichnet
await document.fonts.load('bold 24px "Inter"');
await document.fonts.ready;

ctx.font = 'bold 24px "Inter"';
ctx.fillText('Umsatz 2024', 20, 40);
console.log('Breite:', Math.round(ctx.measureText('Umsatz 2024').width), 'px');

Breite: 148 px

Textbreite erst nach dem Laden der Schriften messen

const heading = document.querySelector('h1');

console.log('Vorher:', heading.getBoundingClientRect().width);

document.fonts.ready.then(() => {
  // Jetzt ist das Layout mit der endgültigen Schrift berechnet
  console.log('Nachher:', heading.getBoundingClientRect().width);
});

Vorher: 412.5 Nachher: 437.2

Mit Zeitlimit kombinieren

const fontsReadyOrTimeout = (ms = 3000) =>
  Promise.race([
    document.fonts.ready.then(() => 'fonts'),
    new Promise((resolve) => setTimeout(() => resolve('timeout'), ms))
  ]);

const result = await fontsReadyOrTimeout(2000);
console.log(`Rendering gestartet nach: ${result}`);

Rendering gestartet nach: fonts

// Wichtig · Fallstricke

Kein Fehlerfall: Das Promise wird auch erfüllt, wenn eine Schrift nicht geladen werden kann, etwa bei einem 404-Fehler oder einem CORS-Problem. Ob eine bestimmte Schrift verfügbar ist, prüft man mit document.fonts.check('16px "Inter"') oder über das Ereignis loadingerror.
Nur benutzte Schriften werden geladen: Per @font-face deklarierte Schriften lädt der Browser erst, wenn sie tatsächlich im Dokument verwendet werden. Kommt eine Schrift nur im Canvas zum Einsatz, muss man sie vorher mit document.fonts.load() anstoßen. Sonst ist ready womöglich schon erfüllt, ohne dass die Schrift geladen wurde.
Nicht dauerhaft gültig: Werden später neue Schriften nachgeladen, kann ein erneuter Zugriff auf ready ein neues Promise liefern. Deshalb sollte man ready nicht einmalig zwischenspeichern und dann für „alle Zukunft“ verwenden.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome 35+, Firefox 41+, Safari 10+, Edge 79+), nicht vom Internet Explorer. In Web Workern ist die Eigenschaft über self.fonts erreichbar, sofern der Browser das unterstützt. Eine Prüfung wie 'fonts' in document dient als Feature-Erkennung.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert und löst im Strict Mode einen TypeError aus.

Siehe auch

FontFaceSet FontFaceSet.prototype.load() FontFaceSet.prototype.check() FontFaceSet.status FontFace Document.fonts