CSSFontFeatureValuesMap.entries() — Methode · JavaScript-Referenz

Signatur

CSSFontFeatureValuesMap.prototype.entries()

Beschreibung

CSSFontFeatureValuesMap ist eine maplike-Schnittstelle. Sie steht für einen einzelnen Feature-Block innerhalb einer @font-feature-values-Regel, z. B. @styleset, @swash, @ornaments, @annotation, @stylistic oder @character-variant. Du erreichst diese Maps über die gleichnamigen Eigenschaften einer CSSFontFeatureValuesRule, also rule.styleset, rule.swash, rule.characterVariant usw.

entries() verhält sich genau wie Map.prototype.entries(). Die Methode gibt einen Iterator zurück, der für jede Deklaration ein Array [name, werte] liefert. name ist der selbst vergebene Bezeichner (z. B. "fancy"), und werte ist ein Array aus ganzzahligen Feature-Indizes (z. B. [1, 3]).

Die Methode eignet sich, um die in CSS definierten Aliasse für OpenType-Features per Skript auszulesen, etwa für Debugging-Werkzeuge, Schriften-Vorschauen oder um eine Auswahl der verfügbaren Stilsets im Interface anzuzeigen. Da die Map selbst iterierbar ist, liefert for...of direkt über die Map dasselbe Ergebnis wie entries().

Rückgabewert

Typ

Iterator<[string, number[]]>

Beschreibung

Ein neuer Map-Iterator. Jeder Schritt liefert ein Array [key, value]: key ist der Name der Deklaration (String), value ist ein Array aus vorzeichenlosen Ganzzahlen, den Feature-Indizes.

Beispiele

Stilsets einer @font-feature-values-Regel auflisten

// CSS im Dokument:
// @font-feature-values MyFont {
//   @styleset { fancy: 1; alt-g: 2 4; }
// }
const style = document.createElement('style');
style.textContent = `
  @font-feature-values MyFont {
    @styleset { fancy: 1; alt-g: 2 4; }
  }`;
document.head.append(style);

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

for (const [name, values] of rule.styleset.entries()) {
  console.log(name, values);
}

fancy [1] alt-g [2, 4]

Iterator manuell mit next() durchlaufen

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

const it = rule.swash.entries();
console.log(it.next()); // erstes Paar
console.log(it.next()); // weiteres Paar oder done: true

{ value: ['flowing', [1]], done: false } { value: undefined, done: true }

Alle Feature-Blöcke in ein Objekt umwandeln

const blocks = ['styleset', 'stylistic', 'swash', 'ornaments', 'annotation', 'characterVariant'];

const dumpFeatureValues = (rule) =>
  Object.fromEntries(
    blocks
      .filter((b) => rule[b] && rule[b].size > 0)
      .map((b) => [b, Object.fromEntries(rule[b].entries())])
  );

const rule = [...document.styleSheets[0].cssRules]
  .find((r) => r instanceof CSSFontFeatureValuesRule);

if (rule) console.log(JSON.stringify(dumpFeatureValues(rule)));

{"styleset":{"fancy":[1],"alt-g":[2,4]}}

// Wichtig · Fallstricke

Browser-Unterstützung: Die @font-feature-values-Regel funktioniert in allen modernen Browsern. Das Objektmodell mit CSSFontFeatureValuesMap ist aber uneinheitlich umgesetzt: Chromium ab Version 111 unterstützt es, Firefox nur teilweise, und ältere Safari-Versionen stellen nur valueText bereit. Prüfe deshalb vorher, ob es vorhanden ist, z. B. mit 'CSSFontFeatureValuesMap' in window oder rule.styleset?.entries.
Der Iterator ist eine Momentaufnahme ohne eigene Kopie. Wenn du die Map während der Iteration mit set() oder delete() änderst, wirkt sich das auf die weitere Iteration aus. Das Verhalten entspricht dem von Map.
Die Werte sind immer Arrays, auch wenn im CSS nur eine Zahl steht (fancy: 1 ergibt [1]).
Ein Iterator lässt sich nur einmal durchlaufen. Brauchst du die Daten mehrfach, rufe entries() erneut auf oder wandle das Ergebnis mit Array.from() in ein Array um.
Regeln aus Stylesheets anderer Herkunft (Cross-Origin) ohne CORS-Freigabe kannst du nicht lesen: Der Zugriff auf cssRules wirft dann einen SecurityError.

Siehe auch

Map.prototype.entries() CSSFontFeatureValuesMap.forEach() CSSFontFeatureValuesMap.values() CSSFontFeatureValuesMap.delete() CSSFontFeatureValuesMap.get()