CSSNumericValue.sub() — Methode · JavaScript-Referenz

Signatur

CSSNumericValue.prototype.sub(...values)

Beschreibung

sub() gehört zum CSS Typed Object Model (Houdini). Die Methode zieht beliebig viele Werte vom aktuellen CSSNumericValue ab. Das Ausgangsobjekt bleibt dabei unverändert, du bekommst immer ein neues Objekt zurück. So kannst du mit CSS-Werten typsicher rechnen, ohne Strings wie "100px" zusammenbauen oder zerlegen zu müssen.

Haben alle Operanden dieselbe Einheit (zum Beispiel alle px), rechnet der Browser das Ergebnis direkt aus und gibt ein CSSUnitValue zurück, etwa CSS.px(100).sub(CSS.px(30)) → 70px. Sind die Einheiten zwar verträglich, aber verschieden (zum Beispiel px und % oder px und em), entsteht ein CSSMathSum. Die abgezogenen Werte stecken darin als CSSMathNegate. In CSS geschrieben ergibt das einen calc()-Ausdruck wie calc(100% - 20px).

Typische Einsätze sind Layout-Berechnungen in JavaScript, etwa „Breite minus Rand“, Animationen mit attributeStyleMap und Paint- oder Layout-Worklets. Reine Zahlen werden automatisch in CSS.number() umgewandelt. Deshalb passen sie nur zu Werten, die selbst keine Einheit haben.

Parameter

Name	Typ	Default	Beschreibung
$values Pflicht	number \| CSSNumericValue (beliebig viele)		Ein oder mehrere Werte, die nacheinander abgezogen werden. Eine `number` wird intern zu `CSS.number(n)`. Alle Werte müssen zum Typ des Ausgangswerts passen, zum Beispiel Länge mit Länge oder Prozent.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Ein neuer CSSNumericValue. Bei gleicher Einheit ist das ein CSSUnitValue mit dem ausgerechneten Wert. Bei gemischten Einheiten ist es ein CSSMathSum, der als calc(...) ausgegeben wird.

Beispiele

Gleiche Einheiten: Ergebnis wird direkt ausgerechnet

const breite = CSS.px(300);
const ergebnis = breite.sub(CSS.px(40), CSS.px(10));

console.log(ergebnis.constructor.name); // CSSUnitValue
console.log(ergebnis.value, ergebnis.unit);
console.log(ergebnis.toString());

CSSUnitValue 250 "px" 250px

Gemischte Einheiten ergeben einen calc()-Ausdruck

const volleBreite = CSS.percent(100);
const seitenleiste = CSS.px(240);

const inhalt = volleBreite.sub(seitenleiste);
console.log(inhalt.constructor.name);
console.log(inhalt.toString());

// Direkt als Stil setzen
document.querySelector('main').attributeStyleMap.set('width', inhalt);

CSSMathSum calc(100% - 240px)

Berechneten Stil auslesen und verkleinern

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

// computedStyleMap() liefert typisierte Werte, z. B. CSSUnitValue in px
const aktuell = box.computedStyleMap().get('width');
const neu = aktuell.sub(CSS.px(20));

box.attributeStyleMap.set('width', neu);
console.log(`${aktuell} -> ${neu}`);

200px -> 180px

Unverträgliche Typen abfangen

try {
  // Länge minus einheitenlose Zahl ist nicht erlaubt
  CSS.px(10).sub(2);
} catch (err) {
  console.log(err.name);
}

// Mit reinen Zahlen klappt es:
console.log(CSS.number(10).sub(3).toString());

TypeError 7

// Wichtig · Fallstricke

TypeError bei unverträglichen Typen: Länge minus Zahl, Länge minus Winkel oder Zeit minus Länge werfen einen TypeError. Zahlenwerte ohne CSS.px() und ähnliche Hilfsfunktionen gelten als einheitenlos.
Keine Strings: sub('5px') funktioniert nicht. Wandle Zeichenketten vorher mit CSSNumericValue.parse('5px') um.
Kein Zusammenfassen gemischter Einheiten: px und em oder % werden nicht verrechnet, weil der Kontext fehlt. Das Ergebnis bleibt dann ein CSSMathSum. Einen Zahlenwert liest du daraus nicht über .value aus.
Unveränderlich: Der ursprüngliche Wert ändert sich nicht. Du musst den Rückgabewert verwenden.
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 die Unterstützung vorher, etwa mit if (window.CSS && CSS.px), und sieh bei Bedarf einen Weg über Strings oder calc() vor.

Siehe auch

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