FontFaceSet.keys() — Methode · JavaScript-Referenz

Signatur

FontFaceSet.prototype.keys()

Beschreibung

FontFaceSet.keys() liefert einen neuen Iterator, der alle im Set enthaltenen FontFace-Objekte in der Reihenfolge ausgibt, in der sie hinzugefügt wurden. FontFaceSet verhält sich wie ein Set. Dort sind Schlüssel und Werte identisch, deshalb ist keys() nur ein Alias für values(). Beide Methoden liefern exakt dieselben Einträge.

Das wichtigste FontFaceSet erreicht man über document.fonts, in Workern über self.fonts. Es enthält alle Schriften, die per CSS-@font-face deklariert oder per JavaScript mit document.fonts.add() hinzugefügt wurden. Mit keys() kann man diese Schriften durchlaufen, zum Beispiel um ihren Ladestatus zu prüfen, zu Debug-Zwecken aufzulisten oder bestimmte Schriften gezielt nachzuladen.

In der Praxis schreibt man meist direkt for (const font of document.fonts), weil FontFaceSet selbst iterierbar ist. keys() lohnt sich vor allem, wenn man ausdrücklich ein Iterator-Objekt braucht, etwa für Array.from(), den Spread-Operator oder die schrittweise Verarbeitung mit next().

Rückgabewert

Typ

Iterator<FontFace>

Beschreibung

Ein neuer Set-Iterator, der jedes FontFace-Objekt des Sets in Einfügereihenfolge liefert. Er ist identisch mit dem Rückgabewert von values().

Beispiele

Alle Schriften des Dokuments auflisten

// Alle registrierten Schriften mit Ladestatus ausgeben
for (const font of document.fonts.keys()) {
  console.log(`${font.family} (${font.weight}, ${font.style}): ${font.status}`);
}

"Inter" (400, normal): loaded "Inter" (700, normal): unloaded

Iterator manuell mit next() durchlaufen

const font = new FontFace('Roboto', 'url(/fonts/roboto.woff2)');
document.fonts.add(font);

const it = document.fonts.keys();
let result = it.next();
while (!result.done) {
  console.log(result.value.family);
  result = it.next();
}

Roboto

Nicht geladene Schriften gezielt nachladen

const loadPending = async () => {
  const pending = [...document.fonts.keys()]
    .filter((font) => font.status === 'unloaded');

  await Promise.all(pending.map((font) => font.load()));
  console.log(`${pending.length} Schrift(en) nachgeladen`);
};

loadPending();

2 Schrift(en) nachgeladen

keys() und values() sind gleichwertig

const keys = [...document.fonts.keys()];
const values = [...document.fonts.values()];

console.log(keys.length === values.length);
console.log(keys.every((font, i) => font === values[i]));

true true

// Wichtig · Fallstricke

Alias: keys() und values() liefern dieselben FontFace-Objekte. entries() liefert dagegen Paare der Form [font, font].
Nicht alle Einträge sind geladen: Der Iterator liefert auch Schriften mit dem Status unloaded oder error. Browser laden @font-face-Schriften erst, wenn sie tatsächlich verwendet werden. Wer auf alle Schriften warten will, nutzt document.fonts.ready.
Live-Iterator: Wird das Set während der Iteration mit add() oder delete() verändert, wirkt sich das wie bei Set auf den laufenden Iterator aus. Wer das vermeiden will, kopiert die Einträge vorher mit [...document.fonts] in ein Array.
CSS-Schriften: Schriften, die per CSS mit @font-face eingebunden sind, erscheinen zwar im Set, lassen sich aber nicht per delete() entfernen.
Kompatibilität: Die Methode wird von Chrome, Edge, Firefox und Safari in aktuellen Versionen unterstützt. In Workern ist das Set über self.fonts erreichbar, sofern der Browser das unterstützt.

Siehe auch

FontFaceSet.values() FontFaceSet.entries() FontFaceSet.forEach() FontFaceSet.add() FontFaceSet.ready FontFace FontFaceSet