FontFaceSetLoadEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface FontFaceSetLoadEvent extends Event

Beschreibung

FontFaceSetLoadEvent ist das Ereignisobjekt, das ein FontFaceSet (meist document.fonts oder im Worker self.fonts) auslöst, wenn Schriften geladen werden. Es gibt drei Ereignistypen: loading (das Laden beginnt), loadingdone (alle angestoßenen Ladevorgänge sind abgeschlossen) und loadingerror (mindestens eine Schrift konnte nicht geladen werden).

Zusätzlich zu den geerbten Eigenschaften von Event bietet die Schnittstelle die schreibgeschützte Eigenschaft fontfaces: ein Array von FontFace-Objekten, die zu diesem Ereignis gehören. Bei loadingdone sind das die erfolgreich geladenen Schriften, bei loadingerror die fehlgeschlagenen.

Einsatzzwecke sind etwa das Vermeiden von FOUT/FOIT (Klasse am <html>-Element setzen, sobald Webfonts bereit sind), Neuberechnen von Layouts oder Canvas-Texten nach dem Laden von Schriften sowie Monitoring fehlgeschlagener Font-Downloads.

Einen Konstruktor new FontFaceSetLoadEvent(type, options) gibt es ebenfalls, er wird aber hauptsächlich für Tests oder eigene Ereignis-Simulation verwendet.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur beim Konstruktor: Ereignistyp, z. B. `"loading"`, `"loadingdone"` oder `"loadingerror"`.
$options	{ fontfaces?: FontFace[], bubbles?: boolean, cancelable?: boolean, composed?: boolean }	{}	Nur beim Konstruktor: `fontfaces` legt das Array der betroffenen Schriften fest (Standard: leeres Array); dazu die üblichen `EventInit`-Optionen.

Rückgabewert

Typ

FontFaceSetLoadEvent

Beschreibung

Ereignisobjekt mit der schreibgeschützten Eigenschaft fontfaces (FontFace[]).

Beispiele

Geladene Schriften protokollieren (addEventListener)

document.fonts.addEventListener('loadingdone', (event) => {
  for (const face of event.fontfaces) {
    console.log(`Geladen: ${face.family} ${face.weight} ${face.style}`);
  }
  document.documentElement.classList.add('fonts-loaded');
});

// Laden explizit anstoßen
document.fonts.load('700 16px "Inter"');

Geladen: Inter 700 normal

Fehlgeschlagene Schriften über on-Property melden

document.fonts.onloadingerror = (event) => {
  const failed = event.fontfaces.map((f) => f.family);
  console.warn('Schriften nicht geladen:', failed);
};

const broken = new FontFace('Kaputt', 'url(/fonts/gibt-es-nicht.woff2)');
document.fonts.add(broken);
broken.load().catch(() => {});

Schriften nicht geladen: ["Kaputt"]

Ladebeginn anzeigen und Listener wieder entfernen

const onLoading = (event) => {
  console.log(`Ladevorgang gestartet (${event.fontfaces.length} Schrift(en))`);
  document.body.classList.add('fonts-loading');
};

document.fonts.addEventListener('loading', onLoading);

const face = new FontFace('Roboto', 'url(/fonts/roboto.woff2)');
document.fonts.add(face);
await face.load();

document.body.classList.remove('fonts-loading');
document.fonts.removeEventListener('loading', onLoading);

Ladevorgang gestartet (1 Schrift(en))

Ereignis für Tests selbst erzeugen

const face = new FontFace('Test', 'local(Arial)');
const evt = new FontFaceSetLoadEvent('loadingdone', { fontfaces: [face] });
console.log(evt.type, evt.fontfaces[0].family);

loadingdone Test

// Wichtig · Fallstricke

Die Ereignisse feuern nur, wenn tatsächlich ein Ladevorgang stattfindet. Sind Schriften bereits im Cache geladen oder wird die Schrift nie im Dokument verwendet, kommt eventuell kein Ereignis – für „Sind alle Schriften fertig?“ ist await document.fonts.ready zuverlässiger.
loadingdone kann mehrfach feuern, wenn später weitere Schriften nachgeladen werden (z. B. durch neue CSS-Regeln).
Ein loadingerror wird ausgelöst, wenn mindestens eine Schrift fehlschlägt; ein loadingdone kann trotzdem folgen – beide Arrays getrennt auswerten.
fontfaces ist ein eingefrorenes Array; Änderungen daran sind wirkungslos.
Kompatibilität: in Chrome, Edge, Firefox und Safari unterstützt; in Web Workern über self.fonts nicht überall verfügbar. Ältere Browser (z. B. Internet Explorer) kennen die CSS Font Loading API nicht – per 'fonts' in document prüfen.
Bei Schriften von fremden Domains sind CORS-Header (Access-Control-Allow-Origin) nötig, sonst endet das Laden in loadingerror.

Siehe auch

Document.fonts Event BeforeUnloadEvent FontFaceSet FormDataEvent