CSSStyleValue.parse() — Methode · JavaScript-Referenz

Signatur

CSSStyleValue.parse(property, cssText)

Beschreibung

CSSStyleValue.parse() ist eine statische Methode des CSS Typed Object Model (Typed OM). Du übergibst einen Eigenschaftsnamen und einen CSS-Text. Der Browser parst den Text nach der Grammatik genau dieser Eigenschaft und gibt ein passendes Objekt zurück, zum Beispiel CSSUnitValue, CSSMathSum, CSSKeywordValue, CSSTransformValue oder bei eigenen Eigenschaften (Custom Properties) CSSUnparsedValue.

Das ist nützlich, wenn du CSS-Werte als Zeichenkette hast, etwa aus einer Konfiguration, einer Benutzereingabe oder einem Stylesheet, und sie strukturiert weiterverarbeiten willst. Du musst dann keine Zeichenketten selbst zerlegen oder mit regulären Ausdrücken arbeiten. Das Ergebnis kannst du direkt mit element.attributeStyleMap.set() zuweisen, untersuchen (zum Beispiel value und unit) oder mit Methoden wie to() und add() umrechnen.

Bei Eigenschaften, die eine Liste von Werten erlauben (etwa background-image oder transition), liefert parse() nur den ersten Wert. Alle Werte bekommst du mit CSSStyleValue.parseAll(). Ist der Text für die Eigenschaft ungültig, wirft die Methode einen TypeError.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft, nach deren Grammatik geparst wird, z. B. `'width'`, `'transform'` oder eine Custom Property wie `'--abstand'`. Kurzschreibweisen wie `'margin'` sind ebenfalls erlaubt.
$cssText Pflicht	string		Der CSS-Wert als Zeichenkette, z. B. `'calc(100% - 2rem)'` oder `'translate(10px, 20px) rotate(45deg)'`.

Rückgabewert

Typ

CSSStyleValue

Beschreibung

Ein Objekt einer Unterklasse von CSSStyleValue, zum Beispiel CSSUnitValue, CSSMathSum, CSSKeywordValue, CSSTransformValue, CSSImageValue oder CSSUnparsedValue. Bei Listenwerten ist es nur der erste Wert. Kann der Browser einen Typ noch nicht genauer abbilden, bekommst du ein einfaches CSSStyleValue.

Beispiele

Transform-Wert parsen und untersuchen

const transform = CSSStyleValue.parse(
  'transform',
  'translate3d(10px, 20px, 0) scale(0.5)'
);

console.log(transform.constructor.name);
console.log(transform.length);
for (const teil of transform) {
  console.log(teil.constructor.name);
}

// Direkt auf ein Element anwenden
document.body.attributeStyleMap.set('transform', transform);

CSSTransformValue 2 CSSTranslate CSSScale

calc()-Ausdruck und einfache Längen

const breite = CSSStyleValue.parse('width', 'calc(100% - 20px)');
console.log(breite.constructor.name, breite.operator);
console.log(breite.toString());

const rand = CSSStyleValue.parse('margin-top', '2.5rem');
console.log(rand.value, rand.unit);

CSSMathSum sum calc(100% - 20px) 2.5 rem

Listenwerte: parse() vs. parseAll()

const text = 'url("a.png"), url("b.png")';

const erster = CSSStyleValue.parse('background-image', text);
console.log(erster.toString());

const alle = CSSStyleValue.parseAll('background-image', text);
console.log(alle.length);

url("a.png") 2

Benutzereingabe sicher prüfen

const parseLaenge = (eingabe) => {
  if (!('CSSStyleValue' in window)) return null; // Feature-Erkennung
  try {
    return CSSStyleValue.parse('width', eingabe);
  } catch (err) {
    console.warn(`Ungültiger Wert "${eingabe}":`, err.name);
    return null;
  }
};

console.log(String(parseLaenge('300px')));
parseLaenge('dreihundert');

300px Ungültiger Wert "dreihundert": TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die Methode seit Version 66, Safari seit 16.4. Firefox unterstützt das CSS Typed OM bisher nicht. Prüfe deshalb vorher mit 'CSSStyleValue' in window und sieh eine Lösung über element.style als Ersatz vor.
Ungültige Werte: Passt der Text nicht zur Grammatik der Eigenschaft oder ist die Eigenschaft unbekannt, wirft die Methode einen TypeError. Verwende deshalb try…catch, vor allem bei Benutzereingaben.
Nur der erste Wert: Bei Eigenschaften mit Listenwerten gehen alle weiteren Einträge verloren. Nutze dafür CSSStyleValue.parseAll().
Custom Properties: Nicht registrierte Custom Properties (--name) ergeben immer ein CSSUnparsedValue, auch wenn der Wert wie eine Länge aussieht. Mit CSS.registerProperty() registrierte Custom Properties werden typisiert.
Statischer Aufruf: Rufe die Methode über die Klasse auf, also CSSStyleValue.parse(). Auf einer Instanz gibt es sie nicht. Einen Konstruktor new CSSStyleValue() gibt es ebenfalls nicht; er wirft einen Fehler.
Für einfache numerische Werte sind die Hilfsfunktionen CSS.px(), CSS.percent() usw. schneller und klarer als das Parsen von Zeichenketten.

Siehe auch

CSSStyleValue CSSStyleValue.parseAll() CSSUnitValue CSSTransformValue CSSUnparsedValue StylePropertyMap.set()