CSSNumericValue.to() — Methode · JavaScript-Referenz

Signatur

CSSNumericValue.prototype.to(unit)

Beschreibung

Die Methode to() gehört zum CSS Typed Object Model (Houdini) und rechnet einen numerischen CSS-Wert in eine andere Einheit um, zum Beispiel px in in, deg in rad oder s in ms. Das Ergebnis ist immer ein neuer CSSUnitValue. Der ursprüngliche Wert bleibt unverändert.

Umrechnen lässt sich nur zwischen Einheiten derselben Kategorie, also Länge, Winkel, Zeit, Frequenz oder Auflösung. Außerdem muss das Verhältnis zwischen den Einheiten fest sein. Absolute Längen wie px, cm, mm, in, pt und pc lassen sich untereinander umrechnen. Relative Einheiten wie em, rem, vw oder % dagegen nicht, weil ihr Wert vom Rendering-Kontext abhängt.

to() funktioniert auch mit zusammengesetzten Werten wie CSSMathSum, etwa aus calc(1in + 48px). Voraussetzung ist, dass sich alle Summanden in die Zieleinheit umrechnen lassen. Die Methode eignet sich gut, um Werte aus element.computedStyleMap() oder CSSNumericValue.parse() auf eine einheitliche Einheit zu bringen, bevor man damit rechnet.

Parameter

Name	Typ	Default	Beschreibung
$unit Pflicht	string		Die Zieleinheit als Zeichenkette, z. B. `'px'`, `'in'`, `'rad'`, `'ms'`, `'Hz'` oder `'dppx'`. Groß- und Kleinschreibung spielt keine Rolle.

Rückgabewert

Typ

CSSUnitValue

Beschreibung

Ein neuer CSSUnitValue mit dem umgerechneten Zahlenwert in value und der Zieleinheit in unit. Ist die Einheit ungültig, wird ein SyntaxError geworfen. Ist die Umrechnung nicht möglich, wird ein TypeError geworfen.

Beispiele

Absolute Längen umrechnen

const breite = CSS.px(96);
const inZoll = breite.to('in');
console.log(inZoll.value, inZoll.unit);

const zentimeter = CSS.cm(2.54).to('px');
console.log(zentimeter.toString());

1 "in" 96px

Winkel und Zeiten für Berechnungen normalisieren

// Math.sin() erwartet Radiant
const winkel = CSS.deg(90).to('rad');
console.log(Math.sin(winkel.value));

// Transition-Dauer in Millisekunden für setTimeout()
const dauer = CSSNumericValue.parse('1.5s').to('ms');
setTimeout(() => console.log(`Fertig nach ${dauer.value} ms`), dauer.value);

1 Fertig nach 1500 ms

calc()-Ausdruck auflösen

const summe = CSSNumericValue.parse('calc(1in + 48px)');
console.log(summe.constructor.name);
console.log(summe.to('px').toString());

CSSMathSum 144px

Nicht umrechenbare Werte abfangen

const sicherUmrechnen = (wert, einheit) => {
  try {
    return wert.to(einheit);
  } catch (err) {
    console.warn(`${wert} → ${einheit}: ${err.name}`);
    return null;
  }
};

sicherUmrechnen(CSS.px(10), 's');      // andere Kategorie
sicherUmrechnen(CSS.em(2), 'px');      // relative Einheit
sicherUmrechnen(CSS.px(10), 'banana'); // unbekannte Einheit

10px → s: TypeError 2em → px: TypeError 10px → banana: SyntaxError

// Wichtig · Fallstricke

Relative Einheiten: em, rem, vw, vh, % usw. lassen sich nicht in px umrechnen, dann kommt ein TypeError. Wer Pixelwerte braucht, liest den berechneten Wert über element.computedStyleMap().get(...) aus. Der liegt meist schon in px vor.
Gemischte Ausdrücke: Auch ein CSSMathSum wie calc(100% - 20px) lässt sich nicht umrechnen, weil einer der Summanden relativ ist.
Fließkomma-Genauigkeit: Umrechnungen wie deg → rad ergeben krumme Zahlen (z. B. 3.141592653589793). Vor dem Vergleichen deshalb runden.
Mehrere Einheiten auf einmal: Mit toSum() lässt sich ein Wert in mehrere Einheiten gleichzeitig aufteilen.
Browser-Unterstützung: CSS Typed OM gibt es in Chromium-Browsern (Chrome/Edge 66+) und in Safari ab 16.4. Firefox unterstützt es nicht. Vorher prüfen, z. B. mit if (window.CSS && CSS.px).

Siehe auch

CSS numeric factory functions CSSNumericValue.add() CSSNumericValue.div() CSSNumericValue.max() CSSNumericValue.min()