CSSUnitValue.unit — Eigenschaft · JavaScript-Referenz

Signatur

CSSUnitValue.unit

Beschreibung

Die Eigenschaft unit gehört zur Schnittstelle CSSUnitValue aus dem CSS Typed Object Model (Houdini). Ein CSSUnitValue steht für einen einfachen CSS-Wert aus einer Zahl und einer Einheit, etwa 12px, 1.5em, 45deg oder 50%. Die Zahl steht in value, die Einheit in unit.

Der Rückgabewert ist ein String mit dem Einheitenkürzel, wie man es aus CSS kennt, z. B. "px", "rem", "vh", "deg", "s" oder "ms". Es gibt zwei Sonderfälle: Prozentwerte liefern "percent" und nicht "%". Einheitenlose Zahlen wie bei line-height: 1.4 oder opacity: 0.5 liefern "number".

Man braucht unit vor allem dann, wenn man Werte aus element.computedStyleMap() oder element.attributeStyleMap liest und sie abhängig von der Einheit verarbeiten will. So muss man keine Strings wie "12px" mehr mit regulären Ausdrücken zerlegen. Die Eigenschaft ist schreibgeschützt. Um die Einheit zu wechseln, verwendet man CSSNumericValue.prototype.to() oder erzeugt einen neuen Wert.

Rückgabewert

Typ

string

Beschreibung

Das Einheitenkürzel des Werts, z. B. "px", "em" oder "deg". Für Prozentwerte "percent", für einheitenlose Zahlen "number".

Beispiele

Einheit direkt erzeugter Werte abfragen

const breite = new CSSUnitValue(120, 'px');
const anteil = CSS.percent(50);
const faktor = CSS.number(1.5);
const winkel = CSS.deg(90);

console.log(breite.unit);
console.log(anteil.unit);
console.log(faktor.unit);
console.log(winkel.unit);

px percent number deg

Berechneten Stil auslesen und nach Einheit auswerten

const box = document.querySelector('.box');
const padding = box.computedStyleMap().get('padding-left');

// Computed-Werte von Längen werden in px aufgelöst
if (padding instanceof CSSUnitValue && padding.unit === 'px') {
  console.log(`Innenabstand: ${padding.value} Pixel`);
} else {
  console.log('Kein einfacher Einheitenwert:', padding.toString());
}

Innenabstand: 16 Pixel

Inline-Stil einheitenabhängig verändern

const el = document.querySelector('#banner');
el.attributeStyleMap.set('font-size', CSS.rem(1.25));

const size = el.attributeStyleMap.get('font-size');

// Nur Werte in rem vergrößern
if (size.unit === 'rem') {
  el.attributeStyleMap.set('font-size', CSS.rem(size.value * 1.2));
}

console.log(el.attributeStyleMap.get('font-size').toString());

1.5rem

Einheit umrechnen statt unit zu überschreiben

const dauer = CSS.ms(1500);
console.log(dauer.unit); // "ms"

// unit ist schreibgeschützt – stattdessen umrechnen:
const inSekunden = dauer.to('s');
console.log(inSekunden.unit, inSekunden.value);

ms s 1.5

// Wichtig · Fallstricke

Prozent ist nicht „%“: Prozentwerte liefern "percent", einheitenlose Zahlen liefern "number". Vergleiche wie unit === '%' sind deshalb nie wahr.
Nicht jeder Wert ist ein CSSUnitValue: computedStyleMap().get() kann auch CSSKeywordValue (z. B. auto), CSSMathSum (z. B. calc(100% - 10px)) oder CSSStyleValue zurückgeben. Dort gibt es keine Eigenschaft unit (undefined). Vorher mit instanceof CSSUnitValue prüfen.
Schreibgeschützt: Eine Zuweisung an unit hat keine Wirkung und wirft im Strict Mode einen TypeError. Zum Umrechnen to() verwenden.
Ungültige Einheiten: new CSSUnitValue(1, 'foo') wirft einen TypeError.
Berechnete Werte: Im Computed Style werden relative Längen wie em oder rem in der Regel in px umgerechnet. attributeStyleMap liefert dagegen die angegebene Einheit.
Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern seit Version 66 und in Safari seit 16.4. Firefox unterstützt es bislang nicht. Die Unterstützung vorher prüfen, z. B. mit 'CSSUnitValue' in window, und sonst auf getComputedStyle() ausweichen.

Siehe auch

CSSUnitValue.value CSSPositionValue.x CSSPositionValue.y CSSRotate.angle CSSRotate.x