StylePropertyMap — Schnittstelle · JavaScript-Referenz

Signatur

interface StylePropertyMap extends StylePropertyMapReadOnly

Beschreibung

StylePropertyMap gehört zur CSS Typed Object Model API (Houdini). Sie stellt CSS-Eigenschaften nicht als Zeichenketten dar, sondern als typisierte Objekte wie CSSUnitValue, CSSKeywordValue oder CSSTransformValue. Man muss also keine Werte wie "10px" mehr per String-Verkettung bauen oder mit parseFloat() zerlegen, sondern arbeitet direkt mit Zahl und Einheit.

Einen Konstruktor gibt es nicht. Instanzen bekommt man über element.attributeStyleMap (entspricht dem Inline-style-Attribut) oder über CSSStyleRule.styleMap (Regeln in einem Stylesheet). element.computedStyleMap() gibt dagegen nur eine schreibgeschützte StylePropertyMapReadOnly zurück.

Von StylePropertyMapReadOnly erbt die Schnittstelle get(), getAll(), has(), size sowie die Iteration (entries(), keys(), values(), forEach(), for…of). Eigene, verändernde Methoden sind:

set(property, ...values) – setzt eine Eigenschaft und ersetzt vorhandene Werte.
append(property, ...values) – hängt Werte an eine listenwertige Eigenschaft an (z. B. transition-duration, background-image).
delete(property) – entfernt eine Eigenschaft.
clear() – entfernt alle Deklarationen.

Die typisierten Werte sind vor allem bei Animationen und bei häufigen Stil-Aktualisierungen praktisch, weil der Browser weniger Strings parsen und serialisieren muss und Einheitenfehler früh als Ausnahme gemeldet werden.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft in CSS-Schreibweise, z. B. `"padding-top"` oder eine Custom Property wie `"--abstand"`. Gilt für `set()`, `append()` und `delete()`.
$...values Pflicht	CSSStyleValue \| string		Ein oder mehrere Werte für `set()` bzw. `append()`, entweder als typisiertes Objekt (z. B. `CSS.px(10)`) oder als CSS-String (z. B. `"1s"`). Mehrere Werte sind nur bei listenwertigen Eigenschaften erlaubt.

Beispiele

Inline-Stil typisiert setzen und lesen

const box = document.querySelector('.box');

// Werte als typisierte Objekte setzen
box.attributeStyleMap.set('padding', CSS.px(12));
box.attributeStyleMap.set('opacity', 0.8);

const padding = box.attributeStyleMap.get('padding');
console.log(padding.value, padding.unit);
console.log(padding.toString());
console.log(box.getAttribute('style'));

12 px 12px padding: 12px; opacity: 0.8;

Listenwertige Eigenschaft mit append() erweitern

const el = document.querySelector('#karte');
const styles = el.attributeStyleMap;

styles.set('transition-property', 'opacity, transform');
styles.set('transition-duration', CSS.ms(200));
styles.append('transition-duration', CSS.s(1));

console.log(styles.getAll('transition-duration').map(String));

// Einzelne Eigenschaft entfernen, dann alles leeren
styles.delete('transition-property');
console.log(styles.has('transition-property'));
styles.clear();
console.log(styles.size);

["200ms", "1s"] false 0

Wert ohne String-Parsing hochzählen (Animation)

const ball = document.querySelector('.ball');
ball.attributeStyleMap.set('transform', new CSSTranslate(CSS.px(0), CSS.px(0)));

let x = 0;
const schritt = () => {
  x += 2;
  // Kein Zusammenbauen von 'translate(' + x + 'px, 0px)' nötig
  ball.attributeStyleMap.set('transform', new CSSTransformValue([
    new CSSTranslate(CSS.px(x), CSS.px(0))
  ]));
  if (x < 300) requestAnimationFrame(schritt);
};
requestAnimationFrame(schritt);

Stylesheet-Regel über CSSStyleRule.styleMap ändern

const sheet = new CSSStyleSheet();
sheet.replaceSync('.hinweis { color: black; margin: 4px; }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[0];
rule.styleMap.set('color', 'crimson');
rule.styleMap.set('margin', CSS.rem(1));

for (const [prop, [wert]] of rule.styleMap) {
  console.log(prop, String(wert));
}

color crimson margin-top 1rem margin-right 1rem margin-bottom 1rem margin-left 1rem

// Wichtig · Fallstricke

Browser-Kompatibilität: Firefox unterstützt das CSS Typed OM bisher nicht. Deshalb vor der Verwendung per Feature-Erkennung prüfen, z. B. if ('attributeStyleMap' in HTMLElement.prototype), und sonst auf element.style zurückgreifen.
append() funktioniert nur bei listenwertigen Eigenschaften. Bei einfachen Eigenschaften wie width wird ein TypeError ausgelöst. Ein TypeError tritt auch bei ungültigen Werten auf, etwa bei set('width', CSS.deg(10)).
element.computedStyleMap() ist schreibgeschützt (StylePropertyMapReadOnly) und hat keine Methoden set(), append(), delete() oder clear().
Kurzschreibweisen wie margin werden beim Iterieren oft in die einzelnen Langform-Eigenschaften aufgelöst, und get('margin') kann einen CSSStyleValue ohne genauere Typisierung zurückgeben.
Die Iterationsreihenfolge und die Serialisierung können von Browser zu Browser leicht abweichen. Verlass dich nicht auf exakte Strings.
Werte, die der Browser nicht typisieren kann (z. B. unregistrierte Custom Properties), kommen als CSSUnparsedValue zurück.

Siehe auch

CSSStyleProperties StylePropertyMapReadOnly CSSPropertyRule StyleSheet StyleSheetList