FontFaceSetLoadEvent.fontfaces — Eigenschaft · JavaScript-Referenz

Signatur

FontFaceSetLoadEvent.fontfaces

Beschreibung

Die Eigenschaft fontfaces eines FontFaceSetLoadEvent enthält ein Array von FontFace-Instanzen. Jede Instanz steht für eine einzeln nutzbare Schriftart, also eine Kombination aus Familie, Schnitt, Stil und Unicode-Bereich.

Solche Ereignisse feuert das FontFaceSet (in der Regel document.fonts). Welche Schriften im Array stehen, hängt vom Ereignistyp ab:

loading: die Schriften, deren Laden gerade begonnen hat.
loadingdone: die Schriften, die erfolgreich geladen wurden.
loadingerror: die Schriften, deren Laden fehlgeschlagen ist.

Nützlich ist die Eigenschaft, um gezielt auf das Laden bestimmter Webfonts zu reagieren. Typische Fälle: eine CSS-Klasse wie fonts-loaded setzen, um ein Aufblitzen ungestylten Texts (FOUT) zu steuern, Ladefehler protokollieren oder Layout-Berechnungen neu ausführen, die von Schriftmetriken abhängen.

Rückgabewert

Typ

ReadonlyArray<FontFace>

Beschreibung

Ein eingefrorenes Array von FontFace-Objekten, die zum jeweiligen Ereignis gehören. Es kann auch leer sein.

Beispiele

Geladene Schriften protokollieren

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

// Laden einer Schrift anstoßen
document.fonts.load('700 1em "Inter"');

Geladen: Inter 700 normal

Ladefehler erkennen und Ersatzschrift aktivieren

document.fonts.onloadingerror = (event) => {
  const failed = event.fontfaces.map((f) => f.family);
  console.warn('Schriften nicht ladbar:', failed);
  document.documentElement.classList.add('fonts-fallback');
};

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

Schriften nicht ladbar: ["Kaputt"]

Klasse setzen, sobald eine bestimmte Familie bereit ist

const onDone = (event) => {
  const hasRoboto = event.fontfaces.some(
    (f) => f.family.replace(/["']/g, '') === 'Roboto'
  );
  if (hasRoboto) {
    document.body.classList.add('roboto-ready');
    document.fonts.removeEventListener('loadingdone', onDone);
  }
};

document.fonts.addEventListener('loadingdone', onDone);

Ereignis selbst erzeugen (z. B. für Tests)

const face = new FontFace('Demo', 'local(Arial)');
const evt = new FontFaceSetLoadEvent('loadingdone', { fontfaces: [face] });

console.log(evt.fontfaces.length, evt.fontfaces[0].family);
console.log(Object.isFrozen(evt.fontfaces));

1 Demo true

// Wichtig · Fallstricke

Das Array ist eingefroren. push() oder Zuweisungen an Indizes werfen im Strict Mode einen Fehler, sonst werden sie stillschweigend ignoriert. Die Eigenschaft selbst ist schreibgeschützt.
FontFace.family kann Anführungszeichen enthalten, je nachdem, wie die Schrift deklariert wurde (z. B. "\"Open Sans\""). Vor Vergleichen deshalb normalisieren.
Die Ereignisse loadingdone und loadingerror werden einmal pro Ladevorgang ausgelöst, nicht einmal pro Schrift. Ein Array kann also mehrere Schriften enthalten, und bei loadingdone kann es sogar leer sein.
Schriften, die schon vor der Registrierung des Listeners geladen wurden, lösen kein Ereignis mehr aus. Für den aktuellen Zustand besser document.fonts.ready oder document.fonts.check() verwenden.
Browser-Kompatibilität: Die Eigenschaft wird in Chrome/Edge 35+, Firefox 41+ und Safari 10+ unterstützt. Im Internet Explorer gibt es sie nicht. Web Worker unterstützen sie über self.fonts nur teilweise.

Siehe auch

FontFaceSetLoadEvent FontFace FontFaceSet FontFaceSet.ready Document.fonts