CSSFontPaletteValuesRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFontPaletteValuesRule extends CSSRule

Beschreibung

Mit der At-Regel @font-palette-values legt man eigene Farbpaletten für Farbschriften fest, also für Schriften mit einer COLR- oder CPAL-Tabelle, etwa Emoji-Schriften oder mehrfarbige Icon-Fonts. Wenn der Browser das Stylesheet einliest, wird jede solche Regel als Objekt vom Typ CSSFontPaletteValuesRule abgebildet. Du findest diese Objekte in CSSStyleSheet.cssRules, genau wie andere Regeln vom Typ CSSRule.

Das Interface erbt von CSSRule und bringt diese schreibgeschützten Eigenschaften mit:

name: der Bezeichner der Palette, also ein Dashed-Ident wie --brand. Mit diesem Namen wird die Palette über font-palette angewendet.
fontFamily: der Wert des Deskriptors font-family, also die Schriftfamilie(n), für die die Palette gilt.
basePalette: der Wert des Deskriptors base-palette, zum Beispiel "1", "light" oder "dark". Ist er nicht gesetzt, ist der Wert ein leerer String.
overrideColors: der Wert des Deskriptors override-colors als String, zum Beispiel "0 red, 1 #00f".

Nützlich ist das Interface vor allem zum Auslesen und Prüfen: Du kannst etwa herausfinden, welche Paletten es gibt, und daraus einen Theme-Umschalter bauen. Außerdem hilft es beim Debuggen von Farbschriften. Ändern kannst du eine Palette nur, indem du die Regel entfernst und neu einfügst (deleteRule()/insertRule()). Alternativ wechselst du über die CSS-Eigenschaft font-palette einfach auf eine andere, schon definierte Palette.

Rückgabewert

Typ

CSSFontPaletteValuesRule

Beschreibung

Du erzeugst die Objekte nicht selbst. Der Browser legt sie beim Einlesen von @font-palette-values-Regeln an, und du erreichst sie über CSSStyleSheet.cssRules.

Beispiele

Alle Farbpaletten im Dokument auflisten

// Gleichnamigen Stil einfügen, damit das Beispiel eigenständig läuft
const style = document.createElement('style');
style.textContent = `
  @font-palette-values --brand {
    font-family: Bixa;
    base-palette: 1;
    override-colors: 0 #e63946, 1 #1d3557;
  }
`;
document.head.append(style);

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

for (const p of palettes) {
  console.log(p.name, '|', p.fontFamily, '|', p.basePalette, '|', p.overrideColors);
}

--brand | Bixa | 1 | 0 rgb(230, 57, 70), 1 rgb(29, 53, 87)

Palette per insertRule() anlegen und anwenden

const sheet = new CSSStyleSheet();
sheet.insertRule(`
  @font-palette-values --dark-icons {
    font-family: "Nabla";
    base-palette: dark;
    override-colors: 0 gold;
  }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[0];
console.log(rule instanceof CSSFontPaletteValuesRule, rule.name);

// Palette auf ein Element anwenden
document.body.style.fontFamily = 'Nabla';
document.body.style.fontPalette = rule.name;

true --dark-icons

Palette 'ändern' durch Ersetzen der Regel

const sheet = new CSSStyleSheet();
sheet.insertRule('@font-palette-values --theme { font-family: Bixa; override-colors: 0 red; }');
document.adoptedStyleSheets = [sheet];

const replacePaletteColors = (name, colors) => {
  const index = [...sheet.cssRules].findIndex(
    (r) => r instanceof CSSFontPaletteValuesRule && r.name === name
  );
  if (index === -1) return;
  const old = sheet.cssRules[index];
  sheet.deleteRule(index);
  sheet.insertRule(
    `@font-palette-values ${name} { font-family: ${old.fontFamily}; override-colors: ${colors}; }`,
    index
  );
};

replacePaletteColors('--theme', '0 green, 1 white');
console.log(sheet.cssRules[0].overrideColors);

0 green, 1 white

// Wichtig · Fallstricke

Schreibgeschützt: name, fontFamily, basePalette und overrideColors kannst du nur lesen. Zuweisungen werden ohne Fehlermeldung ignoriert. Wenn du etwas ändern willst, ersetze die Regel mit deleteRule()/insertRule().
Nur Farbschriften: Die Palette wirkt nur bei Schriften mit COLR/CPAL-Tabelle. Bei normalen Schriften ist sie gültig, zeigt aber keine sichtbare Wirkung.
Serialisierung: Wie der Browser Farben in overrideColors ausgibt, ist nicht einheitlich. Ein Browser liefert vielleicht rgb(...), ein anderer den Originalwert. Vergleiche die Strings deshalb nicht exakt.
Cross-Origin: Greifst du auf cssRules eines fremden Stylesheets ohne CORS-Freigabe zu, wirft der Browser einen SecurityError. Setze den Zugriff also in try/catch.
CSSRule.type: Für dieses Interface gibt es keine eigene Typ-Konstante. type liefert 0. Prüfe deshalb mit instanceof CSSFontPaletteValuesRule.
Kompatibilität: Das Interface ist ab Chrome/Edge 101, Firefox 107 und Safari 15.4 verfügbar. Ältere Browser erkennst du mit 'CSSFontPaletteValuesRule' in window oder CSS.supports('font-palette', 'dark').

Siehe auch

CSSFontFeatureValuesRule CSSFontFeatureValuesMap CSSFontFaceRule CSSContainerRule CSSCounterStyleRule