CSS numeric factory functions — Methode · JavaScript-Referenz

Signatur

CSS.px(value) · CSS.em(value) · CSS.percent(value) · CSS.deg(value) · CSS.turn(value) · … (CSS.<einheit>(value))

Beschreibung

Die CSS numeric factory functions gehören zum CSS Typed Object Model (Typed OM). Für jede CSS-Einheit gibt es eine statische Methode am globalen CSS-Namensraum – etwa CSS.px(), CSS.em(), CSS.rem(), CSS.vw(), CSS.percent(), CSS.deg(), CSS.turn(), CSS.s(), CSS.ms(), CSS.fr() oder CSS.number(). Jede davon liefert ein CSSUnitValue-Objekt, dessen value die übergebene Zahl und dessen unit der Methodenname ist (Ausnahmen: CSS.percent() ergibt die Einheit "percent", CSS.number() die Einheit "number").

Einsatzzweck ist das typsichere Setzen und Rechnen mit CSS-Werten, ohne Strings wie `${x}px` zusammenzubauen und wieder zu parsen. Die erzeugten Werte lassen sich direkt über element.attributeStyleMap.set() zuweisen, mit Methoden wie add(), sub(), mul(), div(), min() und max() kombinieren oder mit to() in kompatible Einheiten umrechnen.

Verfügbare Gruppen sind unter anderem: absolute Längen (px, cm, mm, in, pt, pc, Q), relative Längen (em, rem, ex, ch, ic, lh, rlh), Viewport- und Container-Einheiten (vw, vh, vmin, vmax, svh, dvh, cqw …), Winkel (deg, rad, grad, turn), Zeiten (s, ms), Frequenzen (Hz, kHz), Auflösungen (dpi, dpcm, dppx) sowie fr.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number		Der Zahlenwert des zu erzeugenden `CSSUnitValue`. Ganzzahlen, Dezimalzahlen und negative Werte sind erlaubt.

Rückgabewert

Typ

CSSUnitValue

Beschreibung

Ein neues CSSUnitValue-Objekt mit value = übergebene Zahl und unit = Name der Einheit (z. B. "px", "turn", "percent").

Beispiele

Werte erzeugen und inspizieren

const breite = CSS.px(240);
const drehung = CSS.turn(0.25);
const anteil = CSS.percent(50);

console.log(breite.value, breite.unit);
console.log(drehung.toString());
console.log(anteil.toString());

240 'px' 0.25turn 50%

Stil typsicher per attributeStyleMap setzen

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

box.attributeStyleMap.set('width', CSS.px(300));
box.attributeStyleMap.set('opacity', CSS.number(0.8));
box.attributeStyleMap.set('transition-duration', CSS.ms(250));

console.log(box.attributeStyleMap.get('width').toString());
console.log(box.getAttribute('style'));

300px width: 300px; opacity: 0.8; transition-duration: 250ms;

Rechnen und Einheiten umrechnen

// Winkel umrechnen
const winkel = CSS.turn(0.5).to('deg');
console.log(winkel.toString());

// Gemischte Einheiten ergeben einen calc()-Ausdruck
const summe = CSS.percent(100).sub(CSS.px(20));
console.log(summe.toString());

// Gleiche Einheiten werden direkt verrechnet
console.log(CSS.px(10).add(CSS.px(5)).toString());
console.log(CSS.s(1.5).to('ms').value);

180deg calc(100% - 20px) 15px 1500

Animation mit Feature-Erkennung

const kreisel = document.querySelector('.spinner');
let grad = 0;

const tick = () => {
  grad = (grad + 2) % 360;
  if (window.CSS && 'deg' in CSS && kreisel.attributeStyleMap) {
    kreisel.attributeStyleMap.set(
      'transform',
      new CSSTransformValue([new CSSRotate(CSS.deg(grad))])
    );
  } else {
    // Fallback für Browser ohne Typed OM (z. B. Firefox)
    kreisel.style.transform = `rotate(${grad}deg)`;
  }
  requestAnimationFrame(tick);
};
requestAnimationFrame(tick);

// Wichtig · Fallstricke

Browser-Kompatibilität: Teil der CSS Typed OM – in Chromium-Browsern seit Version 66, in Safari seit 16.4. Firefox unterstützt die Typed OM derzeit nicht; immer per Feature-Erkennung ('px' in CSS) prüfen und einen String-Fallback über element.style vorsehen.
Die Prozent-Methode heißt CSS.percent(), nicht CSS['%'](); einheitenlose Zahlen erzeugt man mit CSS.number().
to() funktioniert nur zwischen kompatiblen, absolut umrechenbaren Einheiten (z. B. px ↔ cm, deg ↔ turn). CSS.em(2).to('px') wirft einen TypeError, weil dafür der Kontext (Schriftgröße) fehlt.
Rechnen mit unterschiedlichen Einheiten liefert kein CSSUnitValue, sondern ein CSSMathSum/CSSMathProduct (serialisiert als calc()).
Ein nicht endlicher Wert wie NaN oder Infinity wird zwar angenommen, führt aber zu calc()-Ausdrücken bzw. ungültigen Stilen – Eingaben vorher validieren.
Die Methoden sind statisch; new CSS.px(5) ist nicht vorgesehen. Wer eine Einheit dynamisch braucht, nutzt new CSSUnitValue(5, 'px').

Siehe auch

StylePropertyMap.prototype.set() CSS CSS.registerProperty() CSS.supports() CSS.escape()