FontFace.loaded — Eigenschaft · JavaScript-Referenz

Signatur

FontFace.loaded

Beschreibung

Die schreibgeschützte Eigenschaft loaded einer FontFace-Instanz gibt ein Promise zurück. Es wird mit genau diesem FontFace-Objekt erfüllt, sobald die im Konstruktor angegebene Schriftquelle geladen und erfolgreich verarbeitet wurde. Schlägt das Laden fehl, etwa wegen einer falschen URL, eines CORS-Fehlers oder ungültiger Schriftdaten, wird es mit einem DOMException vom Typ NetworkError bzw. SyntaxError abgelehnt.

Anders als FontFace.prototype.load() startet der Zugriff auf loaded keinen Ladevorgang. Du kannst damit nur auf einen Ladevorgang warten, der anderweitig ausgelöst wird: durch load(), durch document.fonts.load() oder dadurch, dass der Browser die Schrift beim Rendern braucht. Deshalb eignet sich loaded gut, wenn mehrere Programmteile unabhängig voneinander auf dieselbe Schrift warten wollen. Sie alle erhalten dasselbe Promise-Objekt.

Wird ein FontFace direkt mit binären Daten (ArrayBuffer oder TypedArray) erzeugt, ist die Schrift sofort bzw. nach dem Parsen verfügbar. loaded wird dann ohne Netzwerkzugriff erfüllt oder abgelehnt. Typische Einsatzfälle: Text auf einem Canvas erst zeichnen, wenn die Schrift bereitsteht, sichtbare Layoutsprünge (FOUT/FOIT) steuern oder Messungen mit measureText() erst nach dem Laden der Schrift vornehmen.

Rückgabewert

Typ

Promise<FontFace>

Beschreibung

Ein Promise, das mit dem aktuellen FontFace-Objekt erfüllt wird, sobald dessen status den Wert "loaded" hat. Wechselt status zu "error", wird es mit einem DOMException abgelehnt. Bei wiederholtem Zugriff liefert die Eigenschaft immer dasselbe Promise-Objekt.

Beispiele

Schrift laden und auf loaded warten

const font = new FontFace('Inter', 'url(/fonts/Inter.woff2)', { weight: '400' });
document.fonts.add(font);

// load() startet den Download, loaded wartet nur darauf
font.load();

const geladen = await font.loaded;
console.log(geladen === font, geladen.status);

true "loaded"

Canvas-Text erst nach dem Laden der Schrift zeichnen

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

const font = new FontFace('Pixel', 'url(/fonts/pixel.woff2)');
document.fonts.add(font);
font.load();

try {
  await font.loaded;
  ctx.font = '32px Pixel';
  ctx.fillText('Level 1', 20, 50);
} catch (err) {
  console.error('Schrift konnte nicht geladen werden:', err.name);
  ctx.font = '32px monospace';
  ctx.fillText('Level 1', 20, 50);
}

Fehlerbehandlung bei ungültiger URL

const font = new FontFace('Fehlt', 'url(/fonts/gibt-es-nicht.woff2)');
font.load().catch(() => {}); // Ablehnung hier abfangen

font.loaded
  .then(() => console.log('geladen'))
  .catch((err) => console.log(err.name, font.status));

NetworkError error

Schrift aus ArrayBuffer – loaded ohne Netzwerk

const response = await fetch('/fonts/Inter.woff2');
const buffer = await response.arrayBuffer();

const font = new FontFace('InterLocal', buffer);
await font.loaded; // wird nach dem Parsen erfüllt, ohne load() aufzurufen
document.fonts.add(font);
document.body.style.fontFamily = 'InterLocal, sans-serif';
console.log(font.status);

loaded

// Wichtig · Fallstricke

Kein automatischer Ladestart: Wird die Schrift über eine URL angegeben und weder load() aufgerufen noch von der Seite benutzt, bleibt loaded für immer unerfüllt (status ist dann \"unloaded\"). Ein await font.loaded hängt dann ewig.
Abgelehnte Promises: load() und loaded werden bei einem Fehler beide abgelehnt. Fange beide ab, sonst erscheint in der Konsole eine Warnung zu einer nicht behandelten Ablehnung („unhandled rejection“).
CORS: Schriften von fremden Domains brauchen einen passenden Access-Control-Allow-Origin-Header, sonst wird das Promise mit NetworkError abgelehnt.
Die Eigenschaft ist schreibgeschützt, und jeder Zugriff liefert dasselbe Promise-Objekt.
Kompatibilität: In allen aktuellen Browsern verfügbar (Chrome, Edge, Firefox, Safari) und auch in Web Workern über self.fonts nutzbar. Der Internet Explorer unterstützt die CSS Font Loading API nicht.
Um auf alle Schriften eines Dokuments zu warten, ist document.fonts.ready meist die bessere Wahl.

Siehe auch

FontFace FontFace.prototype.load() FontFace.status FontFaceSet.ready FontFaceSet.prototype.load() Document.fonts FontFace.display