Element.computedStyleMap() — Methode · JavaScript-Referenz

Signatur

Element.prototype.computedStyleMap()

Beschreibung

computedStyleMap() gehört zum CSS Typed Object Model (Houdini) und ist die typisierte Alternative zu window.getComputedStyle(). Statt Strings wie "16px" bekommst du Objekte wie CSSUnitValue { value: 16, unit: "px" }, CSSKeywordValue oder CSSMathValue. So musst du Werte nicht mehr mit parseFloat() oder regulären Ausdrücken zerlegen.

Die zurückgegebene StylePropertyMapReadOnly funktioniert ähnlich wie eine Map: Mit get() liest du den ersten Wert einer Eigenschaft, mit getAll() alle Werte (z. B. bei mehreren background-image-Ebenen) und mit has() prüfst du, ob eine Eigenschaft vorhanden ist. Außerdem kannst du die Map mit for...of durchlaufen, und size gibt die Anzahl der Einträge an. Eigenschaftsnamen schreibst du in CSS-Schreibweise ("padding-top", nicht paddingTop). Benutzerdefinierte Eigenschaften (--meine-farbe) sind ebenfalls enthalten.

Nützlich ist die Methode vor allem dann, wenn du mit berechneten Werten rechnen willst, etwa bei Animationen, Layout-Berechnungen oder beim Auslesen von CSS-Variablen, oder wenn du Einheiten sauber umrechnen möchtest (CSSUnitValue.prototype.to()). Sie liefert berechnete Werte (computed values) und nicht wie getComputedStyle() teilweise aufgelöste Werte (resolved values). width: auto bleibt daher z. B. das Schlüsselwort auto und wird nicht in eine Pixelangabe umgewandelt.

Rückgabewert

Typ

StylePropertyMapReadOnly

Beschreibung

Eine schreibgeschützte, Map-ähnliche Sammlung aller berechneten CSS-Eigenschaften des Elements. Die Werte sind CSSStyleValue-Unterklassen wie CSSUnitValue, CSSKeywordValue, CSSMathSum oder CSSUnparsedValue.

Beispiele

Typisierten Wert auslesen und damit rechnen

// HTML: <button id="btn" style="padding-top: 1rem">OK</button>
const btn = document.querySelector('#btn');
const styles = btn.computedStyleMap();

const padding = styles.get('padding-top');
console.log(padding.value, padding.unit);

// Ohne parseFloat direkt rechnen
const doppelt = CSS.px(padding.value * 2);
btn.attributeStyleMap.set('padding-bottom', doppelt);
console.log(btn.style.paddingBottom);

16 px 32px

Unterschied zu getComputedStyle(): computed vs. resolved

// HTML: <div id="box" style="width: auto">Inhalt</div>
const box = document.querySelector('#box');

const typed = box.computedStyleMap().get('width');
console.log(typed.constructor.name, typed.toString());

const resolved = getComputedStyle(box).width;
console.log(resolved);

CSSKeywordValue auto "784px" (je nach Layout)

Alle Eigenschaften durchlaufen und CSS-Variable lesen

// CSS: :root { --akzent: #0a84ff; }
const map = document.documentElement.computedStyleMap();

console.log('Anzahl Eigenschaften:', map.size);
console.log('Akzent:', map.get('--akzent')?.toString().trim());

// Nur die margin-Eigenschaften ausgeben
for (const [prop, values] of map) {
  if (prop.startsWith('margin-')) {
    console.log(prop, values.map(v => v.toString()).join(', '));
  }
}

Anzahl Eigenschaften: 3xx (browserabhängig) Akzent: #0a84ff margin-block-end 0px ...

Feature-Erkennung mit Fallback

const getPx = (el, prop) => {
  if ('computedStyleMap' in Element.prototype) {
    const v = el.computedStyleMap().get(prop);
    // In Pixel umrechnen, falls möglich
    if (v instanceof CSSUnitValue) return v.to('px').value;
  }
  // Fallback, z. B. für Firefox
  return parseFloat(getComputedStyle(el).getPropertyValue(prop));
};

console.log(getPx(document.body, 'margin-top'));

8

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser ab Version 66 und Safari ab 16.4. Firefox unterstützt die Methode (Stand 2024) nicht. Sie ist also nicht Baseline. Prüfe vorher mit 'computedStyleMap' in Element.prototype, ob sie verfügbar ist, und nutze sonst getComputedStyle().
Berechnete statt aufgelöste Werte: Anders als bei getComputedStyle() bleiben z. B. auto, Prozentwerte oder calc()-Ausdrücke teils erhalten (CSSKeywordValue oder CSSMathSum). Prüfe deshalb mit instanceof CSSUnitValue, bevor du auf .value zugreifst.
Pseudo-Elemente: Die Methode hat keinen Parameter für ::before oder ::after. Für Pseudo-Elemente brauchst du weiterhin getComputedStyle(el, '::before').
Schreibgeschützt: set() und delete() gibt es hier nicht. Zum Schreiben nutzt du element.attributeStyleMap (Inline-Styles).
Eigenschaftsnamen: Schreibe sie in CSS-Schreibweise mit Bindestrichen. Kurzschreibweisen wie margin werden unterschiedlich unterstützt, verlässlicher sind die ausgeschriebenen Eigenschaften (margin-top).
Performance: Wie bei getComputedStyle() kann das Lesen eine Stil- oder Layout-Neuberechnung auslösen. Vermeide Lese- und Schreibzugriffe im Wechsel innerhalb von Schleifen („Layout Thrashing“).

Siehe auch

Window.getComputedStyle() StylePropertyMapReadOnly CSSUnitValue CSSStyleValue new HTMLOutputElement() new TextDecoderStream()