new CSSUnparsedValue() — Methode · JavaScript-Referenz

Signatur

new CSSUnparsedValue(members)

Beschreibung

Der Konstruktor CSSUnparsedValue() gehört zum CSS Typed Object Model (CSS Typed OM). Er erzeugt ein Objekt für einen CSS-Wert, den der Browser nicht in einen genaueren Typ wie CSSUnitValue oder CSSKeywordValue zerlegen kann. Das betrifft vor allem Werte mit var()-Verweisen und Werte von nicht registrierten Custom Properties (--name).

Ein CSSUnparsedValue besteht aus einer Liste von Segmenten. Jedes Segment ist entweder eine Zeichenkette mit rohem CSS-Text oder ein CSSVariableReferenceValue, also ein Verweis auf eine Custom Property. So kannst du Werte wie calc(var(--basis) * 2) oder 1px solid var(--farbe) strukturiert per Code aufbauen, statt Zeichenketten zusammenzufügen.

Das Objekt verhält sich wie ein Array: Du kannst es mit for...of durchlaufen, mit length die Anzahl der Segmente abfragen und über Indizes (value[0]) lesen und schreiben. Mit toString() erhältst du den fertigen CSS-Text. Das Objekt kannst du direkt an element.attributeStyleMap.set() übergeben.

Parameter

Name	Typ	Default	Beschreibung
$members Pflicht	Iterable<string \| CSSVariableReferenceValue>		Liste der Segmente in ihrer Reihenfolge. Zeichenketten werden als roher CSS-Text übernommen, `CSSVariableReferenceValue`-Objekte als `var()`-Verweise ausgegeben. Andere Werte werden nach WebIDL-Regeln in Zeichenketten umgewandelt.

Rückgabewert

Typ

CSSUnparsedValue

Beschreibung

Ein neues CSSUnparsedValue-Objekt mit den übergebenen Segmenten.

Beispiele

Wert mit var()-Verweis erzeugen

const rahmen = new CSSUnparsedValue([
  '1px solid ',
  new CSSVariableReferenceValue('--akzentfarbe')
]);

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

2 1px solid var(--akzentfarbe)

Custom Property mit Ersatzwert per attributeStyleMap setzen

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

// var(--abstand, 16px) als strukturierter Wert
const abstand = new CSSUnparsedValue([
  new CSSVariableReferenceValue('--abstand', new CSSUnparsedValue([' 16px']))
]);

karte.attributeStyleMap.set('--innenabstand', abstand);
console.log(karte.style.getPropertyValue('--innenabstand'));

var(--abstand, 16px)

Segmente eines gelesenen Werts auswerten

const box = document.querySelector('.box');
box.style.setProperty('--schatten', '0 2px var(--schattenfarbe)');

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

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

true Text: "0 2px " Variable: --schattenfarbe

Segment nachträglich ersetzen

const wert = new CSSUnparsedValue(['calc(', new CSSVariableReferenceValue('--basis'), ' * 2)']);

// Das Segment über den Index ersetzen
wert[1] = new CSSVariableReferenceValue('--grundgroesse');
console.log(String(wert));

calc(var(--grundgroesse) * 2)

// 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 die Verfügbarkeit mit 'CSSUnparsedValue' in window und nutze sonst style.setProperty() mit Zeichenketten.
Keine Syntaxprüfung: Der Konstruktor prüft Zeichenketten-Segmente nicht. Ungültiges CSS fällt erst auf, wenn der Wert angewendet wird, und auch dann meist ohne Fehlermeldung (der Wert ist dann zur Berechnungszeit ungültig).
Leerzeichen: Die Segmente werden ohne Trennzeichen aneinandergehängt. Nötige Leerzeichen gehören daher in die Zeichenketten, etwa '1px solid '.
Registrierte Properties: Custom Properties, die mit CSS.registerProperty() oder @property registriert wurden, liefert attributeStyleMap.get() meist als genaueren Typ zurück, etwa als CSSUnitValue, und nicht als CSSUnparsedValue.
Der Aufruf ohne new oder ohne iterierbares Argument löst einen TypeError aus.

Siehe auch

new CSSKeywordValue() new CSSUnitValue() new CSSPositionValue() new CSSTransformValue() new CSSPerspective()