CSSFontFeatureValuesMap.set() — Methode · JavaScript-Referenz

Signatur

CSSFontFeatureValuesMap.prototype.set(featureValueName, values)

Beschreibung

set() ändert zur Laufzeit die Einträge einer @font-feature-values-Regel. Jede CSSFontFeatureValuesRule hat mehrere Maps, nämlich annotation, ornaments, stylistic, swash, characterVariant und styleset. Jede Map ordnet einem frei wählbaren Namen einen oder mehrere OpenType-Feature-Indizes zu. Diese Namen stehen anschließend in CSS über font-variant-alternates zur Verfügung, zum Beispiel als font-variant-alternates: styleset(elegant).

Die Map verhält sich wie eine maplike-Struktur, ähnlich einer normalen Map. Gibt es den Schlüssel noch nicht, legt set() ihn an. Gibt es ihn schon, wird sein Wert ersetzt. Als Wert ist eine einzelne nicht-negative Ganzzahl oder ein Array von Ganzzahlen erlaubt. Intern speichert der Browser den Wert immer als Array.

Das ist nützlich, wenn eine Oberfläche typografische Alternativen einer Schrift austauschen soll, ohne das Stylesheet als Text neu zu schreiben. Ein Beispiel ist ein Schrift-Konfigurator, der zwischen Stilsets einer Variable Font wechselt. Alle Elemente, die den Namen verwenden, werden nach der Änderung sofort neu dargestellt.

Parameter

Name	Typ	Default	Beschreibung
$featureValueName Pflicht	string		Name des Feature-Werts, wie er später in `font-variant-alternates` verwendet wird, z. B. `"elegant"`.
$values Pflicht	number \| number[]		Ein Feature-Index oder eine Liste davon (nicht-negative Ganzzahlen). Wie viele Werte erlaubt sind, hängt von der Map ab: `swash`, `ornaments`, `annotation` und `stylistic` erlauben genau einen, `characterVariant` bis zu zwei, `styleset` beliebig viele.

Rückgabewert

Typ

CSSFontFeatureValuesMap | undefined

Beschreibung

Laut MDN die Map selbst, so wie bei Map.prototype.set(). Die Spezifikation definiert set() allerdings mit dem Rückgabetyp undefined. Verkette Aufrufe deshalb nicht.

Beispiele

Stilset-Namen zur Laufzeit hinzufügen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @font-feature-values "Fira Sans" {
    @styleset { klassisch: 1; }
  }
  h1 { font-family: "Fira Sans"; font-variant-alternates: styleset(elegant); }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

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

// Neuen Namen anlegen: ss02 + ss05
rule.styleset.set("elegant", [2, 5]);

console.log(rule.styleset.get("elegant"));
console.log(rule.styleset.size);

[2, 5] 2

Bestehenden Eintrag überschreiben

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

if (rule) {
  console.log(rule.swash.get("fancy")); // z. B. [1]
  rule.swash.set("fancy", 3);           // Einzelwert wird zu [3]
  console.log(rule.swash.get("fancy"));
}

[1] [3]

Ungültige Anzahl von Werten abfangen

const sheet = new CSSStyleSheet();
sheet.replaceSync('@font-feature-values "Demo" { @swash { a: 1; } }');
const rule = sheet.cssRules[0];

try {
  // swash erlaubt nur einen einzigen Wert
  rule.swash.set("zuViel", [1, 2]);
} catch (err) {
  console.log(err.name);
}

InvalidAccessError

// Wichtig · Fallstricke

Browser-Unterstützung: Die Map-Eigenschaften von CSSFontFeatureValuesRule gibt es erst in neueren Chromium-Versionen (ab 111) und in Safari. Firefox unterstützt @font-feature-values schon lange, die CSSOM-Maps aber nicht vollständig. Prüfe die Unterstützung vorher, z. B. mit 'styleset' in CSSFontFeatureValuesRule.prototype.
Werte werden immer als Array gespeichert. Auch nach set(\"x\", 3) gibt get(\"x\") [3] zurück.
Überschreitet die Zahl der Werte die Grenze der jeweiligen Map (z. B. mehr als einer bei swash), löst set() einen Fehler aus. In Chromium ist das ein InvalidAccessError.
Negative Zahlen oder Kommazahlen werden gemäß WebIDL in unsigned long umgewandelt. Das kann zu unerwarteten Indizes führen. Prüfe die Werte deshalb vorher selbst.
Die Änderung wirkt sich nur aus, wenn die Schrift das entsprechende OpenType-Feature wirklich enthält (z. B. ss02). Andernfalls wird nichts sichtbar.
Stylesheets von fremden Ursprüngen ohne CORS-Freigabe sind nicht lesbar. Schon der Zugriff auf cssRules löst einen SecurityError aus.

Siehe auch

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