CSSFontFeatureValuesRule.fontFamily — Eigenschaft · JavaScript-Referenz

Signatur

CSSFontFeatureValuesRule.fontFamily

Beschreibung

Die Eigenschaft fontFamily gehört zu einem CSSFontFeatureValuesRule-Objekt, also zu einer @font-feature-values-At-Regel im CSSOM. Sie enthält die Familiennamen aus dem Kopf der Regel, zum Beispiel Font One bei @font-feature-values Font One { … }. Stehen dort mehrere Familien, liefert die Eigenschaft sie als kommagetrennte Liste.

Mit @font-feature-values gibt man OpenType-Features wie Stilsets, Schwungbuchstaben (swash) oder Ornamente für bestimmte Schriften eigene Namen. Diese Namen lassen sich danach in font-variant-alternates verwenden, etwa styleset(fancy). Über fontFamily findest du per Skript heraus, für welche Schrift eine solche Regel gilt. Das hilft beim Auswerten, Filtern oder Bearbeiten von Stylesheets, zum Beispiel in Theme-Editoren, Entwicklerwerkzeugen oder Tests.

Laut Spezifikation (CSS Fonts Module Level 4, CSSOM) ist das Attribut les- und schreibbar. Wenn du einen neuen Wert zuweist, gilt die Regel sofort für die neue Familie. Der Browser gibt den Wert in normalisierter (serialisierter) Form zurück. Anführungszeichen und Leerzeichen können deshalb anders aussehen als im Quelltext.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Schreiben: neue, kommagetrennte Liste von Familiennamen, z. B. `"Bodoni, 'Bodoni Moda'"`. Generische Familien wie `serif` sind hier nicht erlaubt.

Rückgabewert

Typ

string

Beschreibung

Die serialisierte Liste der Familiennamen, für die die Regel gilt, z. B. "Font One" oder "Font One, Font Two".

Beispiele

Familiennamen einer @font-feature-values-Regel auslesen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @font-feature-values Font One {
    @styleset { nice-style: 12; }
  }
  .fancy { font-family: "Font One"; font-variant-alternates: styleset(nice-style); }
`);

const rule = sheet.cssRules[0];
if (rule instanceof CSSFontFeatureValuesRule) {
  console.log(rule.fontFamily);
}

Font One

Alle Feature-Regeln eines Dokuments für eine bestimmte Schrift finden

// Durchsucht alle erreichbaren Stylesheets nach @font-feature-values-Regeln
const findFeatureRules = (family) => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // bei fremden Stylesheets ohne CORS: SecurityError
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (
        rule instanceof CSSFontFeatureValuesRule &&
        rule.fontFamily
          .split(',')
          .map((f) => f.trim().replace(/^['"]|['"]$/g, ''))
          .includes(family)
      ) {
        result.push(rule);
      }
    }
  }
  return result;
};

console.log(findFeatureRules('Font One').map((r) => r.cssText));

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

Regel zur Laufzeit auf eine andere Schrift umstellen

const style = document.createElement('style');
style.textContent = `@font-feature-values Font One { @swash { flourish: 1; } }`;
document.head.append(style);

const rule = style.sheet.cssRules[0];
console.log('vorher:', rule.fontFamily);

// Beim Schriftwechsel im Theme-Editor die Feature-Namen mitnehmen
rule.fontFamily = 'Font Two';
console.log('nachher:', rule.fontFamily);

vorher: Font One nachher: Font Two

// Wichtig · Fallstricke

Browser-Unterstützung: Firefox und Safari unterstützen @font-feature-values schon lange. Chromium-Browser erst ab Version 111. In älteren Chromium-Versionen existiert CSSFontFeatureValuesRule nicht, und die Regel wird beim Parsen verworfen. Deshalb vorher prüfen, z. B. mit 'CSSFontFeatureValuesRule' in window.
Serialisierung: Der zurückgegebene Text muss nicht exakt dem Quelltext entsprechen. Anführungszeichen können entfernt oder ergänzt werden, und Leerzeichen werden normalisiert. Für Vergleiche die Namen daher selbst normalisieren, statt Zeichenketten direkt zu vergleichen.
Schreibzugriff: Laut Spezifikation ist das Attribut schreibbar. Die Umsetzung in den Browsern unterscheidet sich aber. Ungültige Werte, z. B. generische Familien wie serif oder eine leere Zeichenkette, werden je nach Browser ignoriert oder führen zu einem Fehler.
Die veraltete Typprüfung über rule.type === CSSRule.FONT_FEATURE_VALUES_RULE (Wert 14) funktioniert nicht überall zuverlässig. Besser ist instanceof CSSFontFeatureValuesRule.
Bei Stylesheets von fremden Ursprüngen ohne CORS-Freigabe löst der Zugriff auf cssRules einen SecurityError aus.

Siehe auch

CSSFontFeatureValuesRule.characterVariant CSSFontFeatureValuesRule.annotation CSSFontFeatureValuesRule.ornaments CSSFontFeatureValuesRule.styleset CSSFontFeatureValuesRule.stylistic