CSSFontFeatureValuesMap.keys() — Methode · JavaScript-Referenz

Signatur

CSSFontFeatureValuesMap.prototype.keys()

Beschreibung

Die Methode keys() einer CSSFontFeatureValuesMap liefert einen neuen Map-Iterator mit den Schlüsseln aller Einträge, in der Reihenfolge, in der sie eingefügt wurden. Anders als manche Kurzbeschreibungen behaupten, enthält der Iterator keine [key, value]-Paare. Die Paare bekommen Sie über entries(). Die Methode verhält sich wie Map.prototype.keys(), weil CSSFontFeatureValuesMap ein maplike-Interface ist.

Eine CSSFontFeatureValuesMap steht für einen Block innerhalb einer @font-feature-values-Regel, zum Beispiel @styleset, @swash, @ornaments, @annotation, @stylistic oder @character-variant. Sie erreichen diese Maps über die gleichnamigen Eigenschaften eines CSSFontFeatureValuesRule-Objekts (styleset, swash, ornaments, annotation, stylistic, characterVariant). Jeder Schlüssel ist ein frei gewählter Name wie "nice-style". Der zugehörige Wert ist ein Array von Ganzzahlen, also die OpenType-Feature-Indizes.

keys() ist nützlich, wenn Sie per Skript prüfen oder auflisten wollen, welche benannten Feature-Werte ein Stylesheet festlegt, etwa für Werkzeuge zur Schrift-Vorschau, Debugging-Hilfen oder dynamisch erzeugte Auswahlmenüs für font-variant-alternates.

Rückgabewert

Typ

Iterator<string>

Beschreibung

Ein neuer Map-Iterator, der die Schlüssel (Namen der Feature-Werte) als string in Einfügereihenfolge liefert.

Beispiele

Namen aus einem @styleset-Block auflisten

// Stylesheet mit @font-feature-values anlegen
const style = document.createElement('style');
style.textContent = `
  @font-feature-values Font One {
    @styleset {
      nice-style: 12;
      fancy: 3 5;
    }
  }
`;
document.head.append(style);

const rule = [...style.sheet.cssRules]
  .find((r) => r instanceof CSSFontFeatureValuesRule);

for (const name of rule.styleset.keys()) {
  console.log(name);
}

nice-style fancy

Schlüssel in ein Array umwandeln und Auswahlmenü befüllen

const rule = [...document.styleSheets]
  .flatMap((sheet) => {
    try { return [...sheet.cssRules]; } catch { return []; } // Cross-Origin-Sheets überspringen
  })
  .find((r) => r instanceof CSSFontFeatureValuesRule);

if (rule) {
  const names = Array.from(rule.swash.keys());
  const select = document.createElement('select');
  for (const name of names) {
    select.append(new Option(name, `swash(${name})`));
  }
  select.addEventListener('change', () => {
    document.body.style.fontVariantAlternates = select.value;
  });
  document.body.prepend(select);
  console.log(names);
}

["flowing", "swishy"] // abhängig vom Stylesheet

keys() im Vergleich zu entries()

const map = rule.styleset; // CSSFontFeatureValuesMap aus einer @font-feature-values-Regel

console.log([...map.keys()]);
console.log([...map.entries()]);

const it = map.keys();
console.log(it.next());

["nice-style", "fancy"] [["nice-style", [12]], ["fancy", [3, 5]]] { value: "nice-style", done: false }

// Wichtig · Fallstricke

Nur Schlüssel: keys() liefert ausschließlich die Namen. Für Name-Wert-Paare verwenden Sie entries() oder direkt for...of über die Map, für die Werte allein values().
Einmal verwendbar: Der Iterator lässt sich nur einmal durchlaufen. Für einen zweiten Durchlauf rufen Sie keys() erneut auf oder wandeln das Ergebnis mit Array.from() in ein Array um.
Live-Verhalten: Ändern Sie die Map während der Iteration (set(), delete()), wirkt sich das wie bei Map auf den laufenden Iterator aus.
Browser-Kompatibilität: CSSFontFeatureValuesMap wird erst in neueren Browsern unterstützt (u. a. Chromium 111+ und Safari 17.4+). In älteren Browsern fehlen die Map-Eigenschaften oder CSSFontFeatureValuesRule ganz. Prüfen Sie deshalb vorher mit typeof CSSFontFeatureValuesRule !== 'undefined'.
Cross-Origin-Stylesheets: Wenn Sie auf cssRules eines fremden Stylesheets ohne CORS-Freigabe zugreifen, wirft der Browser einen SecurityError. Fangen Sie diesen Fehler ab.

Siehe auch

Map.prototype.keys() CSSFontFeatureValuesMap.delete() CSSFontFeatureValuesMap.get() CSSFontFeatureValuesMap.has() CSSFontFeatureValuesMap.set()