Signatur
Beschreibung
Mit toSum() bringst du einen beliebigen CSSNumericValue in eine vereinfachte, normalisierte Form. Das kann ein einfacher Wert wie CSS.px(10) sein oder ein verschachtelter Ausdruck aus add(), sub() und mul(). Heraus kommt immer eine CSSMathSum, deren Summanden ausschließlich CSSUnitValue-Objekte sind. Werte mit kompatiblen Einheiten, etwa px, in, cm und pt, werden dabei zusammengefasst.
Gibst du Einheiten an, rechnet der Browser jeden Summanden in die passende davon um. Die Reihenfolge der Summanden im Ergebnis folgt der Reihenfolge deiner Argumente. Bleibt ein Summand übrig, der sich in keine der angegebenen Einheiten umrechnen lässt, gibt es einen TypeError. Ohne Argumente werden kompatible Werte in ihrer kanonischen Einheit zusammengefasst, zum Beispiel px für Längen. Die Summanden werden dann nach Einheitennamen sortiert.
Typische Einsatzfälle:
- Du willst einen
calc()-Ausdruck gezielt in bestimmte Einheiten zerlegen, etwa in „absoluter Anteil inpx+ relativer Anteil in%“. - Du willst Werte in CSS Houdini, zum Beispiel in einem Paint Worklet, oder in Animationslogik vereinfachen, bevor du damit rechnest.
- Du willst prüfen, ob ein Wert überhaupt in einer gewünschten Einheit darstellbar ist, indem du den
TypeErrorabfängst.
Soll ein Wert in genau eine Einheit umgerechnet werden, ist CSSNumericValue.to() meist die direktere Wahl. Diese Methode liefert einen einzelnen CSSUnitValue.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $...units | string | Beliebig viele Einheitennamen, z. B. "px", "em", "percent" oder "number". Sie legen fest, in welche Einheiten umgerechnet wird und in welcher Reihenfolge die Summanden erscheinen. Ohne Argumente wird automatisch zusammengefasst. |
Rückgabewert
CSSMathSum, deren Eigenschaft values (ein CSSNumericArray) nur CSSUnitValue-Objekte enthält. Das Ausgangsobjekt wird nicht verändert.Beispiele
calc()-Ausdruck in px- und %-Anteil zerlegen
// 10px + 1in + 5% → absolute Längen werden zu px zusammengefasst
const wert = CSS.px(10).add(CSS.in(1), CSS.percent(5));
console.log(wert.toString());
const summe = wert.toSum('px', 'percent');
console.log(summe.toString());
// Reihenfolge der Argumente bestimmt die Reihenfolge der Summanden
console.log(wert.toSum('percent', 'px').toString());Einzelne Summanden auslesen
const breite = CSS.px(48).add(CSS.pt(36), CSS.vw(10));
const summe = breite.toSum('in', 'vw');
for (const teil of summe.values) {
console.log(`${teil.value} ${teil.unit}`);
}Prüfen, ob ein Wert in bestimmte Einheiten passt
const passtIn = (numWert, ...einheiten) => {
try {
numWert.toSum(...einheiten);
return true;
} catch (err) {
if (err instanceof TypeError) return false; // nicht umrechenbar
throw err; // z. B. SyntaxError bei ungültiger Einheit
}
};
const wert = CSS.px(20).add(CSS.percent(50));
console.log(passtIn(wert, 'px'));
console.log(passtIn(wert, 'px', 'percent'));Wert aus dem Stylesheet normalisieren
const box = document.querySelector('.box');
box.attributeStyleMap.set('padding-left', CSS.px(8).add(CSS.cm(1), CSS.em(2)));
const padding = box.attributeStyleMap.get('padding-left');
console.log(padding.toSum('px', 'em').toString());