CSSUnparsedValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSUnparsedValue extends CSSStyleValue

Beschreibung

CSSUnparsedValue gehört zur CSS Typed Object Model API (Houdini). Ein solcher Wert entsteht, wenn der Browser einen Eigenschaftswert nicht in einen genaueren Typ wie CSSUnitValue oder CSSKeywordValue umwandeln kann. Das passiert in zwei typischen Fällen: bei nicht registrierten benutzerdefinierten Eigenschaften (--meine-farbe) und bei Werten, die var()-Referenzen enthalten. Solche Werte stehen erst fest, wenn der Browser die Variablen aufgelöst hat.

Ein CSSUnparsedValue verhält sich wie eine Liste. Jedes Element ist entweder ein string (reiner Tokentext) oder ein CSSVariableReferenceValue (eine var()-Referenz mit optionalem Ersatzwert). Du kannst die Liste mit for...of, forEach(), entries(), keys() und values() durchlaufen. Über einen Index wie value[0] kannst du Elemente lesen und auch ersetzen. length gibt die Anzahl der Elemente an.

Die Schnittstelle ist nützlich, wenn du CSS-Variablen per JavaScript untersuchen oder bauen willst, ohne Strings selbst zu zerlegen. Mit toString() erhältst du wieder gültigen CSS-Text, den du etwa an attributeStyleMap.set() übergeben kannst.

Parameter

Name	Typ	Default	Beschreibung
$members Pflicht	Array<string \| CSSVariableReferenceValue>		Nur beim Konstruktor `new CSSUnparsedValue(members)`: eine Liste aus Textstücken und `CSSVariableReferenceValue`-Objekten, die zusammen den Wert bilden.

Rückgabewert

Typ

CSSUnparsedValue

Beschreibung

Der Konstruktor liefert eine neue Instanz. length liefert eine number, der Indexzugriff einen string oder einen CSSVariableReferenceValue, und toString() liefert den serialisierten CSS-Text.

Beispiele

Instanz erzeugen und serialisieren

// Wert „1px solid var(--rahmenfarbe, black)“ zusammensetzen
const fallback = new CSSUnparsedValue([' black']);
const farbe = new CSSVariableReferenceValue('--rahmenfarbe', fallback);
const rahmen = new CSSUnparsedValue(['1px solid ', farbe]);

console.log(rahmen.length);
console.log(rahmen.toString());

// Als Inline-Style setzen
document.body.attributeStyleMap.set('border', rahmen);

2 1px solid var(--rahmenfarbe, black)

var()-Referenzen eines Inline-Styles untersuchen

const box = document.createElement('div');
box.style.setProperty('margin', 'var(--abstand) auto');

const wert = box.attributeStyleMap.get('margin');
console.log(wert instanceof CSSUnparsedValue);

for (const teil of wert) {
  if (teil instanceof CSSVariableReferenceValue) {
    console.log('Variable:', teil.variable);
  } else {
    console.log('Text:', JSON.stringify(teil));
  }
}

true Variable: --abstand Text: " auto"

Custom Property auslesen und ein Element ersetzen

const el = document.documentElement;
el.style.setProperty('--akzent', 'var(--primaer)');

const akzent = el.attributeStyleMap.get('--akzent');

// Die Referenz über den Index auf eine andere Variable umbiegen
akzent[0] = new CSSVariableReferenceValue('--sekundaer');
el.attributeStyleMap.set('--akzent', akzent);

console.log(el.style.getPropertyValue('--akzent'));

var(--sekundaer)

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome, Edge, Opera) ab Version 66 und in Safari ab 16.4. Firefox unterstützt es nicht. Prüfe deshalb vorher, ob die API vorhanden ist, z. B. mit if ('CSSUnparsedValue' in window), und nutze sonst style.getPropertyValue().
Leerzeichen gehören zum Wert: Textstücke enthalten Leerzeichen exakt so, wie sie im CSS stehen, z. B. ' auto'. Füge Stücke deshalb nicht blind zusammen. Verwende besser toString().
Registrierte Eigenschaften: Eine Custom Property, die mit CSS.registerProperty() oder @property einen Typ (syntax) bekommen hat, liefert im berechneten Stil (computedStyleMap()) einen passenden Typ wie CSSUnitValue statt CSSUnparsedValue.
Der Konstruktor wirft einen TypeError, wenn members kein iterierbares Objekt aus Strings und CSSVariableReferenceValue-Objekten ist.
Wie genau berechnete Werte unregistrierter Custom Properties aussehen, etwa ob Leerzeichen am Rand entfernt werden, kann sich zwischen Browserversionen unterscheiden.

Siehe auch

CSSImageValue CSSUnitValue CSSKeywordValue CSSMathValue CSSNumericValue