new CSSVariableReferenceValue() — Methode · JavaScript-Referenz

Signatur

new CSSVariableReferenceValue(variable, fallback)

Beschreibung

Der Konstruktor CSSVariableReferenceValue() gehört zum CSS Typed Object Model (Houdini). Er erzeugt ein Objekt für einen var()-Ausdruck, also einen Verweis auf eine benutzerdefinierte CSS-Eigenschaft wie --main-color. Optional lässt sich ein Ersatzwert angeben.

Ein CSSVariableReferenceValue wird fast nie für sich allein benutzt. Man packt ihn als Element in ein CSSUnparsedValue. Dieses Objekt kann man dann mit element.attributeStyleMap.set() einer CSS-Eigenschaft zuweisen. So baut man var()-Ausdrücke strukturiert und typsicher auf und muss keine Zeichenketten zusammensetzen.

Das Objekt hat zwei Eigenschaften: variable (der Name der benutzerdefinierten Eigenschaft, veränderbar) und fallback (ein CSSUnparsedValue oder null, nur lesbar).

Parameter

Name	Typ	Default	Beschreibung
$variable Pflicht	string		Name der benutzerdefinierten Eigenschaft. Er muss mit zwei Bindestrichen beginnen, z. B. `'--main-color'`. Sonst wird ein `TypeError` ausgelöst.
$fallback	CSSUnparsedValue \| null	null	Optionaler Ersatzwert. Er entspricht dem zweiten Argument von `var()` und wird verwendet, wenn die Variable nicht definiert ist.

Rückgabewert

Typ

CSSVariableReferenceValue

Beschreibung

Ein neues CSSVariableReferenceValue-Objekt mit den Eigenschaften variable und fallback.

Beispiele

Einfachen Variablen-Verweis erzeugen

const ref = new CSSVariableReferenceValue('--main-color');

console.log(ref.variable);
console.log(ref.fallback);

// Name nachträglich ändern (variable ist veränderbar)
ref.variable = '--accent-color';
console.log(ref.variable);

--main-color null --accent-color

var() mit Ersatzwert per Typed OM setzen

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

// Ersatzwert als CSSUnparsedValue
const fallback = new CSSUnparsedValue(['#336699']);
const ref = new CSSVariableReferenceValue('--akzent', fallback);

// Verweis in einen CSSUnparsedValue einbetten und zuweisen
const value = new CSSUnparsedValue([ref]);
box.attributeStyleMap.set('background-color', value);

console.log(value.toString());
console.log(box.style.backgroundColor);

var(--akzent,#336699) var(--akzent,#336699)

Feature-Erkennung und ungültige Namen abfangen

const createVarRef = (name, fallbackText) => {
  if (typeof CSSVariableReferenceValue === 'undefined') {
    // Rückfall ohne Typed OM: reine Zeichenkette
    return fallbackText ? `var(${name}, ${fallbackText})` : `var(${name})`;
  }
  try {
    const fb = fallbackText ? new CSSUnparsedValue([fallbackText]) : null;
    return new CSSUnparsedValue([new CSSVariableReferenceValue(name, fb)]);
  } catch (err) {
    console.error(`${err.name}: Ungültiger Variablenname "${name}"`);
    return null;
  }
};

createVarRef('abstand'); // fehlendes "--"
console.log(String(createVarRef('--abstand', '8px')));

TypeError: Ungültiger Variablenname "abstand" var(--abstand,8px)

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome/Edge ab 66) und in Safari ab 16.4. Firefox unterstützt es nicht. Prüfe die Verfügbarkeit deshalb vorher, z. B. mit 'CSSVariableReferenceValue' in window, und sieh einen Rückfall über Zeichenketten und style.setProperty() vor.
Beginnt variable nicht mit --, wird ein TypeError ausgelöst. Das gilt beim Konstruktor und auch beim späteren Setzen der Eigenschaft variable.
fallback muss ein CSSUnparsedValue oder null sein. Eine einfache Zeichenkette wie 'red' wird nicht akzeptiert. Wickle sie also in new CSSUnparsedValue(['red']) ein.
Ein CSSVariableReferenceValue kann nicht direkt an attributeStyleMap.set() übergeben werden. Er muss immer in einem CSSUnparsedValue stecken.
Bei der Serialisierung kann Leerraum anders aussehen als erwartet, z. B. var(--a,red) statt var(--a, red). Vergleiche Zeichenketten deshalb nicht exakt.
Der Konstruktor ist nur im Fenster-Kontext und in Worklets verfügbar. Nur in einigen Umgebungen ist er zusätzlich in Web Workern vorhanden.

Siehe auch

CSSVariableReferenceValue CSSUnparsedValue CSSStyleValue StylePropertyMap.prototype.set() Element.prototype.computedStyleMap() CSSStyleDeclaration.prototype.setProperty()