StylePropertyMapReadOnly — Schnittstelle · JavaScript-Referenz

Signatur

interface StylePropertyMapReadOnly

Beschreibung

StylePropertyMapReadOnly gehört zur CSS Typed Object Model API (Houdini) und bildet einen CSS-Deklarationsblock als Map ab, die nur gelesen werden kann. Im Gegensatz zu CSSStyleDeclaration liefert sie keine Strings wie "16px", sondern typisierte Objekte wie CSSUnitValue ({value: 16, unit: "px"}), CSSKeywordValue oder CSSMathValue. So lässt sich mit CSS-Werten rechnen, ohne Strings zerlegen zu müssen.

Meistens bekommt man eine Instanz über Element.computedStyleMap(), das die berechneten Werte eines Elements liefert (ähnlich wie getComputedStyle()). In einem CSS Paint Worklet bekommt die paint()-Methode außerdem ein StylePropertyMapReadOnly mit den Eigenschaften, die in inputProperties angegeben sind. Die beschreibbare Unterklasse StylePropertyMap erhält man über element.attributeStyleMap oder CSSStyleRule.styleMap.

Die Schnittstelle kann durchlaufen werden wie eine Map und bietet folgende Mitglieder:

get(property) – erster Wert der Eigenschaft als CSSStyleValue oder undefined
getAll(property) – Array aller Werte, z. B. bei Listen wie transition-property
has(property) – true, wenn die Eigenschaft in der Map vorkommt
size – Anzahl der Einträge
entries(), keys(), values(), forEach() und [Symbol.iterator] – Iteration über Paare der Form [property, CSSStyleValue[]]

Eigenschaftsnamen werden in CSS-Schreibweise angegeben ("font-size", nicht "fontSize"). Auch Custom Properties wie "--main-color" sind erlaubt.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Für `get()`, `getAll()` und `has()`: CSS-Eigenschaftsname in Kebab-Schreibweise oder Custom Property (`--name`). Bei unbekannten Namen wirft `get()`/`getAll()` einen `TypeError`.

Rückgabewert

Typ

CSSStyleValue | undefined | CSSStyleValue[] | boolean

Beschreibung

get() gibt einen CSSStyleValue (oder undefined) zurück, getAll() ein Array von CSSStyleValue, has() einen boolean. size ist eine number.

Beispiele

Berechnete Schriftgröße typisiert auslesen

const heading = document.querySelector('h1');
const styles = heading.computedStyleMap(); // StylePropertyMapReadOnly

const fontSize = styles.get('font-size');
console.log(fontSize.value, fontSize.unit);

// Mit dem Wert rechnen, ohne Strings zu zerlegen
const doubled = fontSize.mul(2);
console.log(doubled.toString());

32 px 32px

Alle berechneten Eigenschaften durchlaufen

const box = document.querySelector('.card');
const map = box.computedStyleMap();

console.log('Anzahl Eigenschaften:', map.size);

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

Anzahl Eigenschaften: 380 margin-block-end 0px margin-block-start 0px margin-bottom 16px ...

Typ des Werts prüfen und Listenwerte lesen

const el = document.querySelector('.animated');
const map = el.computedStyleMap();

const width = map.get('width');
if (width instanceof CSSUnitValue) {
  console.log(`Breite: ${width.to('px').value}px`);
} else if (width instanceof CSSKeywordValue) {
  console.log('Schlüsselwort:', width.value);
}

// Mehrwertige Eigenschaft
const props = map.getAll('transition-property');
console.log(props.map(v => v.toString()));

console.log(map.has('--theme-color'));

Breite: 240px ["opacity", "transform"] true

Nutzung in einem CSS Paint Worklet

// paint-worklet.js – laden mit: CSS.paintWorklet.addModule('paint-worklet.js')
registerPaint('dots', class {
  static get inputProperties() {
    return ['--dot-color', '--dot-size'];
  }

  paint(ctx, size, properties) {
    // properties ist ein StylePropertyMapReadOnly
    const color = properties.get('--dot-color').toString().trim() || 'black';
    const dot = parseFloat(properties.get('--dot-size').toString()) || 4;

    ctx.fillStyle = color;
    for (let x = dot; x < size.width; x += dot * 3) {
      ctx.beginPath();
      ctx.arc(x, size.height / 2, dot, 0, Math.PI * 2);
      ctx.fill();
    }
  }
});

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (ab Chrome/Edge 66) und Safari ab 16.4 unterstützen die Schnittstelle. Firefox unterstützt sie bisher nicht. Vor der Nutzung prüfen: if ('computedStyleMap' in Element.prototype) { … } und sonst auf getComputedStyle() ausweichen.

Die Map ist schreibgeschützt, set(), append(), delete() und clear() gibt es hier nicht. Zum Schreiben element.attributeStyleMap (StylePropertyMap) nutzen.
computedStyleMap() gibt berechnete Werte zurück, keine verwendeten Werte. Deshalb kann width z. B. als CSSKeywordValue("auto") zurückkommen und nicht als Pixelwert. Mit instanceof den Typ prüfen, bevor man auf .value/.unit zugreift.
Die Map ist live: Wenn sich die Styles ändern, ändern sich auch die Werte beim nächsten Zugriff. Häufige Zugriffe können einen Stil-Neuberechnung auslösen, also nicht unnötig in Animationsschleifen abfragen.
Nicht registrierte Custom Properties kommen als CSSUnparsedValue zurück, oft mit führenden Leerzeichen. Mit CSS.registerProperty() bekommt man stattdessen typisierte Werte.
CamelCase-Namen wie "fontSize" sind ungültig und führen zu einem TypeError.
Kurzschreibweisen (margin, background) werden in der berechneten Map teils nicht oder nur eingeschränkt unterstützt. Die Langform-Eigenschaften sind zuverlässiger.

Siehe auch

StylePropertyMap DOMPointReadOnly DOMRectReadOnly CSSPropertyRule CSSStyleProperties