CSSStyleDeclaration.getPropertyCSSValue() — Methode · JavaScript-Referenz

Signatur

CSSStyleDeclaration.prototype.getPropertyCSSValue(property)

Beschreibung

getPropertyCSSValue() stammt aus dem alten CSS-Objektmodell von DOM Level 2 Style. Anders als getPropertyValue() gibt die Methode keinen String zurück, sondern ein CSSValue-Objekt. Meist ist das ein CSSPrimitiveValue oder eine CSSValueList. Über Methoden wie getFloatValue() oder getRGBColorValue() ließen sich damit typisierte Werte auslesen, ohne Strings selbst zerlegen zu müssen.

Die Idee hat sich nicht durchgesetzt. Das Interface CSSValue wurde aus der Spezifikation gestrichen, und die meisten Browser haben die Methode entfernt. Für neuen Code sollten Sie sie nicht mehr verwenden.

Für heutige Projekte gibt es zwei Ersatzwege:

getPropertyValue() gibt den Wert als String zurück und funktioniert in allen Browsern.
Die CSS Typed OM mit element.computedStyleMap() bzw. element.attributeStyleMap liefert typisierte Objekte wie CSSUnitValue. Sie ist der moderne Nachfolger dieses Konzepts.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft in CSS-Schreibweise mit Bindestrichen, z. B. `"margin-top"` statt `"marginTop"`.

Rückgabewert

Typ

CSSValue | null

Beschreibung

Ein CSSValue-Objekt (meist CSSPrimitiveValue oder CSSValueList). Bei Kurzschreibweisen wie margin oder border und bei nicht gesetzten bzw. unbekannten Eigenschaften kommt null zurück.

Beispiele

Historische Nutzung (nur in alten Browsern)

const box = document.createElement('div');
box.style.marginTop = '12px';
document.body.append(box);

const style = getComputedStyle(box);

if (typeof style.getPropertyCSSValue === 'function') {
  const value = style.getPropertyCSSValue('margin-top');
  // CSSPrimitiveValue.CSS_PX === 5
  console.log(value.getFloatValue(CSSPrimitiveValue.CSS_PX));
} else {
  console.log('getPropertyCSSValue wird nicht unterstützt');
}

12 (alte Browser) getPropertyCSSValue wird nicht unterstützt (aktuelle Browser)

Robuste Alternative mit getPropertyValue()

const box = document.createElement('div');
box.style.width = '250px';
document.body.append(box);

const raw = getComputedStyle(box).getPropertyValue('width');
const width = parseFloat(raw);

console.log(raw, width + 50);

250px 300

Moderner Nachfolger: CSS Typed OM

const box = document.createElement('div');
box.style.paddingLeft = '1.5rem';
document.body.append(box);

const readPadding = (el) => {
  if ('computedStyleMap' in el) {
    const v = el.computedStyleMap().get('padding-left');
    return `${v.value}${v.unit}`; // CSSUnitValue
  }
  // Fallback für Browser ohne Typed OM
  return getComputedStyle(el).getPropertyValue('padding-left');
};

console.log(readPadding(box));

24px (bei 16px Basisschriftgröße)

// Wichtig · Fallstricke

Veraltet: Die Methode ist nicht mehr Teil der aktuellen CSSOM-Spezifikation. Chrome hat sie um Version 40 entfernt, Firefox mit Version 62. Nur WebKit-basierte Browser haben sie teilweise noch. Prüfen Sie daher immer mit typeof style.getPropertyCSSValue === 'function', ob sie vorhanden ist.
Kurzschreibweisen: Für margin, background, font usw. kommt null zurück. Fragen Sie stattdessen die einzelnen Eigenschaften ab, etwa margin-top.
Schreibweise: Der Eigenschaftsname muss mit Bindestrichen geschrieben werden. Mit \"backgroundColor\" bekommen Sie null.
Auch die zugehörigen Interfaces CSSValue, CSSPrimitiveValue und CSSValueList fehlen in modernen Browsern. Code, der sie verwendet, bricht mit einem ReferenceError ab.
Als Ersatz dient getPropertyValue(), das überall funktioniert, oder die CSS Typed OM mit computedStyleMap() (Chromium, Safari ab 16.4; in Firefox noch nicht vorhanden).

Siehe auch

CSSStyleDeclaration.getPropertyValue() CSSStyleDeclaration.setProperty() CSSStyleDeclaration Window.getComputedStyle() Element.computedStyleMap() CSSUnitValue