Signatur
Beschreibung
CSSUnitValue gehört zur CSS Typed Object Model API (Houdini) und steht für einen einfachen numerischen Wert mit einer Einheit, etwa 10px, 2em, 45deg, 300ms oder 50%. Einheitslose Zahlen wie bei opacity: 0.5 haben die Einheit "number". Das Interface erbt von CSSNumericValue und damit von CSSStyleValue.
Ein großer Vorteil gegenüber String-basiertem CSS: Mit value und unit bekommt man Zahl und Einheit getrennt. Man muss also nicht mehr mit parseFloat() und String-Verkettung wie el.style.width = w + 'px' arbeiten. Solche Werte bekommt man über element.attributeStyleMap, element.computedStyleMap(), über new CSSUnitValue(value, unit) oder über die Fabrikfunktionen im CSS-Namensraum, z. B. CSS.px(10), CSS.percent(50) oder CSS.number(1).
Von CSSNumericValue übernommen werden Rechenmethoden wie add(), sub(), mul(), div(), min(), max(), equals() sowie die Umrechnung mit to(unit). Bei gemischten Einheiten, z. B. px + %, ist das Ergebnis kein CSSUnitValue, sondern ein CSSMathSum, also ein calc()-Ausdruck.
Eigenschaften:
value(number, lesbar und schreibbar): der Zahlenwert.unit(string, nur lesbar): die Einheit, z. B."px","percent","number".
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value Pflicht | number | Zahlenwert des neuen CSSUnitValue (Konstruktor new CSSUnitValue(value, unit)). Muss endlich sein, sonst wird ein TypeError geworfen. |
|
| $unit Pflicht | string | Einheit als String, z. B. "px", "em", "deg", "ms", "percent" (nicht "%"!) oder "number" für einheitslose Werte. Bei einer ungültigen Einheit wird ein TypeError geworfen. |
Rückgabewert
CSSUnitValue-Objekt mit den Eigenschaften value und unit.Beispiele
Instanziierung per Konstruktor und CSS-Fabrikfunktion
const a = new CSSUnitValue(12, 'px');
const b = CSS.percent(50);
const c = CSS.number(0.5);
console.log(a.value, a.unit); // Zahl und Einheit getrennt
console.log(b.toString());
console.log(c.unit);Breite eines Elements ohne String-Parsing vergrößern
const box = document.querySelector('.box');
box.attributeStyleMap.set('width', CSS.px(200));
const width = box.attributeStyleMap.get('width'); // CSSUnitValue
width.value += 50; // value ist beschreibbar
box.attributeStyleMap.set('width', width);
console.log(box.style.width);Einheiten umrechnen und rechnen
const angle = CSS.deg(180);
console.log(angle.to('rad').value.toFixed(4));
const dauer = CSS.s(1.5).to('ms');
console.log(dauer.toString());
// Gemischte Einheiten ergeben einen calc()-Ausdruck
const summe = CSS.px(10).add(CSS.percent(5));
console.log(summe.constructor.name, summe.toString());Berechneten Wert auslesen
const el = document.body;
const styles = el.computedStyleMap();
const fontSize = styles.get('font-size');
if (fontSize instanceof CSSUnitValue) {
console.log(`Schriftgröße: ${fontSize.value} ${fontSize.unit}`);
}// Wichtig · Fallstricke
- Browser-Unterstützung: Chromium-Browser (Chrome, Edge, Opera) ab Version 66 und Safari ab 16.4. Firefox unterstützt die CSS Typed OM bislang nicht. Vorher die Unterstützung prüfen, z. B. mit
if ('CSSUnitValue' in window), und sonst aufelement.stylebzw.getComputedStyle()zurückfallen. - Prozent heißt als Einheit
\"percent\", nicht\"%\".new CSSUnitValue(50, '%')wirft einenTypeError. - Rechenmethoden wie
add()odermul()geben nur dann wieder einCSSUnitValuezurück, wenn die Einheiten zusammenpassen. Sonst entsteht einCSSMathValue, das keinevalue-Eigenschaft hat. Vor dem Zugriff also mitinstanceofprüfen. to()rechnet nur zwischen absoluten, kompatiblen Einheiten um (z. B.px↔cm,deg↔rad). Relative Einheiten wieemoder%lassen sich nicht nachpxumrechnen. Dabei wird einTypeErrorgeworfen.- Wenn man
valueändert, passiert am Element noch nichts. Den Wert muss man danach selbst mitattributeStyleMap.set()zurückschreiben. computedStyleMap()liefert je nach Eigenschaft auch andere Typen, z. B.CSSKeywordValuefürauto.