FontFace.status — Eigenschaft · JavaScript-Referenz

Signatur

FontFace.status

Beschreibung

Die Eigenschaft status einer FontFace-Instanz zeigt, wie weit das Laden der Schriftart gerade ist. Sie ist schreibgeschützt und liefert einen von vier Zeichenkettenwerten:

"unloaded" – Die Schrift wurde noch nicht angefordert. Das ist der Anfangszustand einer Schrift, die über eine URL-Quelle (url(...)) erzeugt wurde.
"loading" – Das Laden läuft gerade, entweder durch Aufruf von load() oder weil der Browser die Schrift für die Darstellung braucht.
"loaded" – Die Schrift wurde erfolgreich geladen und geparst und kann verwendet werden.
"error" – Das Laden oder Parsen ist fehlgeschlagen, z. B. wegen eines Netzwerkfehlers, eines ungültigen Formats oder eines CORS-Problems.

Nützlich ist status vor allem für synchrone Abfragen, etwa um vor dem Zeichnen auf ein <canvas> zu prüfen, ob eine Schrift schon bereitsteht, oder um in einer Diagnose alle Schriften aus document.fonts mit ihrem Zustand aufzulisten. Wer auf das Ende des Ladens warten will, sollte stattdessen das Promise FontFace.loaded oder den Rückgabewert von FontFace.load() benutzen, denn in einer Schleife immer wieder status abzufragen (Polling) ist unnötig.

Wird eine FontFace aus binären Daten (ArrayBuffer bzw. ArrayBufferView) erzeugt, parst der Browser die Daten sofort. Der Status springt dann direkt auf "loaded" oder "error", der Zustand "unloaded" wird übersprungen.

Rückgabewert

Typ

"unloaded" | "loading" | "loaded" | "error"

Beschreibung

Eine Zeichenkette mit dem aktuellen Ladezustand der Schriftart.

Beispiele

Statusverlauf beim Laden einer Webfont beobachten

const font = new FontFace('Roboto', 'url(/fonts/roboto.woff2)');
console.log(font.status); // vor dem Laden

const promise = font.load();
console.log(font.status); // Laden läuft

try {
  await promise;
  document.fonts.add(font);
  console.log(font.status);
} catch (err) {
  console.error('Schrift konnte nicht geladen werden:', font.status);
}

unloaded loading loaded

Vor dem Canvas-Zeichnen prüfen, ob die Schrift bereitsteht

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const font = new FontFace('Lobster', 'url(/fonts/lobster.woff2)');
document.fonts.add(font);

const draw = () => {
  // Ersatzschrift nehmen, solange die Webfont nicht geladen ist
  const family = font.status === 'loaded' ? 'Lobster' : 'serif';
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.font = `32px ${family}`;
  ctx.fillText('Hallo Welt', 20, 50);
};

draw();                          // zuerst mit serif zeichnen
font.load().then(draw, () => {}); // nach dem Laden neu zeichnen

Alle Schriften des Dokuments mit ihrem Status auflisten

await document.fonts.ready;

const report = [...document.fonts].map((f) => ({
  family: f.family,
  weight: f.weight,
  status: f.status
}));
console.table(report);

const failed = report.filter((r) => r.status === 'error');
if (failed.length) console.warn('Fehlgeschlagene Schriften:', failed);

Tabelle mit family, weight und status, z. B. "Roboto" | "400" | "loaded"

Schrift aus einem ArrayBuffer erzeugen

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

const font = new FontFace('Inter', buffer);
// Binärdaten werden sofort geparst, "unloaded" wird übersprungen
await font.loaded;
console.log(font.status);

loaded

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie font.status = 'loaded' wird im nicht strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus.
Kein Polling: Um auf das Ende des Ladens zu warten, await font.loaded oder await font.load() verwenden. Das Promise wird bei "error" mit einer DOMException vom Typ NetworkError bzw. SyntaxError abgelehnt.
Nur hinzufügen startet kein Laden: Mit document.fonts.add(font) allein bleibt der Status "unloaded", bis ein Element die Schrift tatsächlich benutzt oder load() aufgerufen wird. Bei Canvas-Text wird das Laden nicht immer zuverlässig ausgelöst, deshalb dort load() ausdrücklich aufrufen.
Ursachen für "error": Fehlende CORS-Header bei Schriften von fremden Domains, ein falscher MIME-Typ, ein beschädigtes oder nicht unterstütztes Dateiformat oder eine Content-Security-Policy, die über font-src die Quelle sperrt.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt (Chrome, Edge, Firefox, Safari) und ist auch in Web Workers über self.fonts verfügbar. Der Internet Explorer unterstützt die CSS Font Loading API nicht.

Siehe auch

Document.fonts DataCue.value FontFace.stretch FontFace.style FontFace.loaded