FontFaceSet — Schnittstelle · JavaScript-Referenz

Signatur

interface FontFaceSet extends EventTarget

Beschreibung

FontFaceSet ist die zentrale Schnittstelle der CSS Font Loading API. Eine Instanz steht im Dokument als document.fonts bereit, in Web Workern als self.fonts. Die Menge enthält alle Schriftarten, die per CSS-@font-face deklariert wurden, sowie alle, die Sie per Skript mit add() ergänzen. Sie verhält sich wie ein Set: Methoden wie add(), delete(), has(), clear(), forEach(), entries(), values() und die Eigenschaft size sind vorhanden, und Sie können sie mit for...of durchlaufen.

Wichtige Bestandteile:

status – "loading" oder "loaded", je nachdem, ob gerade noch Schriften geladen werden.
ready – ein Promise<FontFaceSet>, das erfüllt wird, sobald das Laden der Schriften und das Layout abgeschlossen sind.
load(font, text) – lädt gezielt alle Schriften, die zu einer CSS-font-Kurzschreibweise passen, und liefert ein Promise<FontFace[]>.
check(font, text) – gibt synchron true zurück, wenn alle für den Text benötigten, passenden Schriften bereits geladen sind (oder gar keine passende Schrift in der Menge existiert).
Ereignisse – loading, loadingdone und loadingerror (als FontFaceSetLoadEvent), auch als onloading, onloadingdone und onloadingerror.

Sie verwenden FontFaceSet, wenn Sie Text erst nach dem Laden der Webfonts messen oder zeichnen wollen (z. B. im <canvas>), wenn Sie ein Aufblitzen ungestylten Textes (FOUT) oder unsichtbaren Textes (FOIT) gezielt steuern möchten, oder wenn Sie Schriften erst bei Bedarf dynamisch nachladen.

Parameter

Name	Typ	Default	Beschreibung
$font Pflicht	string		Für `load()` und `check()`: eine Schriftangabe in CSS-`font`-Kurzschreibweise, z. B. `"bold 16px Inter"`. Schriftgröße und Familie sind Pflicht.
$text	string	" " (Leerzeichen)	Für `load()` und `check()`: Beispieltext, mit dem über `unicode-range` ermittelt wird, welche Schriftdateien nötig sind.
$fontFace Pflicht	FontFace		Für `add()`, `delete()` und `has()`: das `FontFace`-Objekt, das hinzugefügt, entfernt oder geprüft werden soll.

Rückgabewert

Typ

FontFaceSet

Beschreibung

document.fonts bzw. self.fonts liefert die FontFaceSet-Instanz des Dokuments oder Workers. load() gibt Promise<FontFace[]> zurück, check() einen boolean, ready ein Promise<FontFaceSet>.

Beispiele

Warten, bis alle Schriften bereit sind

// Z. B. vor dem Messen von Textbreiten
const init = async () => {
  console.log('Status vorher:', document.fonts.status);
  await document.fonts.ready;
  console.log('Status nachher:', document.fonts.status);
  console.log('Anzahl Schriften:', document.fonts.size);

  const breite = document.querySelector('h1')?.getBoundingClientRect().width;
  console.log('Überschrift-Breite:', breite);
};

init();

Status vorher: loading Status nachher: loaded Anzahl Schriften: 4 Überschrift-Breite: 612.5

Schrift dynamisch per FontFace hinzufügen und laden

const ladeSchrift = async () => {
  const inter = new FontFace(
    'Inter',
    'url(/fonts/inter-var.woff2) format("woff2")',
    { weight: '100 900', display: 'swap' }
  );

  document.fonts.add(inter);   // zur Menge hinzufügen
  await inter.load();          // Download anstoßen

  console.log(document.fonts.has(inter));        // true
  console.log(document.fonts.check('16px Inter')); // true
  document.body.style.fontFamily = 'Inter, sans-serif';
};

ladeSchrift().catch((err) => console.error('Schrift fehlgeschlagen:', err));

true true

Canvas-Text erst nach dem Laden zeichnen

const zeichne = async () => {
  const canvas = document.querySelector('canvas');
  const ctx = canvas.getContext('2d');
  const font = 'bold 32px "Roboto Slab"';

  // Lädt nur die für diesen Text nötigen Schriftdateien
  const faces = await document.fonts.load(font, 'Hallo Welt');
  console.log(`${faces.length} Schrift(en) geladen`);

  ctx.font = font;
  ctx.fillText('Hallo Welt', 20, 50);
};

zeichne();

1 Schrift(en) geladen

Ladeereignisse beobachten und wieder entfernen

const onDone = (event) => {
  const namen = event.fontfaces.map((f) => `${f.family} ${f.weight}`);
  console.log('Fertig geladen:', namen.join(', '));
};

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

// Alle Schriften der Menge auflisten
for (const face of document.fonts) {
  console.log(face.family, face.status);
}

// Später aufräumen
setTimeout(() => document.fonts.removeEventListener('loadingdone', onDone), 10000);

Inter loaded Roboto Slab unloaded Fertig geladen: Roboto Slab 700

// Wichtig · Fallstricke

check() ist irreführend: Es gibt auch true zurück, wenn keine passende Schrift in der Menge existiert, z. B. bei Tippfehlern im Familiennamen. Es sagt also nicht, dass eine Schrift verfügbar ist, sondern nur, dass nichts mehr geladen werden muss.
Lazy Loading: Per CSS deklarierte @font-face-Schriften lädt der Browser erst, wenn sie tatsächlich verwendet werden. document.fonts.ready kann deshalb erfüllt sein, bevor eine später benötigte Schrift geladen wurde. Mit load() erzwingen Sie das Laden gezielt.
ready kann sich ändern: Beginnt nach dem Erfüllen ein neuer Ladevorgang, liefert document.fonts.ready ein neues Promise. Lesen Sie die Eigenschaft daher bei Bedarf neu aus.
load() wird abgelehnt (SyntaxError), wenn die font-Angabe ungültig ist, etwa ohne Schriftgröße.
Mit delete() lassen sich nur per Skript hinzugefügte Schriften entfernen. Aus CSS stammende Schriften (CSS-verbunden) bleiben erhalten.
Kompatibilität: document.fonts wird von allen modernen Browsern unterstützt. self.fonts in Workern und der Konstruktor new FontFaceSet() werden nicht überall unterstützt. Prüfen Sie vorher mit 'fonts' in document.
Sicherheit/Datenschutz: Externe Schrift-URLs unterliegen CORS und der CSP-Direktive font-src. Einige Browser schränken das Erkennen lokal installierter Schriften ein, um Fingerprinting zu erschweren.

Siehe auch

Document.fonts Set FontFace FontData CSSFontFaceRule