CSSNumericValue.parse() — Methode · JavaScript-Referenz

Signatur

CSSNumericValue.parse(cssText)

Beschreibung

Die statische Methode CSSNumericValue.parse() gehört zum CSS Typed Object Model (Houdini). Sie nimmt einen einzelnen numerischen CSS-Wert als String entgegen und liefert ein Objekt zurück, mit dem man rechnen kann, statt Strings mühsam mit regulären Ausdrücken zu zerlegen. Einfache Werte wie "10px", "50%" oder "1.5" werden zu einem CSSUnitValue mit den Eigenschaften value und unit.

Mathematische Ausdrücke wie calc(), min(), max() oder clamp() werden zu Unterklassen von CSSMathValue (etwa CSSMathSum, CSSMathProduct, CSSMathMin) aufgelöst. Auf allen Ergebnissen stehen die Methoden von CSSNumericValue zur Verfügung, zum Beispiel add(), mul(), to(), equals() und type().

Einsetzen lässt sich die Methode überall dort, wo CSS-Werte als Text vorliegen: bei Benutzereingaben, Konfigurationsdaten, Werten aus getPropertyValue() oder beim Aufbau von Werten für element.attributeStyleMap.set(). Einheitenlose Zahlen bekommen die Einheit "number", Prozentwerte die Einheit "percent".

Parameter

Name	Typ	Default	Beschreibung
$cssText Pflicht	string		Ein einzelner numerischer CSS-Wert, z. B. `"42px"`, `"75%"`, `"3"` oder ein mathematischer Ausdruck wie `"calc(100% - 2rem)"`.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Ein CSSUnitValue bei einfachen Werten oder eine Unterklasse von CSSMathValue (z. B. CSSMathSum) bei mathematischen Ausdrücken. Lässt sich der String nicht als numerischer Wert lesen, wird ein SyntaxError (DOMException) ausgelöst.

Beispiele

Einfachen Längenwert zerlegen

const breite = CSSNumericValue.parse('42.5px');

console.log(breite instanceof CSSUnitValue); // true
console.log(breite.value, breite.unit);

const anteil = CSSNumericValue.parse('75%');
console.log(anteil.value, anteil.unit);

const faktor = CSSNumericValue.parse('1.5');
console.log(faktor.unit);

true 42.5 "px" 75 "percent" "number"

calc()-Ausdruck einlesen und untersuchen

const ausdruck = CSSNumericValue.parse('calc(1px + 2em)');

console.log(ausdruck.constructor.name);  // CSSMathSum
console.log(ausdruck.operator);           // "sum"
console.log([...ausdruck.values].map(v => `${v.value}${v.unit}`));
console.log(ausdruck.toString());

CSSMathSum sum ["1px", "2em"] calc(1px + 2em)

Benutzereingabe prüfen, umrechnen und setzen

const setzeRand = (element, eingabe) => {
  try {
    const wert = CSSNumericValue.parse(eingabe);
    // Absolute Längen in Pixel umrechnen
    const px = wert.to('px');
    element.attributeStyleMap.set('margin-left', px);
    console.log(`Gesetzt: ${px.toString()}`);
  } catch (fehler) {
    console.warn(`Ungültiger Wert "${eingabe}": ${fehler.name}`);
  }
};

const box = document.querySelector('.box');
setzeRand(box, '1in');   // 1 Zoll = 96px
setzeRand(box, 'auto');  // kein numerischer Wert

Gesetzt: 96px Ungültiger Wert "auto": SyntaxError

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM wird von Chromium-Browsern (Chrome, Edge, Opera ab Version 66) und Safari ab 16.4 unterstützt, von Firefox bisher nicht. Vor der Verwendung prüfen, z. B. mit if (window.CSSNumericValue?.parse) { … }.
Nur numerische Werte: Schlüsselwörter wie auto oder inherit, Farben, mehrere Werte ("1px 2px") und var()-Referenzen lösen einen SyntaxError aus. Für allgemeine Eigenschaftswerte ist CSSStyleValue.parse(property, cssText) gedacht.
Umrechnung mit to(): Das klappt nur zwischen kompatiblen absoluten Einheiten (px, in, cm, pt …). Relative Einheiten wie em, % oder vw lassen sich ohne Kontext nicht umrechnen, dann wird ein TypeError ausgelöst.
Einheiten werden in Kleinbuchstaben ausgegeben ("10PX" → unit: "px"). Prozentwerte haben die Einheit "percent", nicht "%".
Die Methode ist statisch: Sie wird direkt auf CSSNumericValue aufgerufen, nicht auf einer Instanz.

Siehe auch

CSSNumericValue.add() CSSNumericValue.max() CSSNumericValue.type() CSSNumericValue.div() CSSNumericValue.equals()