CSSFontFeatureValuesRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFontFeatureValuesRule extends CSSRule

Beschreibung

Mit der At-Regel @font-feature-values gibt man OpenType-Funktionen einer bestimmten Schriftfamilie lesbare Namen, z. B. @styleset { elegant: 1; }. Diese Namen verwendet man danach in font-variant-alternates, etwa mit styleset(elegant), statt direkt mit dem Index in font-feature-settings zu arbeiten. CSSFontFeatureValuesRule ist die Darstellung dieser Regel im CSS-Objektmodell. Man findet sie in CSSStyleSheet.cssRules.

Die Schnittstelle erbt von CSSRule, also auch cssText, parentStyleSheet und parentRule. Sie hat außerdem diese Eigenschaften:

fontFamily (string): die Schriftfamilie(n), für die die Regel gilt. Die Eigenschaft ist les- und schreibbar.
annotation, ornaments, stylistic, swash, characterVariant, styleset (jeweils CSSFontFeatureValuesMap): Map-ähnliche Objekte, die jedem Namen ein Array von Feature-Indizes zuordnen. Sie haben get(), set(), has(), delete() und lassen sich durchlaufen.

Die Schnittstelle ist vor allem für Werkzeuge nützlich, die Stylesheets untersuchen, für Theme-Editoren und für Design-Systeme, die typografische Alternativen zur Laufzeit anpassen. Einen Konstruktor gibt es nicht. Instanzen entstehen nur, wenn der Browser CSS parst, also über ein Stylesheet oder insertRule().

Rückgabewert

Typ

CSSFontFeatureValuesRule

Beschreibung

Kein Konstruktor. Instanzen bekommt man über CSSStyleSheet.cssRules oder CSSGroupingRule.cssRules.

Beispiele

Regeln im Dokument finden und die Schriftfamilie auslesen

// CSS: @font-feature-values "Font One" { @styleset { nice-style: 12; } }
const findFeatureRules = () =>
  [...document.styleSheets].flatMap((sheet) => {
    try {
      return [...sheet.cssRules];
    } catch {
      return []; // Stylesheets von fremden Origins sind nicht lesbar
    }
  }).filter((rule) => rule instanceof CSSFontFeatureValuesRule);

for (const rule of findFeatureRules()) {
  console.log(rule.fontFamily);
  console.log(rule.cssText);
}

"Font One" @font-feature-values "Font One" { @styleset { nice-style: 12; } }

Regel per insertRule() anlegen und benannte Werte lesen

const style = document.createElement('style');
document.head.append(style);
const sheet = style.sheet;

const index = sheet.insertRule(
  '@font-feature-values Inter { @styleset { rund: 1; } @swash { schwung: 2; } }'
);
const rule = sheet.cssRules[index];

console.log(rule instanceof CSSFontFeatureValuesRule);
console.log(rule.fontFamily);

// Die Maps gibt es nicht in jedem Browser, deshalb vorher prüfen
if ('styleset' in rule) {
  console.log(rule.styleset.get('rund'));
  console.log(rule.swash.has('schwung'));
}

true Inter [1] true

Stylesets zur Laufzeit ändern (Theme-Umschaltung)

// Voraussetzung: rule ist eine CSSFontFeatureValuesRule für "Inter"
// und das CSS enthält: h1 { font-family: Inter; font-variant-alternates: styleset(headline); }
const setHeadlineStyleset = (rule, ...indices) => {
  if (!('styleset' in rule)) {
    console.warn('CSSFontFeatureValuesMap wird nicht unterstützt');
    return;
  }
  rule.styleset.set('headline', indices);
};

setHeadlineStyleset(rule, 3, 7); // ss03 und ss07 aktivieren

for (const [name, values] of rule.styleset) {
  console.log(name, values);
}

headline [3, 7]

// Wichtig · Fallstricke

Unterschiedliche Unterstützung: fontFamily funktioniert in allen aktuellen Browsern. Die CSSFontFeatureValuesMap-Eigenschaften (styleset, swash usw.) fehlen dagegen in manchen Engines, vor allem in älteren Firefox-Versionen. Firefox hat stattdessen die nicht standardisierte Eigenschaft valueText. Vor der Nutzung mit 'styleset' in rule prüfen.
Kein Konstruktor: new CSSFontFeatureValuesRule() wirft einen TypeError. Regeln deshalb über insertRule() oder replaceSync() erzeugen.
Fremde Origins: Greift man auf cssRules eines Stylesheets von einem anderen Origin zu, wirft der Browser einen SecurityError. Der Zugriff klappt nur, wenn das Stylesheet mit CORS geladen wurde (crossorigin).
Werte bei der Zuweisung: set() erwartet nicht-negative Ganzzahlen. Wie viele Werte erlaubt sind, hängt vom Feature-Typ ab. @swash akzeptiert zum Beispiel nur einen einzigen Wert, @styleset dagegen mehrere. Unzulässige Werte führen je nach Browser zu einer Ausnahme oder werden ignoriert.
Die Namen wirken nur, wenn die Schrift die entsprechenden OpenType-Features wirklich enthält. Ansonsten ändert sich die Darstellung ohne Meldung nicht.

Siehe auch

CSSFontFeatureValuesMap CSSFontPaletteValuesRule CSSFontFaceRule CSSCounterStyleRule CSSContainerRule