FontFaceSet.load() — Methode · JavaScript-Referenz

Signatur

FontFaceSet.prototype.load(font, text)

Beschreibung

load() wird auf einem FontFaceSet aufgerufen, meist auf document.fonts (im Worker: self.fonts). Die Methode ermittelt anhand einer CSS-Kurzschreibweise für font (z. B. "bold 16px Roboto") alle passenden FontFace-Einträge und startet deren Download, falls sie noch nicht geladen sind. Das Ergebnis ist ein Promise, das mit einem Array der passenden FontFace-Objekte erfüllt wird.

Das ist nützlich, weil Browser Webfonts normalerweise lazy laden: Eine per @font-face deklarierte Schrift wird erst heruntergeladen, wenn Text sie tatsächlich benötigt. Mit load() kann man den Download gezielt anstoßen – etwa bevor man Text auf ein <canvas> zeichnet, Textbreiten misst oder einen Layout-Sprung (FOUT/FOIT) vermeiden will.

Über den optionalen Parameter text wird die Auswahl auf Schriften eingegrenzt, deren unicode-range mindestens ein Zeichen dieses Textes abdeckt. So lassen sich bei aufgeteilten Schriftdateien (z. B. getrennt für Latein und Kyrillisch) nur die wirklich benötigten Teile laden.

Passt keine Schrift zur Angabe, wird das Promise mit einem leeren Array erfüllt – nicht abgelehnt. Abgelehnt wird es, wenn die Font-Angabe syntaktisch ungültig ist (SyntaxError) oder das Laden einer passenden Schrift fehlschlägt.

Parameter

Name	Typ	Default	Beschreibung
$font Pflicht	string		Schriftangabe in der Syntax der CSS-Eigenschaft `font`, z. B. `"italic 700 1em 'Open Sans'"`. Größe und Familie sind Pflichtbestandteile.
$text	string	" " (Leerzeichen)	Beispieltext; es werden nur Schriften berücksichtigt, deren `unicode-range` mindestens ein Zeichen daraus enthält.

Beispiele

Schrift vor dem Zeichnen auf ein Canvas laden

// CSS: @font-face { font-family: 'Lobster'; src: url(/fonts/lobster.woff2); }
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const drawTitle = async () => {
  const fonts = await document.fonts.load("48px 'Lobster'");
  console.log(`${fonts.length} Schrift(en) geladen`);
  ctx.font = "48px 'Lobster'";
  ctx.fillText('Hallo Welt', 20, 60);
};

drawTitle();

1 Schrift(en) geladen

Mehrere Schnitte parallel laden und Fehler abfangen

const preloadFonts = async () => {
  try {
    const results = await Promise.all([
      document.fonts.load("400 1em 'Inter'"),
      document.fonts.load("700 1em 'Inter'"),
      document.fonts.load("italic 400 1em 'Inter'")
    ]);
    const loaded = results.flat();
    loaded.forEach((face) => console.log(face.family, face.weight, face.style, face.status));
    document.documentElement.classList.add('fonts-loaded');
  } catch (err) {
    console.error('Schrift konnte nicht geladen werden:', err);
  }
};

preloadFonts();

Inter 400 normal loaded Inter 700 normal loaded Inter 400 italic loaded

Mit Text-Parameter nur den benötigten Unicode-Bereich laden

// Die Schrift 'Noto Sans' ist in mehrere Dateien mit unicode-range aufgeteilt
const loadForText = async (text) => {
  const faces = await document.fonts.load("16px 'Noto Sans'", text);
  if (faces.length === 0) {
    console.log('Keine passende Schrift – Fallback wird verwendet');
    return;
  }
  console.log('Geladene Bereiche:', faces.map((f) => f.unicodeRange));
};

loadForText('Привет');

Geladene Bereiche: [ 'U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116' ]

FontFace per JavaScript hinzufügen und laden

const face = new FontFace('Brand', 'url(/fonts/brand.woff2)', { weight: '600' });
document.fonts.add(face);

const [loaded] = await document.fonts.load("600 20px 'Brand'");
console.log(loaded === face, loaded.status);

true loaded

// Wichtig · Fallstricke

Leeres Array statt Fehler: Tippfehler im Familiennamen führen nicht zu einer Ablehnung, sondern zu []. Prüfe daher result.length, wenn die Schrift zwingend nötig ist.
Größe ist Pflicht: document.fonts.load(\"Roboto\") ist ungültig und wirft einen SyntaxError (abgelehntes Promise). Immer eine Größe angeben, z. B. \"1em Roboto\"; Familiennamen mit Leerzeichen in Anführungszeichen setzen.
Systemschriften: Lokal installierte Schriften, die nicht per @font-face oder FontFace registriert sind, gehören nicht zum FontFaceSet – das Ergebnis ist dann leer.
CORS: Webfonts von fremden Ursprüngen benötigen passende Access-Control-Allow-Origin-Header, sonst schlägt das Laden fehl und das Promise wird abgelehnt. Auch die CSP-Direktive font-src muss die Quelle erlauben.
load() wartet nur auf die passenden Schriften. Um auf alle anstehenden Ladevorgänge zu warten, eignet sich document.fonts.ready; zum synchronen Prüfen ohne Download document.fonts.check().
Kompatibilität: In allen aktuellen Browsern verfügbar; in Web Workern über self.fonts nicht überall (ältere Safari-Versionen). Internet Explorer wird nicht unterstützt.

Siehe auch

Document.fonts FontFaceSet.add() FontFaceSet.clear() FontFaceSet.has() FontFaceSet.keys()