CSSFontFeatureValuesRule.swash — Eigenschaft · JavaScript-Referenz

Signatur

CSSFontFeatureValuesRule.swash

Beschreibung

Die Eigenschaft swash gehört zum Interface CSSFontFeatureValuesRule. Dieses Interface steht in der CSSOM-Schnittstelle für eine @font-feature-values-Regel. Dort können Sie OpenType-Glyphenvarianten einer Schriftfamilie mit eigenen, gut lesbaren Namen versehen. Der Unterblock @swash legt dabei Namen für Swash-Glyphen fest, also für verschnörkelte Zierbuchstaben (OpenType-Features swsh und cswh).

Zurückgegeben wird ein CSSFontFeatureValuesMap. Dieses Objekt verhält sich wie eine Map: Die Schlüssel sind die selbst gewählten Namen, z. B. fancy, die Werte sind Arrays mit Feature-Indizes, z. B. [1]. Die Eigenschaft selbst ist schreibgeschützt, Sie können ihr also kein neues Objekt zuweisen. Die Map ist aber veränderbar: Mit set(), delete() und clear() ändern Sie die Regel zur Laufzeit, und der Browser wendet die Änderung sofort an.

Typische Einsatzfälle sind Werkzeuge für die Typografie, Theme-Editoren und Debugging. Sie können auslesen, welche Swash-Namen für eine Schrift definiert sind, oder zur Laufzeit andere Glyphenvarianten zuordnen. Im CSS nutzen Sie die Namen dann über font-variant-alternates: swash(name).

Rückgabewert

Typ

CSSFontFeatureValuesMap

Beschreibung

Ein Map-ähnliches Objekt mit Einträgen der Form Name → number[]. Es unterstützt get(), set(), has(), delete(), clear(), forEach(), keys(), values(), entries() und size und lässt sich mit for...of durchlaufen.

Beispiele

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

// CSS im Dokument:
// @font-feature-values "Playfair Display" {
//   @swash { fancy: 1; extra: 2; }
// }

const findFeatureRules = () =>
  [...document.styleSheets].flatMap((sheet) => {
    try {
      return [...sheet.cssRules];
    } catch {
      return []; // Fremde Stylesheets ohne CORS überspringen
    }
  }).filter((rule) => rule instanceof CSSFontFeatureValuesRule);

for (const rule of findFeatureRules()) {
  console.log(`Schrift: ${rule.fontFamily}`);
  for (const [name, indices] of rule.swash) {
    console.log(`  swash(${name}) → Index ${indices.join(', ')}`);
  }
}

Schrift: "Playfair Display" swash(fancy) → Index 1 swash(extra) → Index 2

Swash-Variante zur Laufzeit ändern

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

if (rule && 'swash' in rule) {
  // Vorher: fancy → [1]
  rule.swash.set('fancy', [3]); // anderen Glyphenindex zuordnen
  console.log(rule.swash.get('fancy'));

  // Elemente mit font-variant-alternates: swash(fancy)
  // werden sofort neu gerendert.
}

[3]

Feature-Erkennung und Einträge verwalten

const supportsSwashMap =
  typeof CSSFontFeatureValuesRule !== 'undefined' &&
  'swash' in CSSFontFeatureValuesRule.prototype;

console.log('swash-Map unterstützt:', supportsSwashMap);

if (supportsSwashMap) {
  const sheet = new CSSStyleSheet();
  sheet.replaceSync('@font-feature-values Lora { @swash { zier: 1; } }');
  const rule = sheet.cssRules[0];

  console.log(rule.swash.has('zier'));   // true
  rule.swash.delete('zier');
  console.log(rule.swash.size);          // 0
}

swash-Map unterstützt: true true 0

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Map-Eigenschaften (swash, stylistic, styleset, characterVariant, ornaments, annotation) gibt es derzeit nur in Chromium-Browsern ab Version 111. Firefox kennt CSSFontFeatureValuesRule zwar, bietet aber nur fontFamily und valueText. Prüfen Sie die Unterstützung deshalb vorher mit 'swash' in rule.
Laut Spezifikation darf @swash pro Name genau einen Index haben. Die Werte kommen trotzdem immer als Array zurück, z. B. [1], und nicht als einzelne Zahl.
Ob eine Swash-Variante sichtbar wird, hängt davon ab, ob die Schrift die OpenType-Features swsh/cswh mit diesem Index tatsächlich enthält. Fehlt der Index, gibt es keine Fehlermeldung, die Schrift sieht einfach unverändert aus.
Bei Stylesheets von einem anderen Ursprung ohne CORS-Freigabe löst der Zugriff auf cssRules einen SecurityError aus. Fangen Sie diesen mit try/catch ab.
Die Eigenschaft ist schreibgeschützt: Eine Zuweisung wie rule.swash = … wird ignoriert, im Strict Mode gibt es einen TypeError. Ändern Sie stattdessen die Einträge über die Methoden der Map.

Siehe auch

CSSFontFeatureValuesMap.size CSSFontFeatureValuesRule.styleset CSSFontFeatureValuesRule.stylistic CSSFontFeatureValuesRule.ornaments CSSFontFeatureValuesRule.annotation