CSSFontFeatureValuesMap — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFontFeatureValuesMap

Beschreibung

CSSFontFeatureValuesMap ist ein Interface des CSS Object Model (CSSOM). Es stellt den Inhalt eines einzelnen Feature-Blocks innerhalb einer @font-feature-values-Regel dar, also z. B. @swash, @annotation, @ornaments, @stylistic, @styleset oder @character-variant. Jeder Eintrag ordnet einem selbst gewählten Namen (z. B. fancy) eine Liste von Ganzzahlen zu, die den OpenType-Feature-Index der Schrift angeben.

Instanzen erzeugt man nicht selbst. Man erhält sie über die Eigenschaften eines CSSFontFeatureValuesRule-Objekts: rule.swash, rule.annotation, rule.ornaments, rule.stylistic, rule.styleset und rule.characterVariant. Jede dieser Eigenschaften liefert eine eigene CSSFontFeatureValuesMap.

Das Interface verhält sich wie eine Map<string, number[]> und bietet die üblichen Map-Methoden an:

size: Anzahl der Einträge
get(name), has(name): einzelne Werte abfragen
keys(), values(), entries(), forEach(), [Symbol.iterator](): Einträge durchlaufen
set(name, values), delete(name), clear(): Einträge ändern, sofern der Browser das zulässt

Einsatzbereiche sind Werkzeuge, die Stylesheets auslesen (Typografie-Inspektoren, Designsystem-Dokumentation), und dynamische Anpassungen. Damit lässt sich etwa zur Laufzeit festlegen, welcher Swash-Index für font-variant-alternates: swash(fancy) gilt.

Parameter

Name	Typ	Beschreibung
$featureValueName Pflicht	string	Für `get()`, `has()`, `set()` und `delete()`: der in CSS vergebene Name des Feature-Werts, z. B. `fancy`. Groß- und Kleinschreibung wird unterschieden.
$values	number \| number[]	Nur bei `set()`: der neue Feature-Index als nicht-negative Ganzzahl oder als Liste von Ganzzahlen, etwa bei `@character-variant` mit zwei Werten.
$callback	(value: number[], key: string, map: CSSFontFeatureValuesMap) => void	Nur bei `forEach()`: wird für jeden Eintrag aufgerufen.

Rückgabewert

Typ

CSSFontFeatureValuesMap

Beschreibung

Wird über die Eigenschaften von CSSFontFeatureValuesRule abgerufen. get() liefert ein number[] oder undefined, has() liefert ein boolean, die Iteratoren liefern Paare der Form [string, number[]].

Beispiele

Swash-Werte einer @font-feature-values-Regel auslesen

// CSS im Dokument:
// @font-feature-values "Font One" { @swash { fancy: 12; plain: 1; } }
const style = document.createElement('style');
style.textContent = `@font-feature-values "Font One" { @swash { fancy: 12; plain: 1; } }`;
document.head.append(style);

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

const swashMap = rule.swash; // CSSFontFeatureValuesMap
console.log(swashMap.size);
for (const [name, values] of swashMap) {
  console.log(name, values);
}

2 fancy [12] plain [1]

Einzelnen Wert prüfen und abfragen

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

if (rule?.swash.has('fancy')) {
  const [index] = rule.swash.get('fancy');
  console.log(`Swash "fancy" nutzt Index ${index}`);
} else {
  console.log('Kein Swash "fancy" definiert');
}

Swash "fancy" nutzt Index 12

Feature-Index zur Laufzeit ändern

const style = document.createElement('style');
style.textContent = `
  @font-feature-values "Font One" { @styleset { alt-a: 1; } }
  h1 { font-family: "Font One"; font-variant-alternates: styleset(alt-a); }
`;
document.head.append(style);

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

// Styleset 1 durch Styleset 3 ersetzen, h1 wird neu gerendert
if (typeof rule.styleset.set === 'function') {
  rule.styleset.set('alt-a', 3);
}
console.log(rule.styleset.get('alt-a'));
console.log(rule.cssText.includes('alt-a: 3'));

[3] true

// Wichtig · Fallstricke

Browser-Kompatibilität: @font-feature-values und die CSSOM-Schnittstellen dazu gibt es in Chromium erst ab Version 111. Firefox unterstützt die Regel schon länger. Ob Safari und ältere Browser einzelne Methoden wie set() anbieten, ist unterschiedlich. Vorher prüfen, z. B. mit 'CSSFontFeatureValuesRule' in window.
Werte werden immer als Array zurückgegeben, auch wenn in CSS nur eine Zahl steht (fancy: 12 ergibt [12]).
Wie viele Werte gültig sind, hängt vom Block ab. @swash, @annotation und @stylistic erlauben genau einen Wert, @character-variant einen oder zwei, @styleset mehrere. Ungültige Angaben werden ignoriert oder lösen einen Fehler aus.
Die Namen gelten nur für die Schriftfamilien, die in der Regel angegeben sind. Ein Name wie swash(fancy) wirkt nur, wenn die Schrift das Feature tatsächlich enthält.
Stylesheets von fremden Ursprüngen ohne CORS-Freigabe können nicht gelesen werden. Der Zugriff auf cssRules löst dann einen SecurityError aus.

Siehe auch

Map CSSFontFeatureValuesRule CSSFontPaletteValuesRule CSSFontFaceRule CSSFontFaceDescriptors