CSSUnitValue.value — Eigenschaft · JavaScript-Referenz

Signatur

CSSUnitValue.value

Beschreibung

Die Eigenschaft value gehört zum CSS Typed Object Model (Houdini). Ein CSSUnitValue besteht aus zwei Teilen: einer Zahl (value) und einer Einheit (unit). Beim Wert 1.5em ist value also 1.5 und unit ist "em".

Die Eigenschaft lässt sich lesen und schreiben. Mit ihr ändern Sie CSS-Werte rechnerisch, ohne Zeichenketten wie "120px" zerlegen und wieder zusammensetzen zu müssen. Das macht Animationen, Layout-Berechnungen und Werte aus element.computedStyleMap() bzw. element.attributeStyleMap einfacher und weniger fehleranfällig.

Wichtig: Wenn Sie value ändern, wirkt sich das nicht automatisch auf das Element aus. Das Objekt ist eine unabhängige Kopie. Sie müssen es erst mit attributeStyleMap.set() wieder zuweisen, damit die Änderung greift.

Rückgabewert

Typ

number

Beschreibung

Eine Gleitkommazahl mit der Anzahl der Einheiten. Beim Schreiben wird der Wert nach JavaScript-Regeln in eine Zahl (double) umgewandelt.

Beispiele

Wert und Einheit auslesen

const breite = new CSSUnitValue(120, 'px');
console.log(breite.value); // Zahl
console.log(breite.unit);  // Einheit
console.log(breite.toString());

// Alternativ über die Fabrikfunktion
const abstand = CSS.em(1.5);
console.log(abstand.value);

120 px 120px 1.5

Berechnete Schriftgröße eines Elements lesen

const ueberschrift = document.querySelector('h1');
const groesse = ueberschrift.computedStyleMap().get('font-size');

if (groesse instanceof CSSUnitValue) {
  console.log(`Schriftgröße: ${groesse.value} ${groesse.unit}`);
}

Schriftgröße: 32 px

Wert ändern und zurückschreiben

const box = document.querySelector('.box');
box.attributeStyleMap.set('width', CSS.px(200));

const breite = box.attributeStyleMap.get('width');
breite.value += 50; // ändert nur das Objekt

// Erst durch set() wird die Änderung am Element sichtbar
box.attributeStyleMap.set('width', breite);
console.log(box.style.width);

250px

Einfache Animation ohne String-Zerlegung

const element = document.querySelector('.ball');
const links = CSS.px(0);

const schritt = () => {
  links.value += 2;
  element.attributeStyleMap.set('left', links);
  if (links.value < 300) requestAnimationFrame(schritt);
};

requestAnimationFrame(schritt);

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern (Chrome und Edge ab Version 66) und in Safari ab 16.4. Firefox unterstützt es derzeit nicht. Prüfen Sie die Unterstützung z. B. mit if ('CSSUnitValue' in window).
Wenn Sie value setzen, ändert sich das Element nicht von selbst. Weisen Sie das Objekt anschließend mit attributeStyleMap.set() neu zu.
Nicht jeder Wert aus computedStyleMap().get() ist ein CSSUnitValue. Ausdrücke wie calc(100% - 10px) liefern einen CSSMathSum, und Schlüsselwörter wie auto liefern einen CSSKeywordValue. Beide haben keine Eigenschaft value vom Typ Zahl. Prüfen Sie daher vorher mit instanceof.
Werte ohne Einheit haben die Einheit "number", Prozentwerte die Einheit "percent".
Wenn Sie einen nicht-numerischen Wert zuweisen, wird er umgewandelt. NaN ist technisch möglich, ergibt aber kein gültiges CSS.

Siehe auch

CSSMathClamp.value CSSUnitValue.unit CSSKeywordValue.value CSSMathSum.values DataCue.value