CSSVariableReferenceValue.variable — Eigenschaft · JavaScript-Referenz

Signatur

CSSVariableReferenceValue.variable

Beschreibung

Die Eigenschaft variable gehört zur Schnittstelle CSSVariableReferenceValue aus dem CSS Typed Object Model. Ein CSSVariableReferenceValue-Objekt steht für einen Ausdruck der Form var(--name, fallback). Über variable erhältst du den Namen der referenzierten benutzerdefinierten Eigenschaft (Custom Property), also den Teil --name, als Zeichenkette.

Solche Objekte begegnen dir meist als Bestandteile eines CSSUnparsedValue. Das passiert, wenn du über element.attributeStyleMap oder CSSStyleRule.styleMap einen angegebenen Wert ausliest, der var() enthält. Mit variable kannst du herausfinden, von welchen Custom Properties ein Wert abhängt, etwa für Design-Token-Analysen, Theming-Werkzeuge oder Debugging.

Die Eigenschaft ist les- und schreibbar. Beim Setzen muss der neue Wert ein gültiger Custom-Property-Name sein, also mit zwei Bindestrichen (--) beginnen. Sonst wirft der Browser einen TypeError. Wenn du den Namen änderst, wird das Element nicht automatisch neu gestylt. Dafür musst du den geänderten Wert erst wieder mit attributeStyleMap.set() zuweisen.

Rückgabewert

Typ

string

Beschreibung

Der Name der referenzierten benutzerdefinierten Eigenschaft mit führendem --, z. B. "--brand-color".

Beispiele

Verweis erzeugen und Namen auslesen

// Entspricht var(--brand-color, #0055ff)
const fallback = new CSSUnparsedValue([' #0055ff']);
const ref = new CSSVariableReferenceValue('--brand-color', fallback);

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

--brand-color #0055ff

Custom Properties in einem Inline-Stil finden

const box = document.querySelector('.box');
box.style.setProperty('border', '2px solid var(--accent, red)');

const value = box.attributeStyleMap.get('border');

if (value instanceof CSSUnparsedValue) {
  const vars = [...value]
    .filter((part) => part instanceof CSSVariableReferenceValue)
    .map((part) => part.variable);
  console.log('Abhängig von:', vars);
}

Abhängig von: ["--accent"]

Verweis auf eine andere Variable umstellen

const btn = document.querySelector('button');
btn.style.setProperty('color', 'var(--primary)');

const unparsed = btn.attributeStyleMap.get('color');
const ref = [...unparsed].find((p) => p instanceof CSSVariableReferenceValue);

ref.variable = '--secondary';            // Namen ändern
btn.attributeStyleMap.set('color', unparsed); // erneut zuweisen

console.log(btn.style.color);

try {
  ref.variable = 'secondary'; // ohne -- → ungültig
} catch (err) {
  console.log(err.name);
}

var(--secondary) TypeError

// Wichtig · Fallstricke

Browserunterstützung: Das CSS Typed OM gibt es in Chromium-basierten Browsern (ab Version 66) und in Safari (ab 16.4). Firefox unterstützt es nicht. Prüfe die Verfügbarkeit vorher, z. B. mit if ('CSSVariableReferenceValue' in window), und sieh bei Bedarf einen Rückfall auf getPropertyValue() vor.
Nur angegebene Werte: element.computedStyleMap() liefert berechnete Werte, in denen var() schon aufgelöst ist. Dort tauchen keine CSSVariableReferenceValue-Objekte auf. Verwende stattdessen attributeStyleMap oder CSSStyleRule.styleMap.
Beim Setzen muss der Name mit -- beginnen, sonst wird ein TypeError geworfen. Die Klammern von var() gehören nicht zum Namen.
Wenn du variable änderst, passiert das nur am Objekt. Damit die Änderung sichtbar wird, musst du den umgebenden CSSUnparsedValue erneut per set() zuweisen.
Ob die Custom Property überhaupt definiert ist, prüft variable nicht. Der Name wird nur als Zeichenkette gespeichert.

Siehe auch

CSSVariableReferenceValue.fallback CSSKeywordValue.value CSSTransformValue.is2D CSSFontFeatureValuesMap.size CSSTransformValue.length