CSSNumericValue.mul() — Methode · JavaScript-Referenz

Signatur

CSSNumericValue.prototype.mul(...values)

Beschreibung

Die Methode mul() gehört zur CSS Typed Object Model API (Houdini) und multipliziert den aktuellen numerischen CSS-Wert mit allen übergebenen Werten. Das Original bleibt unverändert; das Ergebnis ist immer ein neues Objekt. So lassen sich CSS-Werte typsicher berechnen, ohne Strings wie "calc(10px * 2)" zusammenzubauen und wieder zu parsen.

Der Typ des Ergebnisses hängt von den Operanden ab:

Sind alle Beteiligten CSSUnitValues und hat höchstens einer davon eine echte Einheit (die übrigen sind reine Zahlen), wird das Ergebnis direkt ausgerechnet und als CSSUnitValue zurückgegeben – z. B. CSS.px(10).mul(2) ergibt 20px.
In allen anderen Fällen (z. B. zwei Längen oder ein CSSMathSum als Operand) entsteht ein CSSMathProduct, das als calc(...)-Ausdruck serialisiert wird.

Typische Einsatzfälle sind das Skalieren von Werten aus element.computedStyleMap() oder element.attributeStyleMap, etwa um eine Schriftgröße zu verdoppeln oder eine Breite prozentual anzupassen, sowie Berechnungen in CSS Paint Worklets.

Parameter

Name	Typ	Default	Beschreibung
$...values Pflicht	number \| CSSNumericValue		Ein oder mehrere Faktoren. Reine Zahlen werden intern in `CSS.number(n)` umgewandelt. Numerische CSS-Werte wie `CSS.px(5)` oder `CSS.percent(50)` sind ebenfalls erlaubt.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Ein neuer CSSUnitValue, wenn sich das Produkt direkt ausrechnen lässt, sonst ein CSSMathProduct. Der Ausgangswert wird nicht verändert.

Beispiele

Einfache Multiplikation mit Zahlen

const breite = CSS.px(10);
const doppelt = breite.mul(2);
console.log(doppelt.toString());

// Mehrere Faktoren werden nacheinander multipliziert
console.log(CSS.em(1.5).mul(2, 3).toString());
console.log(CSS.percent(50).mul(0.5).toString());

// Das Original bleibt unverändert
console.log(breite.toString());

20px 9em 25% 10px

Ergebnis als calc()-Ausdruck (CSSMathProduct)

const mix = CSS.px(10).add(CSS.vw(5)); // CSSMathSum
const produkt = mix.mul(2);

console.log(produkt instanceof CSSMathProduct);
console.log(produkt.toString());

true calc((10px + 5vw) * 2)

Schriftgröße eines Elements verdoppeln

const titel = document.querySelector('h1');

// Berechneten Wert typisiert auslesen (z. B. CSSUnitValue 32px)
const schrift = titel.computedStyleMap().get('font-size');

// Verdoppeln und als Inline-Style zurückschreiben
titel.attributeStyleMap.set('font-size', schrift.mul(2));

console.log(titel.attributeStyleMap.get('font-size').toString());

64px

Feature-Erkennung vor der Nutzung

const skaliere = (el, faktor) => {
  if (!('attributeStyleMap' in Element.prototype) || !window.CSS?.px) {
    // Fallback über klassische Strings
    el.style.width = `calc(${getComputedStyle(el).width} * ${faktor})`;
    return;
  }
  const aktuell = el.computedStyleMap().get('width');
  el.attributeStyleMap.set('width', aktuell.mul(faktor));
};

skaliere(document.querySelector('.box'), 1.5);

// Wichtig · Fallstricke

Browser-Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern (ab Chrome/Edge 66) und in Safari ab 16.4. Firefox unterstützt die API nicht. Vor der Nutzung also eine Feature-Erkennung einbauen, z. B. 'CSSNumericValue' in window.
Einheiten multiplizieren sich mit: CSS.px(10).mul(CSS.px(2)) ergibt kein 20px, sondern ein CSSMathProduct mit dem Typ „Länge²“ (calc(10px * 2px)). Weist man so einen Wert einer Eigenschaft wie width zu, wird ein TypeError geworfen, weil der Typ nicht passt.
Keine Strings: Übergeben werden können nur Zahlen oder CSSNumericValue-Objekte. Ein String wie "2px" löst einen TypeError aus; ihn vorher mit CSSNumericValue.parse() umwandeln.
Werte aus computedStyleMap() sind nicht immer CSSUnitValues, bei Schlüsselwörtern wie auto kommt z. B. ein CSSKeywordValue ohne mul() zurück. Den Typ prüfen, bevor du rechnest.
Ein Produkt wird nicht automatisch vereinfacht, wenn relative Einheiten beteiligt sind (vw, %, em mit anderen Einheiten gemischt). Das Endergebnis berechnet erst der Browser beim Layout.

Siehe auch

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