CSSFontPaletteValuesRule.fontFamily — Eigenschaft · JavaScript-Referenz

Signatur

CSSFontPaletteValuesRule.fontFamily

Beschreibung

Die Eigenschaft fontFamily eines CSSFontPaletteValuesRule-Objekts gibt den Wert des font-family-Deskriptors einer @font-palette-values-Regel als String zurück. Die Regel legt eine eigene Farbpalette für Farbschriften fest (etwa COLRv0/COLRv1 oder OpenType-SVG). Der Deskriptor bestimmt, auf welche Schriftfamilien sich diese Palette bezieht.

Über das CSS Object Model (CSSOM) kannst du so zur Laufzeit prüfen, welche Paletten für welche Schriften definiert sind. Das hilft zum Beispiel beim Debuggen, bei Theme-Umschaltern oder bei Werkzeugen, die Stylesheets untersuchen und passende font-palette-Werte anbieten.

Die Eigenschaft ist schreibgeschützt. Eine Zuweisung ändert die Regel nicht. Wenn du die Zielschrift ändern willst, musst du die Regel löschen und neu einfügen, zum Beispiel mit CSSStyleSheet.deleteRule() und insertRule(). Fehlt der Deskriptor, ist der Wert ein leerer String.

Rückgabewert

Typ

string

Beschreibung

Die serialisierte Liste der Schriftfamilien aus dem font-family-Deskriptor, mehrere Namen durch Kommas getrennt (z. B. "Bixa, Nabla"). Fehlt der Deskriptor, ist der Wert "".

Beispiele

Schriftfamilie einer Paletten-Regel auslesen

const style = document.createElement('style');
style.textContent = `
  @font-palette-values --warm {
    font-family: Bixa;
    base-palette: 1;
    override-colors: 0 crimson;
  }
`;
document.head.append(style);

const rule = style.sheet.cssRules[0];
if (rule instanceof CSSFontPaletteValuesRule) {
  console.log(rule.name);       // Name der Palette
  console.log(rule.fontFamily); // Zielschrift
}

--warm Bixa

Alle Paletten im Dokument nach Schrift gruppieren

const palettesByFamily = () => {
  const map = new Map();
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Stylesheets (CORS) fehlschlagen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (!(rule instanceof CSSFontPaletteValuesRule)) continue;
      for (const family of rule.fontFamily.split(',').map((f) => f.trim())) {
        if (!map.has(family)) map.set(family, []);
        map.get(family).push(rule.name);
      }
    }
  }
  return map;
};

console.log(palettesByFamily());

Map(2) { 'Bixa' => ['--warm', '--cold'], 'Nabla' => ['--cold'] }

Mit einem konstruierbaren Stylesheet prüfen und die Palette anwenden

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @font-palette-values --neon {
    font-family: Nabla, Bixa;
    override-colors: 0 #0ff, 1 #f0f;
  }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const [rule] = sheet.cssRules;
const heading = document.querySelector('h1');
const families = rule.fontFamily.split(',').map((f) => f.trim());

// Palette nur setzen, wenn die Überschrift eine passende Schrift nutzt
const used = getComputedStyle(heading).fontFamily;
if (families.some((f) => used.includes(f))) {
  heading.style.fontPalette = rule.name;
}

// Zuweisung wird ignoriert (schreibgeschützt)
rule.fontFamily = 'Arial';
console.log(rule.fontFamily);

Nabla, Bixa

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert. Im Strict Mode (z. B. in ES-Modulen) wirft sie einen TypeError, weil nur ein Getter existiert. Zum Ändern die Regel neu einfügen.
Serialisierung: Der String entspricht der normalisierten Form des Browsers. Anführungszeichen um Namen mit Leerzeichen (z. B. "Bungee Spice") können erhalten bleiben. Vergleiche deshalb nicht exakt, sondern trenne an Kommas und entferne Leerzeichen und Anführungszeichen.
Die Palette wirkt nur bei Farbschriften (COLR/CPAL, OpenType-SVG). Bei normalen Schriften hat sie keinen sichtbaren Effekt, auch wenn fontFamily passt.
Bei Stylesheets von fremden Origins löst der Zugriff auf cssRules einen SecurityError aus. Deshalb im zweiten Beispiel try/catch.
Kompatibilität: Verfügbar ab Chrome/Edge 101, Firefox 107 und Safari 15.4. In älteren Browsern gibt es CSSFontPaletteValuesRule nicht; instanceof wirft dann einen ReferenceError. Vorher mit 'CSSFontPaletteValuesRule' in window prüfen.

Siehe auch

CSSFontFeatureValuesRule.fontFamily CSSFontPaletteValuesRule.name CSSFontPaletteValuesRule.basePalette CSSFontPaletteValuesRule.overrideColors CSSFontFeatureValuesRule.annotation