new CSSUnitValue() — Methode · JavaScript-Referenz

Signatur

new CSSUnitValue(value, unit)

Beschreibung

Der Konstruktor CSSUnitValue() gehört zum CSS Typed Object Model (Houdini). Er erzeugt ein typisiertes Objekt aus einer Zahl und einer Einheit, zum Beispiel new CSSUnitValue(10, 'px'). Dadurch musst du CSS-Werte nicht mehr als Zeichenketten zusammensetzen und wieder zerlegen: value und unit sind getrennt lesbar und beschreibbar.

Solche Objekte kannst du direkt an element.attributeStyleMap.set() übergeben oder mit den mathematischen Methoden von CSSNumericValue verrechnen, etwa add(), mul() oder to(). So lassen sich Werte umrechnen (z. B. in → px) oder mit Werten in anderen Einheiten zu einem CSSMathSum verbinden, was in CSS einem calc() entspricht.

Oft sind die Kurzfabriken wie CSS.px(10), CSS.percent(50) oder CSS.number(1) bequemer. Sie liefern ebenfalls CSSUnitValue-Instanzen. Den Konstruktor brauchst du vor allem, wenn die Einheit erst zur Laufzeit feststeht, also als Zeichenkette in einer Variablen vorliegt.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number		Der Zahlenwert, z. B. `10` oder `-2.5`. Nicht-numerische Werte führen zu einem `TypeError`.
$unit Pflicht	string		Die Einheit als Zeichenkette, z. B. `'px'`, `'em'`, `'deg'` oder `'s'`. Für Prozent schreibst du `'percent'`, für einheitenlose Zahlen `'number'`. Groß- und Kleinschreibung spielt keine Rolle. Bei einer unbekannten Einheit wird ein `TypeError` ausgelöst.

Beispiele

Wert erzeugen und auslesen

const breite = new CSSUnitValue(120, 'px');

console.log(breite.value);      // 120
console.log(breite.unit);       // 'px'
console.log(breite.toString()); // '120px'

// Prozent und einheitenlose Zahl
const anteil = new CSSUnitValue(50, 'percent');
const faktor = new CSSUnitValue(1.5, 'number');
console.log(anteil.toString(), faktor.toString());

120 px 120px 50% 1.5

Typisiert in attributeStyleMap schreiben

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

// Einheit kommt z. B. aus einer Konfiguration
const config = { abstand: 16, einheit: 'px' };

box.attributeStyleMap.set('padding', new CSSUnitValue(config.abstand, config.einheit));
box.attributeStyleMap.set('opacity', new CSSUnitValue(0.8, 'number'));

console.log(box.style.padding); // '16px'
console.log(box.attributeStyleMap.get('opacity').value); // 0.8

16px 0.8

Rechnen und Einheiten umrechnen

const zoll = new CSSUnitValue(1, 'in');

// Umrechnung in eine kompatible Einheit
console.log(zoll.to('px').toString()); // '96px'

// Verdoppeln, Wert direkt ändern
const rand = new CSSUnitValue(4, 'px');
console.log(rand.mul(2).toString()); // '8px'
rand.value += 1;
console.log(rand.toString()); // '5px'

// Verschiedene Einheiten ergeben einen calc()-Ausdruck
const summe = new CSSUnitValue(100, 'percent').sub(CSS.px(20));
console.log(summe.toString()); // 'calc(100% - 20px)'

96px 8px 5px calc(100% - 20px)

Fehlerbehandlung bei ungültiger Einheit

const erzeugeWert = (wert, einheit) => {
  try {
    return new CSSUnitValue(wert, einheit);
  } catch (err) {
    console.warn(`Ungültig: ${wert}${einheit} (${err.name})`);
    return null;
  }
};

erzeugeWert(10, 'pixel');
erzeugeWert(10, '%'); // '%' ist ungültig, richtig wäre 'percent'

Ungültig: 10pixel (TypeError) Ungültig: 10% (TypeError)

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (Chrome, Edge, Opera) ab Version 66 und Safari ab 16.4. Firefox unterstützt das CSS Typed OM bisher nicht. Prüfe die Verfügbarkeit mit if ('CSSUnitValue' in window) und nutze sonst element.style mit Zeichenketten.
Für Prozent gibst du 'percent' an, nicht '%'. Einheitenlose Zahlen brauchen 'number'. toString() gibt trotzdem 50% aus.
Der Konstruktor prüft nicht, ob der Wert zur Zieleigenschaft passt. attributeStyleMap.set('width', new CSSUnitValue(5, 'deg')) löst erst beim Setzen einen TypeError aus.
to() funktioniert nur zwischen kompatiblen absoluten Einheiten (z. B. px, in, cm). Relative Einheiten wie em oder % lassen sich ohne Layout-Kontext nicht umrechnen.
Nur in sicheren Kontexten muss man nicht denken: Die API steht auch über HTTP bereit, in Workern jedoch nur eingeschränkt (z. B. in Paint Worklets).

Siehe auch

StylePropertyMap.prototype.set() new CSSPositionValue() new CSSRotate() new CSSScale() new CSSUnparsedValue()