CSSStyleDeclaration.getPropertyValue() — Methode · JavaScript-Referenz

Signatur

CSSStyleDeclaration.prototype.getPropertyValue(property)

Beschreibung

getPropertyValue() liest den Wert einer CSS-Eigenschaft aus einem CSSStyleDeclaration-Objekt. So ein Objekt bekommt man zum Beispiel über element.style (Inline-Stile), über getComputedStyle(element) (berechnete Stile) oder über CSSStyleRule.style (Regeln in einem Stylesheet).

Der Eigenschaftsname wird in CSS-Schreibweise übergeben, also mit Bindestrichen, z. B. background-color statt backgroundColor. Das ist der große Vorteil gegenüber dem Punkt-Zugriff: Nur so kommt man an CSS-Custom-Properties (--hauptfarbe) heran, denn die tauchen nicht als JavaScript-Eigenschaften auf.

Was genau zurückkommt, hängt von der Quelle ab. Bei element.style steht nur drin, was inline im style-Attribut gesetzt wurde. Bei getComputedStyle() bekommt man den aufgelösten Wert, den der Browser tatsächlich verwendet, meist in absoluten Einheiten (z. B. px, rgb()). Ist die Eigenschaft nicht gesetzt oder unbekannt, kommt ein leerer String "" zurück, nicht null.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft in CSS-Schreibweise (kebab-case), z. B. `margin-top` oder `--abstand`. Bei normalen Eigenschaften spielt Groß-/Kleinschreibung keine Rolle, bei Custom-Properties schon.

Rückgabewert

Typ

string

Beschreibung

Der Wert der Eigenschaft als String, z. B. "16px" oder "rgb(255, 0, 0)". Ist die Eigenschaft nicht gesetzt oder unbekannt, kommt ein leerer String "" zurück.

Beispiele

Inline-Stil lesen

const box = document.createElement('div');
box.style.setProperty('background-color', 'tomato');
box.style.setProperty('padding', '8px 16px');

console.log(box.style.getPropertyValue('background-color'));
console.log(box.style.getPropertyValue('padding'));
console.log(box.style.getPropertyValue('margin')); // nicht gesetzt

tomato 8px 16px "" (leerer String)

CSS-Variable aus :root auslesen

// CSS: :root { --hauptfarbe: #0066cc; --abstand: 1.5rem; }
const rootStyles = getComputedStyle(document.documentElement);

const farbe = rootStyles.getPropertyValue('--hauptfarbe').trim();
const abstand = rootStyles.getPropertyValue('--abstand').trim();

console.log(`Farbe: ${farbe}, Abstand: ${abstand}`);

Farbe: #0066cc, Abstand: 1.5rem

Berechnete Breite als Zahl verwenden

const header = document.querySelector('header');
const style = getComputedStyle(header);

// getComputedStyle liefert aufgelöste Werte, meist in px
const hoehe = parseFloat(style.getPropertyValue('height'));
const paddingTop = parseFloat(style.getPropertyValue('padding-top'));

document.body.style.setProperty('--header-hoehe', `${hoehe + paddingTop}px`);
console.log('Header-Höhe:', hoehe);

Header-Höhe: 64

Wert aus einer Stylesheet-Regel lesen

const sheet = new CSSStyleSheet();
sheet.replaceSync('.btn { border-radius: 4px; color: white; }');

const regel = sheet.cssRules[0];
console.log(regel.style.getPropertyValue('border-radius'));
console.log(regel.style.getPropertyPriority('color') || 'keine Priorität');

4px keine Priorität

// Wichtig · Fallstricke

Bindestrich-Schreibweise: getPropertyValue('backgroundColor') gibt "" zurück. Richtig ist 'background-color'. Die camelCase-Form gibt es nur beim Punkt-Zugriff (style.backgroundColor).
Custom-Properties: Der Name muss genau stimmen, auch bei Groß-/Kleinschreibung. Der Wert kann Leerzeichen am Anfang enthalten (z. B. bei --x: red), deshalb am besten .trim() anwenden. Custom-Properties werden in getComputedStyle() nicht in absolute Einheiten umgerechnet, außer sie sind über @property registriert.
Kurzschreibweisen (margin, border, font): Wie berechnete Werte für Kurzschreibweisen aussehen, war früher je nach Browser unterschiedlich. Es ist zuverlässiger, die Einzeleigenschaften abzufragen, z. B. margin-top.
element.style vs. getComputedStyle: element.style sieht nur Inline-Stile. Werte aus Stylesheets bekommt man nur über getComputedStyle(). Dessen Ergebnis ist schreibgeschützt: setProperty() darauf wirft einen NoModificationAllowedError.
Performance: Werte aus getComputedStyle() zu lesen kann einen synchronen Layout-Durchlauf erzwingen (Reflow). Deshalb nicht in engen Schleifen abwechselnd lesen und schreiben.
Priorität: !important ist nicht Teil des Rückgabewerts. Die Priorität fragt man mit getPropertyPriority() ab.
Die Methode wird von allen modernen Browsern unterstützt. Der Internet Explorer kennt sie ab Version 9.

Siehe auch

CSSStyleDeclaration CSSStyleDeclaration.setProperty() CSSStyleDeclaration.removeProperty() CSSStyleDeclaration.getPropertyPriority() Window.getComputedStyle() HTMLElement.style CSSStyleDeclaration.item()