FontFaceSet: loadingerror — Ereignis · JavaScript-Referenz

Signatur

document.fonts.addEventListener("loadingerror", handler)

Beschreibung

Das Ereignis loadingerror gehört zum Interface FontFaceSet, das man im Browser meist über document.fonts erreicht (in Workern über self.fonts). Es wird ausgelöst, sobald der Browser alle ausstehenden Schriftarten abgearbeitet hat und dabei mindestens eine Schriftart gescheitert ist, zum Beispiel wegen eines 404-Fehlers, einer CORS-Sperre oder einer beschädigten Schriftdatei.

Der Handler erhält ein FontFaceSetLoadEvent. Dessen Eigenschaft fontfaces ist ein Array mit den FontFace-Objekten, die nicht geladen werden konnten. So kannst du gezielt reagieren: Fehler protokollieren, eine Ersatzschrift aktivieren oder eine CSS-Klasse setzen, die das Layout an die Systemschrift anpasst.

Registrieren lässt sich das Ereignis mit document.fonts.addEventListener("loadingerror", handler) oder über die Eigenschaft document.fonts.onloadingerror = handler. Das zugehörige Ereignis loadingdone wird ebenfalls ausgelöst, sobald der Ladevorgang beendet ist; dessen fontfaces enthält dann die erfolgreich geladenen Schriftarten.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"loadingerror"`.
$handler Pflicht	(event: FontFaceSetLoadEvent) => void		Callback, der ein `FontFaceSetLoadEvent` erhält. `event.fontfaces` enthält die fehlgeschlagenen `FontFace`-Objekte.
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen für `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener hat keinen Rückgabewert. Der Handler bekommt ein FontFaceSetLoadEvent mit der Eigenschaft fontfaces (FontFace[]).

Beispiele

Fehlgeschlagene Schriftarten protokollieren

document.fonts.addEventListener("loadingerror", (event) => {
  for (const face of event.fontfaces) {
    console.warn(`Schrift fehlgeschlagen: ${face.family} (${face.weight}, ${face.style}), Status: ${face.status}`);
  }
});

// Eine Schrift mit ungültiger URL anlegen und laden
const broken = new FontFace("Brand", "url(/fonts/gibt-es-nicht.woff2)");
document.fonts.add(broken);
broken.load().catch(() => { /* Fehler wird auch über das Ereignis gemeldet */ });

Schrift fehlgeschlagen: Brand (normal, normal), Status: error

Ersatzschrift per CSS-Klasse aktivieren (on-Property)

document.fonts.onloadingerror = (event) => {
  const families = event.fontfaces.map((f) => f.family);
  if (families.includes("Brand")) {
    // CSS: .font-fallback body { font-family: system-ui, sans-serif; }
    document.documentElement.classList.add("font-fallback");
  }
};

// Später wieder entfernen
// document.fonts.onloadingerror = null;

Fehler an Monitoring senden und Listener wieder entfernen

const reportFontErrors = (event) => {
  const payload = event.fontfaces.map(({ family, weight, style }) => ({ family, weight, style }));
  navigator.sendBeacon("/api/font-errors", JSON.stringify(payload));
};

document.fonts.addEventListener("loadingerror", reportFontErrors);

// Nach dem initialen Laden nicht mehr überwachen
document.fonts.ready.then(() => {
  document.fonts.removeEventListener("loadingerror", reportFontErrors);
  console.log("Überwachung beendet");
});

Überwachung beendet

// Wichtig · Fallstricke

Nur bei tatsächlich angestoßenem Laden: Per @font-face deklarierte Schriften werden erst geladen, wenn sie im Dokument verwendet werden. Unbenutzte Schriften lösen daher kein loadingerror aus.
Späte Registrierung: Wird der Listener erst angemeldet, nachdem das Laden schon beendet ist, verpasst du das Ereignis. Registriere ihn früh oder prüfe zusätzlich FontFace.status === "error" für alle Einträge in document.fonts.
Keine Fehlerdetails: Das Ereignis sagt nicht, warum das Laden gescheitert ist (404, CORS, ungültiges Format). Genaueres zeigen die Netzwerk-Werkzeuge im Browser oder die abgelehnte Promise von FontFace.load().
CORS: Schriften von anderen Ursprüngen brauchen einen passenden Access-Control-Allow-Origin-Header, sonst schlägt das Laden fehl. Auch eine font-src-Direktive der CSP kann Schriften blockieren.
Kompatibilität: Das Ereignis wird von allen aktuellen Browsern unterstützt. In sehr alten Browsern fehlt document.fonts; prüfe dort vorher mit "fonts" in document.

Siehe auch

FontFaceSet FontFaceSetLoadEvent FontFace FontFaceSet.ready Document.fonts