CSSStyleValue — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSStyleValue

Beschreibung

CSSStyleValue ist die gemeinsame Oberklasse aller Wertobjekte der CSS Typed OM API. Liest man Styles über element.computedStyleMap() oder element.attributeStyleMap, erhält man keine Zeichenketten wie bei getComputedStyle(), sondern Instanzen spezialisierter Unterklassen: CSSNumericValue bzw. CSSUnitValue für Zahlen mit Einheit, CSSKeywordValue für Schlüsselwörter wie auto, CSSTransformValue für Transformationen, CSSImageValue für Bilder und CSSUnparsedValue für Werte mit Custom Properties (var()).

Direkt instanziieren lässt sich CSSStyleValue nicht. Der Konstruktor wirft einen TypeError. Nützlich sind vor allem die beiden statischen Methoden:

CSSStyleValue.parse(property, cssText) wandelt einen CSS-Text für eine bestimmte Eigenschaft in das passende typisierte Objekt um und gibt den ersten Wert zurück.
CSSStyleValue.parseAll(property, cssText) gibt bei Listen-Eigenschaften wie transition oder background-image alle Werte als Array zurück.

Jede Instanz hat außerdem die Methode toString(), die den Wert wieder als gültigen CSS-Text serialisiert. Typed OM lohnt sich vor allem, wenn man häufig Styles per Skript liest oder schreibt, etwa bei Animationen oder in CSS-Houdini-Worklets. Man spart sich das fehleranfällige Zerlegen und Zusammensetzen von Zeichenketten, und der Browser muss weniger parsen.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Parameter von `parse()`/`parseAll()`: Name der CSS-Eigenschaft, für die geparst werden soll, z. B. `"width"`, `"transform"` oder eine Custom Property wie `"--abstand"`.
$cssText Pflicht	string		Parameter von `parse()`/`parseAll()`: der zu parsende CSS-Wert als Zeichenkette, z. B. `"calc(100% - 2rem)"`.

Rückgabewert

Typ

CSSStyleValue | CSSStyleValue[]

Beschreibung

parse() gibt eine Instanz der passenden Unterklasse zurück (z. B. CSSUnitValue, CSSMathSum, CSSKeywordValue). parseAll() gibt ein Array solcher Instanzen zurück. Ist der Text für die Eigenschaft ungültig, wird ein TypeError geworfen.

Beispiele

CSS-Text mit parse() in typisierte Werte umwandeln

const breite = CSSStyleValue.parse('width', 'calc(100% - 2rem)');
console.log(breite.constructor.name);
console.log(breite instanceof CSSStyleValue);
console.log(breite.toString());

const transform = CSSStyleValue.parse('transform', 'translateX(10px) rotate(45deg)');
console.log(transform.constructor.name, transform.length);

CSSMathSum true calc(100% - 2rem) CSSTransformValue 2

Listen-Eigenschaften mit parseAll() zerlegen

const werte = CSSStyleValue.parseAll(
  'transition-duration',
  '200ms, 1s, 0.5s'
);

const inSekunden = werte.map((v) => v.to('s').value);
console.log(inSekunden);

[0.2, 1, 0.5]

Geparsten Wert in attributeStyleMap setzen und Typ prüfen

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

// Wert parsen und als Inline-Style setzen
box.attributeStyleMap.set('margin-top', CSSStyleValue.parse('margin-top', '1.5em'));

// Berechneten Wert auslesen und nach Unterklasse unterscheiden
const wert = box.computedStyleMap().get('margin-top');
if (wert instanceof CSSUnitValue) {
  console.log(`${wert.value} ${wert.unit}`); // Pixel nach Berechnung
} else if (wert instanceof CSSKeywordValue) {
  console.log('Schlüsselwort:', wert.value);
}

24 px

Ungültige Eingaben und Feature-Erkennung abfangen

const sicherParsen = (prop, text) => {
  if (!('CSSStyleValue' in window)) return null; // z. B. Firefox
  try {
    return CSSStyleValue.parse(prop, text);
  } catch (err) {
    console.warn(`Ungültig für ${prop}:`, text, err.name);
    return null;
  }
};

sicherParsen('width', 'blau');

try {
  new CSSStyleValue();
} catch (err) {
  console.log(err.name);
}

Ungültig für width: blau TypeError TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-basierte Browser unterstützen die Typed OM seit Version 66, Safari ab 16.4. Firefox unterstützt sie bisher nicht. Deshalb vorher per Feature-Erkennung prüfen, etwa mit 'CSSStyleValue' in window oder 'attributeStyleMap' in HTMLElement.prototype, und auf element.style bzw. getComputedStyle() zurückfallen.
Keine direkte Instanziierung: new CSSStyleValue() wirft einen TypeError. Einzelne Werte erzeugt man mit Unterklassen-Konstruktoren wie new CSSKeywordValue('auto'), mit Fabrikfunktionen wie CSS.px(10) oder mit parse().
Werte sind an eine Eigenschaft gebunden: Ein Wert, der mit parse() für eine Listen-Eigenschaft erzeugt wurde, lässt sich nicht beliebig bei einer anderen Eigenschaft einsetzen. attributeStyleMap.set() kann dann einen TypeError werfen.
Werte mit var() werden als CSSUnparsedValue geliefert. Sie sind nicht typisiert und lassen sich nicht umrechnen.
parse() gibt bei Listen nur den ersten Wert zurück. Für alle Werte parseAll() verwenden.
Berechnete Werte aus computedStyleMap() sind aufgelöst: Aus em oder % werden oft px. Das entspricht dem Verhalten von getComputedStyle().

Siehe auch

CSSStyleRule CSSImageValue CSSMathValue CSSStyleSheet CSSUnitValue