Signatur
Beschreibung
CSSNumericValue ist die gemeinsame Basis aller numerischen Werte der CSS Typed Object Model API (Houdini). Mit ihr rechnet man mit CSS-Werten als echten Objekten und nicht mit Zeichenketten wie "10px". Konkrete Unterklassen sind CSSUnitValue (ein Wert mit einer Einheit, z. B. 10px) und CSSMathValue mit den Varianten CSSMathSum, CSSMathProduct, CSSMathNegate, CSSMathInvert, CSSMathMin, CSSMathMax und CSSMathClamp. Sie stehen für calc()-, min()-, max()- und clamp()-Ausdrücke.
Die Schnittstelle stellt folgende Methoden bereit:
add(...values),sub(...values),mul(...values),div(...values): Grundrechenarten. Als Argumente sindCSSNumericValue-Objekte oder einfache Zahlen erlaubt.min(...values),max(...values): geben das Minimum bzw. Maximum zurück, bei gemischten Einheiten alsCSSMathMin/CSSMathMax.equals(...values): prüft, ob die Werte strukturell gleich sind.to(unit): rechnet in eine andere, kompatible Einheit um (z. B.in→px).toSum(...units): zerlegt den Wert in eineCSSMathSumaus den angegebenen Einheiten.type(): liefert einCSSNumericType-Objekt, das den Typ beschreibt (z. B.{ length: 1 }).- statisch
CSSNumericValue.parse(cssText): wandelt eine CSS-Zeichenkette in einCSSNumericValueum.
Sinnvoll ist das vor allem zusammen mit element.attributeStyleMap und element.computedStyleMap(). Werte lassen sich damit typsicher lesen, verrechnen und zurückschreiben, ohne Zeichenketten zu zerlegen oder zusammenzubauen. Bei gleichen Einheiten wird direkt gerechnet, das Ergebnis ist ein CSSUnitValue. Bei unterschiedlichen, aber kompatiblen Einheiten (z. B. px und %) entsteht ein CSSMathValue, den der Browser später wie calc() auswertet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $cssText Pflicht | string | Nur für die statische Methode CSSNumericValue.parse(): ein numerischer CSS-Wert als Zeichenkette, z. B. "10px" oder "calc(50% - 2em)". |
Rückgabewert
add, sub, mul, div, min, max, to) und parse() geben ein neues CSSNumericValue zurück, also einen CSSUnitValue oder einen CSSMathValue. Das Ausgangsobjekt bleibt unverändert. equals() liefert boolean, type() ein CSSNumericType-Objekt und toSum() eine CSSMathSum.Beispiele
Werte erzeugen und mit gleichen Einheiten rechnen
// CSSNumericValue ist abstrakt: Instanzen entstehen über CSS.px() & Co. oder parse()
const a = CSSNumericValue.parse('10px');
const b = CSS.px(5);
const summe = a.add(b);
console.log(summe instanceof CSSUnitValue, summe.value, summe.unit);
console.log(a.mul(3).toString());
console.log(CSS.px(10).equals(CSS.px(10)));
console.log(CSS.px(10).type());Gemischte Einheiten ergeben calc()-Ausdrücke
const breite = CSS.percent(100).sub(CSS.px(40));
console.log(breite.constructor.name, breite.toString());
const kleinste = CSS.px(300).min(CSS.vw(50));
console.log(kleinste.toString());
// Einheitenumrechnung zwischen kompatiblen absoluten Einheiten
console.log(CSS.in(1).to('px').toString());
console.log(CSS.s(1.5).to('ms').toString());Praxis: Element-Breite typsicher verdoppeln
const box = document.querySelector('.box');
box.attributeStyleMap.set('width', CSS.px(120));
// Wert lesen, verrechnen und zurückschreiben, ganz ohne String-Parsing
const aktuell = box.attributeStyleMap.get('width');
const neu = aktuell.mul(2).add(CSS.rem(1));
box.attributeStyleMap.set('width', neu);
console.log(box.style.width);Fehlerbehandlung bei inkompatiblen Typen
try {
// Länge + Zeit ist nicht definiert
CSS.px(10).add(CSS.s(1));
} catch (err) {
console.log(err.name);
}
try {
CSSNumericValue.parse('rot');
} catch (err) {
console.log(err.name);
}