FontFaceSet.add() — Methode · JavaScript-Referenz

Signatur

FontFaceSet.prototype.add(font)

Beschreibung

Mit add() registrieren Sie eine Schrift, die Sie mit dem Konstruktor new FontFace() erzeugt haben, in einem FontFaceSet. In der Praxis ist das fast immer document.fonts (im Hauptthread) bzw. self.fonts (in Workern). Erst nachdem die Schrift im Set ist, kann CSS sie über ihren font-family-Namen verwenden. Die Wirkung entspricht einer @font-face-Regel, nur eben per Skript.

Typisch ist das dynamische Nachladen von Schriften: Designer-Werkzeuge, in denen Nutzer Schriften auswählen, Canvas-Anwendungen, die eine Schrift vor dem Zeichnen sicher geladen haben müssen, oder Schriften, die aus einem ArrayBuffer kommen, zum Beispiel aus IndexedDB oder einem Upload.

Wichtig: add() fügt die Schrift nur hinzu, lädt sie aber nicht. Das Laden startet erst, wenn Sie fontFace.load() aufrufen, wenn Sie document.fonts.load() nutzen oder wenn der Browser die Schrift beim Rendern braucht. Für ein vorhersagbares Verhalten sollten Sie zuerst await fontFace.load() ausführen und danach add() aufrufen.

Die Methode gibt das Set selbst zurück, deshalb lassen sich Aufrufe verketten. Ist dieselbe FontFace-Instanz schon im Set, passiert nichts.

Parameter

Name	Typ	Default	Beschreibung
$font Pflicht	FontFace		Das `FontFace`-Objekt, das hinzugefügt werden soll. Es muss per `new FontFace()` erzeugt worden sein. Schriften, die aus einer CSS-Regel `@font-face` stammen, sind nicht erlaubt.

Rückgabewert

Typ

FontFaceSet

Beschreibung

Das FontFaceSet, auf dem add() aufgerufen wurde. Damit sind verkettete Aufrufe möglich.

Beispiele

Webfont per Skript laden und registrieren

const loadBrandFont = async () => {
  const font = new FontFace(
    'Brand Sans',
    'url(/fonts/brand-sans.woff2) format("woff2")',
    { weight: '400', style: 'normal', display: 'swap' }
  );

  // Erst laden, dann hinzufügen, damit kein Umschalten der Schrift sichtbar wird
  await font.load();
  document.fonts.add(font);

  document.body.style.fontFamily = '"Brand Sans", sans-serif';
  console.log(font.status, document.fonts.has(font));
};

loadBrandFont().catch((err) => console.error('Schrift konnte nicht geladen werden:', err));

loaded true

Schrift vor dem Zeichnen im Canvas sicherstellen

const drawTitle = async (canvas) => {
  const font = new FontFace('Headline', 'url(/fonts/headline.woff2)');
  document.fonts.add(await font.load());

  const ctx = canvas.getContext('2d');
  ctx.font = '48px Headline';
  ctx.fillText('Hallo Welt', 20, 60);
};

drawTitle(document.querySelector('canvas'));

Mehrere Schnitte aus ArrayBuffern verkettet hinzufügen

const registerFamily = async () => {
  const [regular, bold] = await Promise.all([
    fetch('/fonts/inter-regular.woff2').then((r) => r.arrayBuffer()),
    fetch('/fonts/inter-bold.woff2').then((r) => r.arrayBuffer())
  ]);

  // Bei ArrayBuffer-Quellen sind die Daten sofort da, trotzdem load() abwarten
  const faces = [
    new FontFace('Inter', regular, { weight: '400' }),
    new FontFace('Inter', bold, { weight: '700' })
  ];
  await Promise.all(faces.map((f) => f.load()));

  // add() gibt das Set zurück, daher ist Verkettung möglich
  document.fonts.add(faces[0]).add(faces[1]);
  console.log(document.fonts.check('700 16px Inter'));
};

registerFamily();

true

Fehler bei CSS-verknüpften Schriften abfangen

// Angenommen, das Stylesheet enthält eine @font-face-Regel für 'CssFont'
const cssFace = [...document.fonts].find((f) => f.family === 'CssFont');

try {
  document.fonts.add(cssFace);
} catch (err) {
  console.log(err.name);
}

InvalidModificationError

// Wichtig · Fallstricke

Kein automatisches Laden: Nach add() hat die Schrift weiterhin den Status "unloaded", bis ein Ladevorgang startet. Rufen Sie fontFace.load() auf oder warten Sie auf document.fonts.ready.
InvalidModificationError: Stammt ein FontFace aus einer CSS-Regel @font-face, löst add() eine DOMException mit dem Namen InvalidModificationError aus. Solche Schriften werden über CSS verwaltet.
TypeError: Wird kein FontFace übergeben, etwa ein String, gibt es einen TypeError.
Doppelte Instanzen: Ist dieselbe Instanz schon im Set, hat ein erneuter Aufruf keine Wirkung. Zwei verschiedene Instanzen mit denselben Angaben werden dagegen beide aufgenommen. Vermeiden Sie das, zum Beispiel mit einer Prüfung über has().
Sicherheit und CORS: Schriften von fremden Domains brauchen passende CORS-Header (Access-Control-Allow-Origin). Außerdem muss die Direktive font-src der CSP die Quelle erlauben, sonst schlägt load() fehl.
Kompatibilität: Die Methode wird von allen aktuellen Browsern unterstützt. In Web Workern steht sie über self.fonts zur Verfügung, zum Beispiel für OffscreenCanvas. Dort ist die Unterstützung bei älteren Safari-Versionen aber lückenhaft.

Siehe auch

FontFaceSet FontFace FontFace.prototype.load() FontFaceSet.prototype.delete() FontFaceSet.prototype.has() FontFaceSet.prototype.load() FontFaceSet.prototype.check() FontFaceSet.ready Document.fonts