Document.fonts — Eigenschaft · JavaScript-Referenz

Signatur

Document.fonts

Beschreibung

document.fonts gibt das FontFaceSet des Dokuments zurück. Dieses Objekt ist der zentrale Einstiegspunkt der CSS Font Loading API. Es enthält alle FontFace-Objekte, die dem Dokument über @font-face-Regeln im CSS oder per JavaScript mit fonts.add() zur Verfügung stehen.

Typische Einsatzfälle sind: auf das Laden aller Schriften warten (document.fonts.ready), bevor Text vermessen oder auf ein <canvas> gezeichnet wird, Schriften bei Bedarf nachladen (document.fonts.load()), prüfen, ob eine Schrift schon verfügbar ist (document.fonts.check()), und Schriften zur Laufzeit hinzufügen oder entfernen.

Da FontFaceSet von EventTarget erbt, lassen sich auch die Ereignisse loading, loadingdone und loadingerror abonnieren. So kann man zum Beispiel ein „Flash of Unstyled Text“ (FOUT) kontrolliert behandeln, indem eine CSS-Klasse erst gesetzt wird, sobald die Schriften bereitstehen.

Rückgabewert

Typ

FontFaceSet

Beschreibung

Das FontFaceSet des Dokuments, eine mengenähnliche Sammlung von FontFace-Objekten mit den Methoden add(), delete(), has(), check(), load(), der Eigenschaft status ("loading" oder "loaded") und dem Promise ready.

Beispiele

Auf alle Schriften warten, bevor gemessen wird

// Erst wenn alle Schriften geladen sind, stimmen die Textmaße
await document.fonts.ready;

const heading = document.querySelector('h1');
console.log('Status:', document.fonts.status);
console.log('Breite der Überschrift:', heading.getBoundingClientRect().width);

Status: loaded Breite der Überschrift: 412.5

Schrift gezielt laden und für Canvas nutzen

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

try {
  // Lädt alle Schriftschnitte, die zu dieser Font-Angabe passen
  const faces = await document.fonts.load('bold 32px "Roboto"');
  console.log(`${faces.length} Schriftschnitt(e) geladen`);

  ctx.font = 'bold 32px "Roboto"';
  ctx.fillText('Hallo Welt', 20, 50);
} catch (err) {
  console.error('Schrift konnte nicht geladen werden:', err);
}

1 Schriftschnitt(e) geladen

Schrift per JavaScript hinzufügen und prüfen

const font = new FontFace('MeineSchrift', 'url(/fonts/meine-schrift.woff2)', {
  weight: '400',
  style: 'normal'
});

document.fonts.add(font);
console.log('Vor dem Laden verfügbar?', document.fonts.check('16px MeineSchrift'));

await font.load();
console.log('Nach dem Laden verfügbar?', document.fonts.check('16px MeineSchrift'));

document.body.style.fontFamily = 'MeineSchrift, sans-serif';

Vor dem Laden verfügbar? false Nach dem Laden verfügbar? true

Ladeereignisse beobachten und CSS-Klasse setzen

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

document.fonts.onloadingerror = (event) => {
  console.warn('Fehler bei:', event.fontfaces.map((f) => f.family));
};

Fertig geladen: "Roboto", "Open Sans"

// Wichtig · Fallstricke

Nur lesbar: document.fonts selbst lässt sich nicht ersetzen, nur das enthaltene Set verändern (add(), delete(), clear()). clear() entfernt nur per JavaScript hinzugefügte Schriften, keine aus @font-face-Regeln.
check() ist irreführend: Es gibt true zurück, wenn keine passende Schrift im Set steht (weil dann eine Systemschrift genutzt wird). Ein true heißt also nicht zwingend, dass die gewünschte Web-Schrift geladen ist.
Lazy Loading: Browser laden @font-face-Schriften erst, wenn sie tatsächlich verwendet werden. document.fonts.ready kann daher erfüllt werden, bevor eine nie genutzte Schrift geladen wurde. Für Canvas-Text sollte man document.fonts.load() ausdrücklich aufrufen.
ready kann mehrmals relevant sein: Kommen später neue Ladevorgänge hinzu, wird ein neues Promise erzeugt. Eine einmal gespeicherte Referenz auf das alte Promise meldet diese nicht.
Worker: In Web Workern steht das Set als self.fonts (WorkerGlobalScope.fonts) zur Verfügung, nicht über document.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt, im Internet Explorer fehlt die Eigenschaft. Für alte Umgebungen if ('fonts' in document) prüfen.
CORS: Schriften von fremden Domains brauchen passende Access-Control-Allow-Origin-Header, sonst endet load() mit einem Fehler (loadingerror). Auch die CSP-Direktive font-src kann Ladevorgänge blockieren.

Siehe auch

FontFaceSet FontFace FontFaceSet.ready FontFaceSet.prototype.load() FontFaceSet.prototype.check() WorkerGlobalScope.fonts