FontFaceSet: loadingdone — Ereignis · JavaScript-Referenz

Signatur

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

Beschreibung

Das Ereignis loadingdone wird an einem FontFaceSet (meist document.fonts, in Workern self.fonts) ausgelöst, wenn keine Schriftladevorgänge mehr ausstehen. Das Ereignisobjekt ist ein FontFaceSetLoadEvent. Seine Eigenschaft fontfaces enthält die FontFace-Objekte, die in diesem Durchgang erfolgreich geladen wurden.

Du registrierst den Listener entweder mit addEventListener("loadingdone", handler) oder über die Eigenschaft document.fonts.onloadingdone. Das Ereignis wird nicht abgebrochen und steigt nicht auf (kein Bubbling).

Typische Einsatzfälle: Layout-Messungen neu berechnen, die von der Schriftbreite abhängen (z. B. Textumbrüche in Canvas oder virtualisierte Listen), eine Klasse wie fonts-loaded setzen, um einen FOUT (Flash of Unstyled Text) zu vermeiden, oder in Analysen protokollieren, welche Webfonts tatsächlich geladen wurden.

Das Ereignis gehört zu einer Dreiergruppe: loading (Ladevorgang beginnt), loadingdone (Ladevorgang abgeschlossen) und loadingerror (mindestens eine Schrift ist fehlgeschlagen). Es kann in einem Dokument mehrmals auftreten, zum Beispiel wenn später per JavaScript oder durch neu verwendete CSS-Regeln weitere Schriften nachgeladen werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"loadingdone"`.
$handler Pflicht	(event: FontFaceSetLoadEvent) => void		Callback, der ein `FontFaceSetLoadEvent` erhält. `event.fontfaces` ist ein Array der erfolgreich geladenen `FontFace`-Objekte.
$options	boolean \| AddEventListenerOptions	false	Die üblichen Listener-Optionen, z. B. `{ once: true }` oder `{ signal }` zum Entfernen per `AbortController`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein FontFaceSetLoadEvent.

Beispiele

Geladene Schriften mit addEventListener protokollieren

document.fonts.addEventListener("loadingdone", (event) => {
  const namen = event.fontfaces.map((f) => `${f.family} ${f.weight}`);
  console.log(`Fertig geladen: ${namen.join(", ")}`);
  document.documentElement.classList.add("fonts-loaded");
});

Fertig geladen: "Inter" 400, "Inter" 700

Variante mit der on-Property onloadingdone

document.fonts.onloadingdone = (event) => {
  console.log(`${event.fontfaces.length} Schrift(en) geladen`);
};

// Handler später wieder entfernen
// document.fonts.onloadingdone = null;

2 Schrift(en) geladen

Schrift per JavaScript laden, Canvas neu zeichnen, Listener wieder entfernen

const canvas = document.querySelector("canvas");
const ctx = canvas.getContext("2d");

const zeichnen = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.font = "32px Roboto, sans-serif";
  ctx.fillText("Hallo Welt", 20, 50);
};

const onDone = (event) => {
  if (event.fontfaces.some((f) => f.family.includes("Roboto"))) {
    zeichnen();
    document.fonts.removeEventListener("loadingdone", onDone);
  }
};

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

const roboto = new FontFace("Roboto", "url(/fonts/roboto.woff2)");
document.fonts.add(roboto);
roboto.load(); // löst loading und danach loadingdone aus
zeichnen(); // erster Durchgang mit Ersatzschrift

Fehler mit loadingerror zusätzlich abfangen

const controller = new AbortController();
const { signal } = controller;

document.fonts.addEventListener("loadingdone", (e) => {
  console.log("OK:", e.fontfaces.map((f) => f.family));
}, { signal });

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

// Beide Listener auf einmal entfernen
// controller.abort();

OK: ["Inter"]

// Wichtig · Fallstricke

Späte Registrierung: Sind die Schriften schon geladen, bevor du den Listener registrierst, wird loadingdone nicht nachträglich ausgelöst. Wenn du nur wissen willst, ob alles fertig ist, nimm besser das Promise document.fonts.ready. Es erfüllt sich auch dann, wenn der Ladevorgang schon vorbei ist.
Lazy Loading: Browser laden per @font-face deklarierte Schriften erst, wenn sie tatsächlich auf der Seite verwendet werden. Ohne passenden sichtbaren Text wird deshalb gar nichts geladen und auch kein Ereignis ausgelöst.
Fehlgeschlagene Schriften: Ein fehlgeschlagener Ladevorgang verhindert loadingdone nicht. fontfaces enthält dann nur die erfolgreich geladenen Schriften. Die fehlgeschlagenen kommen über loadingerror.
Mehrfaches Auslösen: Das Ereignis kann in einem Dokument mehrmals auftreten. Soll dein Code nur einmal laufen, nutze { once: true }.
Kompatibilität: Wird in allen modernen Browsern unterstützt. In Web Workern steht es über self.fonts zur Verfügung, aber nicht in jedem Browser gleich lange. Der Internet Explorer unterstützt die CSS Font Loading API nicht.

Siehe auch

FontFaceSet FontFaceSet.ready FontFaceSetLoadEvent FontFace FontFace.prototype.load() Document.fonts