CSSValue.cssText — Eigenschaft · JavaScript-Referenz

Signatur

CSSValue.cssText

Beschreibung

Die Eigenschaft cssText der veralteten Schnittstelle CSSValue gibt den Wert als Zeichenkette in CSS-Syntax zurück. Ein CSSValue-Objekt bekam man früher über CSSStyleDeclaration.getPropertyCSSValue(), meist aufgerufen auf dem Ergebnis von window.getComputedStyle(). cssText gibt dann den berechneten Wert der Eigenschaft aus, also etwa "rgb(255, 0, 0)" oder "16px".

Laut Spezifikation (DOM Level 2 Style) ist die Eigenschaft beschreibbar. Bei berechneten Stilen ist das Objekt aber schreibgeschützt: Ein Schreibzugriff löst dort eine DOMException vom Typ NoModificationAllowedError aus.

Die Schnittstelle CSSValue und damit auch cssText gelten als veraltet. Chrome und Firefox (ab Version 62) haben getPropertyCSSValue() entfernt. Für neuen Code nutzt man stattdessen CSSStyleDeclaration.getPropertyValue() für einfache Textwerte oder das CSS Typed Object Model mit Element.computedStyleMap() für typisierte Werte.

Rückgabewert

Typ

string

Beschreibung

Der Wert in CSS-Textform, z. B. "16px", "rgb(0, 0, 255)" oder "none". Bei berechneten Stilen ist das der aufgelöste, absolute Wert.

Beispiele

Berechneten Wert mit Fallback auslesen

const el = document.body;
const style = getComputedStyle(el);

// Veraltete API nur verwenden, wenn der Browser sie noch hat
const fontSize = typeof style.getPropertyCSSValue === 'function'
  ? style.getPropertyCSSValue('font-size').cssText
  : style.getPropertyValue('font-size');

console.log(fontSize);

16px

Schreibzugriff auf einen berechneten Wert abfangen

const style = getComputedStyle(document.documentElement);

if (typeof style.getPropertyCSSValue === 'function') {
  const value = style.getPropertyCSSValue('color');
  try {
    value.cssText = 'red'; // Berechnete Werte sind schreibgeschützt
  } catch (err) {
    console.log(err.name);
  }
} else {
  console.log('CSSValue wird nicht unterstützt');
}

NoModificationAllowedError (bzw. „CSSValue wird nicht unterstützt“ in modernen Browsern)

Moderne Alternative: CSS Typed OM

const box = document.createElement('div');
box.style.width = '12.5rem';
document.body.append(box);

if ('computedStyleMap' in Element.prototype) {
  const width = box.computedStyleMap().get('width');
  console.log(width.toString()); // Textform wie früher cssText
  console.log(width.value, width.unit); // typisierter Zugriff
} else {
  console.log(getComputedStyle(box).getPropertyValue('width'));
}

200px 200 "px"

// Wichtig · Fallstricke

Veraltet: CSSValue, CSSPrimitiveValue, CSSValueList und getPropertyCSSValue() sind in Chrome und Firefox (ab 62) nicht mehr verfügbar und in anderen Browsern höchstens noch teilweise vorhanden. Vor der Nutzung immer prüfen, ob die Funktion existiert.
Bei Kurzschreibweisen wie margin oder border lieferte getPropertyCSSValue() oft null. Ein direkter Zugriff auf .cssText wirft dann einen TypeError.
Bei berechneten Stilen ist cssText nur lesbar. Ein Schreibzugriff löst NoModificationAllowedError aus.
Nicht verwechseln mit CSSStyleDeclaration.cssText (kompletter Deklarationsblock, weiterhin unterstützt) oder CSSRule.cssText (gesamte Regel als Text).
Ersatz: getPropertyValue() für Strings, computedStyleMap() bzw. attributeStyleMap für typisierte Werte. Firefox unterstützt Typed OM erst in neueren Versionen.

Siehe auch

CSSValue CSSValue.cssValueType CSSStyleDeclaration.getPropertyCSSValue() CSSStyleDeclaration.getPropertyValue() CSSStyleDeclaration.cssText Window.getComputedStyle() Element.computedStyleMap()