CSSFontFeatureValuesMap.get() — Methode · JavaScript-Referenz

Signatur

CSSFontFeatureValuesMap.prototype.get(key)

Beschreibung

Mit der CSS-At-Regel @font-feature-values kann man OpenType-Features einer Schriftfamilie lesbare Namen geben, zum Beispiel @styleset { elegant: 3; }. Solche Namen verwendet man dann in font-variant-alternates. Im CSSOM steht jede dieser Regeln als CSSFontFeatureValuesRule zur Verfügung. Jeder Unterblock (@styleset, @swash, @annotation, @ornaments, @stylistic, @character-variant) ist dort eine eigene CSSFontFeatureValuesMap.

get() liest aus so einer Map den Wert zu einem Namen. Der Wert ist ein Array aus nicht-negativen Ganzzahlen, also die Feature-Indizes. Bei @styleset und @character-variant können das mehrere Zahlen sein, bei den anderen Blöcken ist es meist genau eine.

Die Schnittstelle verhält sich wie eine Map. Neben get() gibt es deshalb auch has(), set(), delete(), keys(), entries(), forEach() und size. Mit get() prüfen Sie zur Laufzeit, welche Feature-Namen ein Stylesheet festlegt, zum Beispiel für Schrift-Vorschauen, Design-Tools oder Tests.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Der selbst gewählte Feature-Name aus dem `@font-feature-values`-Block, zum Beispiel `"elegant"`. Groß- und Kleinschreibung zählt.

Rückgabewert

Typ

number[] | undefined

Beschreibung

Ein Array mit den Feature-Indizes, die unter key stehen, zum Beispiel [3] oder [2, 4]. Gibt es den Schlüssel nicht, kommt undefined zurück.

Beispiele

Styleset-Wert aus einer @font-feature-values-Regel lesen

const style = document.createElement('style');
style.textContent = `
  @font-feature-values Fancy Serif {
    @styleset { elegant: 3; alt-g: 2 4; }
    @swash { flowing: 1; }
  }
`;
document.head.append(style);

// Die Regel im Stylesheet suchen
const rule = [...style.sheet.cssRules]
  .find((r) => r instanceof CSSFontFeatureValuesRule);

console.log(rule.styleset.get('elegant'));
console.log(rule.styleset.get('alt-g'));
console.log(rule.swash.get('flowing'));
console.log(rule.swash.get('unbekannt'));

[3] [2, 4] [1] undefined

Sicherer Zugriff mit Rückfallwert

const getFeatureIndex = (rule, block, name, fallback = null) => {
  const map = rule?.[block];
  // Firefox kennt die Map-Eigenschaften nicht
  if (!map || typeof map.get !== 'function') return fallback;
  return map.get(name) ?? fallback;
};

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

console.log(getFeatureIndex(rule, 'styleset', 'elegant', [0]));

[3] (oder [0], falls der Schlüssel fehlt oder die API nicht unterstützt wird)

Alle Feature-Namen einer Schriftfamilie auflisten

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

for (const sheet of document.styleSheets) {
  let rules;
  try { rules = sheet.cssRules; } catch { continue; } // Fremd-Stylesheets (CORS)
  for (const rule of rules) {
    if (!(rule instanceof CSSFontFeatureValuesRule)) continue;
    for (const block of blocks) {
      const map = rule[block];
      if (!map) continue;
      for (const name of map.keys()) {
        console.log(`${rule.fontFamily} / ${block} / ${name}:`, map.get(name));
      }
    }
  }
}

Fancy Serif / styleset / elegant: [3] Fancy Serif / styleset / alt-g: [2, 4] Fancy Serif / swash / flowing: [1]

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (ab Version 111) und Safari stellen die Map-Eigenschaften wie styleset oder swash bereit. Firefox kennt CSSFontFeatureValuesRule, aber diese Maps nicht. Prüfen Sie deshalb vorher, ob die Eigenschaft existiert.
Der Rückgabewert ist immer ein Array, auch bei nur einem Index. Für einen Vergleich schreiben Sie also get('x')[0] === 3, nicht get('x') === 3.
Ist der Schlüssel falsch geschrieben oder stimmt die Groß-/Kleinschreibung nicht, kommt stillschweigend undefined zurück, ohne Fehlermeldung. Ein Rückfallwert mit ?? hilft hier.
Jede Map gehört zu genau einem Block. Ein Name, der unter @swash steht, taucht in styleset.get() nicht auf.
Wer cssRules von Stylesheets anderer Herkunft ohne CORS-Freigabe liest, bekommt eine SecurityError-Ausnahme.

Siehe auch

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