CSSNumericValue.add() — Methode · JavaScript-Referenz

Signatur

CSSNumericValue.prototype.add(...values)

Beschreibung

Die Methode add() gehört zum CSS Typed Object Model. Sie addiert CSS-Werte typsicher, ohne dass du Zeichenketten wie "10px" selbst zerlegen und wieder zusammensetzen musst. Der ursprüngliche Wert bleibt unverändert, denn add() gibt immer ein neues Objekt zurück.

Das Ergebnis hängt von den Einheiten ab:

Haben alle Summanden dieselbe Einheit (z. B. nur px), wird direkt gerechnet. Du bekommst einen CSSUnitValue zurück, z. B. 15px.
Sind die Einheiten verschieden, aber verträglich (z. B. px und % bei Längen), entsteht ein CSSMathSum. Dieser wird als calc(…) ausgegeben.
Passen die Typen nicht zusammen (z. B. Länge + Zeit), wirft die Methode einen TypeError.

Typische Einsatzfälle sind Animationen und Layout-Berechnungen in JavaScript, bei denen du Werte aus element.attributeStyleMap oder element.computedStyleMap() liest, veränderst und wieder zurückschreibst. Das spart die Umwandlung in Zeichenketten und das anschließende Parsen, geht schneller und macht weniger Fehler.

Parameter

Name	Typ	Default	Beschreibung
$values Pflicht	...(number\|CSSNumericValue)		Ein oder mehrere Werte, die addiert werden. Einfache Zahlen werden wie `CSS.number(n)` behandelt, sind also einheitenlos. Zeichenketten wie `"5px"` werden nicht akzeptiert. Wandle sie vorher mit `CSSNumericValue.parse()` um.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Einen neuen CSSNumericValue: einen CSSUnitValue, wenn sich die Summe direkt ausrechnen lässt, sonst einen CSSMathSum. Wirft einen TypeError, wenn die Typen nicht verträglich sind.

Beispiele

Werte mit gleicher Einheit addieren

const a = CSS.px(10);
const summe = a.add(CSS.px(5), CSS.px(2.5));

console.log(summe instanceof CSSUnitValue);
console.log(summe.value, summe.unit);
console.log(summe.toString());
console.log(a.toString()); // Original bleibt unverändert

true 17.5 "px" 17.5px 10px

Gemischte Einheiten ergeben calc()

const breite = CSS.percent(50).add(CSS.px(20));

console.log(breite.constructor.name);
console.log(breite.toString());

document.body.attributeStyleMap.set('width', breite);

CSSMathSum calc(50% + 20px)

Breite eines Elements bei jedem Klick vergrößern

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

box.addEventListener('click', () => {
  // Aktuellen Inline-Wert lesen, sonst bei 100px beginnen
  const aktuell = box.attributeStyleMap.get('width') ?? CSS.px(100);
  box.attributeStyleMap.set('width', aktuell.add(CSS.px(10)));
  console.log(box.attributeStyleMap.get('width').toString());
});

110px (nach dem ersten Klick)

Unverträgliche Typen abfangen

try {
  CSS.px(10).add(CSS.s(1)); // Länge + Zeit
} catch (err) {
  console.log(err.name);
}

// Einheitenlose Zahlen funktionieren untereinander
console.log(CSS.number(2).add(3).toString());

TypeError 5

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es bisher nicht. Prüfe vorher mit if ('CSSNumericValue' in window) und nutze sonst einen Ersatzweg über element.style.
Einheitenlose Zahlen und Längen: CSS.px(10).add(5) wirft einen TypeError, weil 5 als einheitenlose Zahl gilt und nicht als Länge.
Keine automatische Umrechnung: Nur absolut umrechenbare Einheiten werden zu einem einzigen Wert zusammengefasst. Bei relativen Einheiten wie %, em oder vw bleibt ein CSSMathSum übrig. Soll ein fester Wert herauskommen, rufe to() auf (nur bei umrechenbaren Einheiten) oder lies den berechneten Wert über computedStyleMap().
Negative Summanden: Für Subtraktion ist sub() besser lesbar. Negative CSSUnitValues werden in calc() als + -20px ausgegeben.
Das Ergebnis ist unveränderlich (immutable). Wenn du es nicht speicherst oder zurückschreibst, geht es verloren.

Siehe auch

CSSNumericValue.div() CSSNumericValue.max() CSSNumericValue.min() CSSNumericValue.mul() CSSNumericValue.sub()