CSSFontFeatureValuesRule.styleset — Eigenschaft · JavaScript-Referenz

Signatur

CSSFontFeatureValuesRule.styleset

Beschreibung

Die Eigenschaft styleset einer CSSFontFeatureValuesRule gibt den Inhalt des @styleset-Blocks innerhalb einer @font-feature-values-Regel wieder. Dort ordnet man selbst gewählten Namen (user-defined idents) einen oder mehrere Feature-Indizes zu. Diese Indizes verweisen auf die OpenType-Features ss01 bis ss20 (Stylistic Sets) einer Schrift. Im CSS setzt man die Namen dann über font-variant-alternates: styleset(name) ein.

Zurückgegeben wird ein CSSFontFeatureValuesMap-Objekt, das sich wie eine Map verhält: Schlüssel sind die Namen als Zeichenketten, Werte sind Arrays mit ganzzahligen Indizes. Anders als bei @swash oder @ornaments darf ein Name bei @styleset mehrere Indizes haben, z. B. fancy: 3 5;. So lassen sich mehrere Stylistic Sets gleichzeitig einschalten.

Die Eigenschaft selbst ist schreibgeschützt, man kann ihr also kein neues Objekt zuweisen. Die zurückgegebene Map lässt sich aber mit set(), delete() und clear() ändern. Solche Änderungen wirken sich direkt auf das CSSOM aus. Damit kann man zur Laufzeit neue Stil-Varianten festlegen oder vorhandene auslesen, zum Beispiel für einen Schrift-Konfigurator.

Rückgabewert

Typ

CSSFontFeatureValuesMap

Beschreibung

Ein Map-ähnliches Objekt (Map<string, number[]>). Es unterstützt get(), has(), set(), delete(), clear(), size, forEach() sowie die Iteration mit for…of, entries(), keys() und values().

Beispiele

Stylistic Sets aus einem Stylesheet auslesen

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);

console.log(rule.fontFamily);
console.log(rule.styleset.get('nice-style'));

for (const [name, indices] of rule.styleset) {
  console.log(`${name} → ss${indices.map((i) => String(i).padStart(2, '0')).join(' + ss')}`);
}

"Font One" [12] nice-style → ss12 fancy → ss03 + ss05

Neues Stylistic Set zur Laufzeit festlegen und anwenden

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @font-feature-values "Inter" { @styleset { alt-digits: 1; } }
  .headline { font-family: "Inter"; }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

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

// Mehrere Indizes: ss02 und ss04 zusammen aktivieren
rule.styleset.set('rounded', [2, 4]);

document.querySelector('.headline').style.fontVariantAlternates = 'styleset(rounded)';
console.log(rule.styleset.get('rounded'), rule.styleset.size);

[2, 4] 2

Einträge prüfen, entfernen und Unterstützung ermitteln

const getStylesetMap = (sheet) => {
  if (typeof CSSFontFeatureValuesRule === 'undefined') return null;
  const rule = [...sheet.cssRules]
    .find((r) => r instanceof CSSFontFeatureValuesRule);
  return rule && 'styleset' in rule ? rule.styleset : null;
};

const map = getStylesetMap(document.styleSheets[0]);
if (map) {
  if (map.has('fancy')) map.delete('fancy');
  console.log([...map.keys()]);
} else {
  console.log('styleset wird nicht unterstützt');
}

["nice-style"]

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft gibt es in Chromium-Browsern ab Version 111 und in Safari ab 17.4. Firefox kennt CSSFontFeatureValuesRule schon länger, stellt die Map-Eigenschaften wie styleset aber nicht oder nur teilweise bereit. Prüfen Sie deshalb vor dem Zugriff, ob die Eigenschaft vorhanden ist, etwa mit 'styleset' in rule.
Nur lesend – aber änderbar: rule.styleset = … hat keine Wirkung (im Strict Mode gibt es einen TypeError). Ändern Sie die Einträge stattdessen über die Methoden der Map.
Werte sind immer Arrays: Auch bei nur einem Index liefert get() ein Array, etwa [12]. Beim Setzen sind eine einzelne Zahl und ein Array beide erlaubt.
Gültiger Bereich: Es gibt nur die Stylistic Sets ss01 bis ss20, also die Indizes 1–20. Höhere Werte werden ignoriert, und hat die Schrift das Feature nicht, ändert sich die Darstellung nicht.
Keine variablen Achsen: Anders als manchmal angegeben betrifft styleset nicht die Achsen variabler Schriften (dafür gibt es font-variation-settings), sondern OpenType-Stylistic-Sets.
Stylesheets von anderen Domains ohne CORS-Freigabe lösen beim Zugriff auf cssRules einen SecurityError aus.

Siehe auch

CSSFontFeatureValuesRule.stylistic CSSFontFeatureValuesRule.swash CSSFontFeatureValuesRule.ornaments CSSFontFeatureValuesRule.fontFamily CSSFontFeatureValuesRule.annotation