CSSVariableReferenceValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSVariableReferenceValue

Beschreibung

CSSVariableReferenceValue gehört zur CSS Typed Object Model API (Houdini) und steht für einen einzelnen var()-Ausdruck. Das Objekt enthält den Namen der referenzierten Custom Property (z. B. --main-color) und optional einen Ersatzwert (Fallback), der gilt, wenn die Variable nicht definiert ist.

Einzeln begegnet man diesen Objekten selten. Sie stecken fast immer als Bestandteil in einem CSSUnparsedValue. Liest man über element.attributeStyleMap.get() oder element.computedStyleMap() einen Wert aus, der var() enthält, kommt ein CSSUnparsedValue zurück. Dessen Einträge sind Zeichenketten oder CSSVariableReferenceValue-Instanzen.

Wichtige Bestandteile:

new CSSVariableReferenceValue(variable, fallback) – Konstruktor
variable – Name der Custom Property als string, lesbar und schreibbar
fallback – nur lesbar; ein CSSUnparsedValue oder null

Das Interface ist nützlich, wenn man Stilwerte mit Variablen typsicher im Code erzeugen, untersuchen oder umschreiben will, ohne Zeichenketten selbst zu zerlegen. Typische Einsätze sind Theming-Werkzeuge, Design-Token-Editoren oder Houdini-Worklets.

Parameter

Name	Typ	Default	Beschreibung
$variable Pflicht	string		Name der Custom Property, mit führendem `--`, z. B. `'--main-color'`. Ohne dieses Präfix wird ein `TypeError` ausgelöst.
$fallback	CSSUnparsedValue \| null	null	Optionaler Ersatzwert, entspricht dem zweiten Argument von `var()`. Er muss ein `CSSUnparsedValue` sein, eine einfache Zeichenkette wird nicht angenommen.

Rückgabewert

Typ

CSSVariableReferenceValue

Beschreibung

Der Konstruktor liefert eine neue Instanz mit den Eigenschaften variable und fallback.

Beispiele

Variablenverweis erzeugen und als Stil setzen

const box = document.querySelector('.box');

// entspricht var(--main-color)
const ref = new CSSVariableReferenceValue('--main-color');
box.attributeStyleMap.set('color', new CSSUnparsedValue([ref]));

console.log(ref.variable);
console.log(ref.fallback);
console.log(box.style.color);

--main-color null var(--main-color)

Verweis mit Ersatzwert

const card = document.querySelector('.card');

const gap = new CSSVariableReferenceValue(
  '--card-gap',
  new CSSUnparsedValue(['16px']) // Ersatzwert, falls --card-gap fehlt
);

card.attributeStyleMap.set('padding', new CSSUnparsedValue([gap]));
console.log(card.attributeStyleMap.get('padding').toString());

var(--card-gap,16px)

var()-Verweise in bestehenden Stilen finden und umbenennen

const el = document.querySelector('.button');
el.style.setProperty('background', 'var(--btn-bg, steelblue)');

const value = el.attributeStyleMap.get('background');

if (value instanceof CSSUnparsedValue) {
  for (const part of value) {
    if (part instanceof CSSVariableReferenceValue) {
      console.log('Variable:', part.variable, '| Fallback:', part.fallback?.toString());
      // Token-Migration: alten Namen durch neuen ersetzen
      if (part.variable === '--btn-bg') part.variable = '--color-primary';
    }
  }
  el.attributeStyleMap.set('background', value);
}

console.log(el.style.background);

Variable: --btn-bg | Fallback: steelblue var(--color-primary, steelblue)

Feature-Erkennung vor der Nutzung

const supportsTypedOM = 'CSSVariableReferenceValue' in window &&
  'attributeStyleMap' in HTMLElement.prototype;

const setVar = (el, prop, name) => {
  if (supportsTypedOM) {
    el.attributeStyleMap.set(prop, new CSSUnparsedValue([
      new CSSVariableReferenceValue(name)
    ]));
  } else {
    el.style.setProperty(prop, `var(${name})`); // Rückfall über Zeichenketten
  }
};

setVar(document.body, 'color', '--text-color');
console.log(document.body.style.color);

var(--text-color)

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es nicht. Prüfen Sie deshalb vorher mit Feature-Erkennung und sehen Sie einen Rückfall über style.setProperty() vor.
Der Variablenname muss mit -- beginnen. Das gilt beim Konstruktor und beim Setzen von variable, sonst kommt ein TypeError.
fallback ist nur lesbar. Um den Ersatzwert zu ändern, erzeugen Sie eine neue Instanz. Er muss außerdem ein CSSUnparsedValue sein, keine Zeichenkette.
Ausgelesene Ersatzwerte können Leerzeichen am Anfang enthalten, z. B. " steelblue", weil sie unverändert übernommen werden. Bei Bedarf mit trim() bereinigen.
Das Objekt beschreibt nur den Verweis und nicht den aufgelösten Wert. Den tatsächlichen Wert der Variable liefert getComputedStyle(el).getPropertyValue('--name').
Eine Änderung am Objekt wirkt sich erst auf das Element aus, wenn der Wert erneut mit attributeStyleMap.set() gesetzt wird.

Siehe auch

CSSUnparsedValue CSSStyleValue StylePropertyMap Element.computedStyleMap() CSSStyleDeclaration.setProperty()