new FontFaceSetLoadEvent() — Methode · JavaScript-Referenz

Signatur

new FontFaceSetLoadEvent(type, options)

Beschreibung

Der Konstruktor FontFaceSetLoadEvent() erzeugt ein Ereignisobjekt vom Typ FontFaceSetLoadEvent. Solche Ereignisse löst der Browser normalerweise selbst auf document.fonts (einem FontFaceSet) aus, und zwar wenn das Laden von Schriften beginnt (loading), abgeschlossen ist (loadingdone) oder fehlgeschlagen ist (loadingerror).

Die wichtigste Eigenschaft des Ereignisses ist fontfaces: ein fest eingefrorenes Array der FontFace-Objekte, die zu diesem Ladevorgang gehören. Im Handler von loadingdone steht es für die erfolgreich geladenen Schriften, bei loadingerror für die fehlgeschlagenen.

Selbst ruft man den Konstruktor vor allem in Tests auf, zum Beispiel um Code zu prüfen, der auf Schrift-Ereignisse reagiert, ohne auf echte Netzwerkanfragen zu warten. Außerdem eignet er sich, um in eigenen EventTarget-Strukturen ein einheitliches Ereignisformat zu verwenden. Weil FontFaceSetLoadEvent von Event erbt, lassen sich auch die üblichen Optionen wie bubbles und cancelable angeben.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"loading"`, `"loadingdone"` oder `"loadingerror"`. Groß- und Kleinschreibung wird beachtet.
$options	object	{}	Optionales Objekt. Es kann alle Optionen von `Event()` enthalten (`bubbles`, `cancelable`, `composed`) und zusätzlich `fontfaces`.
$options.fontfaces	FontFace[]	[]	Array von `FontFace`-Objekten, das später über `event.fontfaces` gelesen werden kann.

Rückgabewert

Typ

FontFaceSetLoadEvent

Beschreibung

Ein neues FontFaceSetLoadEvent-Objekt mit dem angegebenen Typ. Seine Eigenschaft fontfaces enthält die übergebenen Schriften.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const font = new FontFace('MeineSchrift', 'url(/fonts/meine-schrift.woff2)');

const event = new FontFaceSetLoadEvent('loadingdone', {
  fontfaces: [font]
});

console.log(event.type);
console.log(event.fontfaces.length);
console.log(event.fontfaces[0].family);
console.log(Object.isFrozen(event.fontfaces));

loadingdone 1 MeineSchrift true

Echte Ladeereignisse auf document.fonts abhören

document.fonts.addEventListener('loadingdone', (event) => {
  const namen = event.fontfaces.map((f) => f.family);
  console.log('Geladen:', namen.join(', '));
  document.documentElement.classList.add('fonts-loaded');
});

document.fonts.addEventListener('loadingerror', (event) => {
  console.warn('Fehlgeschlagen:', event.fontfaces.map((f) => f.family));
});

// Laden anstoßen
const font = new FontFace('Inter', 'url(/fonts/inter.woff2)');
document.fonts.add(font);
font.load().catch(() => {});

Geladen: Inter

Handler im Test mit einem simulierten Ereignis prüfen

const target = new EventTarget();
const geladen = [];

const onFontsLoaded = (event) => {
  geladen.push(...event.fontfaces.map((f) => f.family));
};

target.addEventListener('loadingdone', onFontsLoaded);

const fakeFonts = [
  new FontFace('Roboto', 'local(Roboto)'),
  new FontFace('Lora', 'local(Lora)')
];

target.dispatchEvent(new FontFaceSetLoadEvent('loadingdone', { fontfaces: fakeFonts }));

console.log(geladen);
target.removeEventListener('loadingdone', onFontsLoaded);

['Roboto', 'Lora']

// Wichtig · Fallstricke

Ein selbst erzeugtes und per dispatchEvent() versendetes Ereignis hat isTrusted === false. Die Schriften werden dadurch nicht geladen, und der Zustand von document.fonts (status, ready) bleibt unverändert.
event.fontfaces ist ein eingefrorenes Array. Versuche, es zu verändern, werden stillschweigend ignoriert bzw. werfen im Strict Mode einen TypeError.
Ob das Laden aller Schriften fertig ist, prüft man meist einfacher mit await document.fonts.ready. Die Ereignisse sind nur dann nützlich, wenn man einzelne Ladevorgänge verfolgen muss.
Ohne new aufgerufen wirft der Konstruktor einen TypeError. In Web Workern gibt es ihn über self.fonts, wobei die Unterstützung je nach Browser verschieden ist. Node.js kennt diese API nicht.
Hinweis zur Kompatibilität: Sehr alte Browser (Internet Explorer, Safari vor Version 10) unterstützen die CSS Font Loading API nicht. Vorher mit 'FontFaceSetLoadEvent' in window prüfen, ob sie vorhanden ist.

Siehe auch

FontFaceSetLoadEvent FontFaceSetLoadEvent.fontfaces FontFaceSet FontFace Document.fonts Event