CSSStyleRule.styleMap — Eigenschaft · JavaScript-Referenz

Signatur

get CSSStyleRule.styleMap

Beschreibung

Die schreibgeschützte Eigenschaft styleMap einer CSSStyleRule gibt ein StylePropertyMap-Objekt zurück. Es gehört zum CSS Typed Object Model (Typed OM) und bildet die Deklarationen der Regel (z. B. .card { width: 200px; }) als Schlüssel-Wert-Paare ab. Anders als bei CSSStyleRule.style, das Werte als Strings liefert, erhält man hier Objekte wie CSSUnitValue oder CSSKeywordValue.

Das ist nützlich, wenn du Stylesheet-Regeln per Skript anpassen willst, ohne Strings zusammenzubauen und wieder zu zerlegen: rule.styleMap.set('width', CSS.px(320)) statt rule.style.width = '320px'. Mit der typisierten Form kann man direkt rechnen (value.value * 2), die Einheit abfragen (value.unit) und Werte mit CSS.px(), CSS.percent() usw. erzeugen.

Die Map ist live: Änderungen über set(), append(), delete() oder clear() wirken sofort auf die Regel und damit auf alle Elemente, auf die der Selektor zutrifft. Die Eigenschaft selbst kann nicht neu zugewiesen werden – man ändert immer nur den Inhalt der zurückgegebenen Map.

Wichtig: styleMap enthält nur die in der Regel deklarierten Werte, nicht die berechneten Werte eines Elements. Für berechnete Werte gibt es Element.computedStyleMap(), für Inline-Stile HTMLElement.attributeStyleMap.

Rückgabewert

Typ

StylePropertyMap

Beschreibung

Eine live verknüpfte, veränderbare Map der Deklarationen dieser Regel. Werte werden als CSSStyleValue-Unterklassen geliefert (z. B. CSSUnitValue, CSSKeywordValue, CSSUnparsedValue).

Beispiele

Typisierten Wert aus einer Stylesheet-Regel lesen

// Konstruierbares Stylesheet anlegen und einbinden
const sheet = new CSSStyleSheet();
sheet.replaceSync('.card { width: 200px; opacity: 0.5; }');
document.adoptedStyleSheets = [sheet];

const rule = sheet.cssRules[0]; // CSSStyleRule
const width = rule.styleMap.get('width');

console.log(width.value, width.unit);
console.log(width instanceof CSSUnitValue);
console.log(rule.styleMap.get('opacity').value);

200 "px" true 0.5

Regel per Skript ändern – wirkt auf alle .card-Elemente

const sheet = new CSSStyleSheet();
sheet.replaceSync('.card { width: 200px; opacity: 0.5; }');
document.adoptedStyleSheets = [sheet];

const rule = sheet.cssRules[0];
const { styleMap } = rule;

// Breite verdoppeln, ohne Strings zu parsen
const current = styleMap.get('width');
styleMap.set('width', CSS.px(current.value * 2));

// Deklaration entfernen
styleMap.delete('opacity');

console.log(rule.cssText);

.card { width: 400px; }

Alle Deklarationen einer Regel durchlaufen

const sheet = new CSSStyleSheet();
sheet.replaceSync('.btn { padding-top: 8px; color: red; }');

const rule = sheet.cssRules[0];
console.log('Anzahl:', rule.styleMap.size);

for (const [property, values] of rule.styleMap) {
  // values ist immer ein Array von CSSStyleValue-Objekten
  console.log(property, values.map(String).join(', '));
}

Anzahl: 2 color red padding-top 8px

Feature-Erkennung mit Rückfall auf CSSStyleDeclaration

const setRuleWidth = (rule, px) => {
  if ('styleMap' in CSSStyleRule.prototype) {
    rule.styleMap.set('width', CSS.px(px));
  } else {
    // Firefox & ältere Browser
    rule.style.setProperty('width', `${px}px`);
  }
};

const sheet = new CSSStyleSheet();
sheet.replaceSync('.box { width: 100px; }');
setRuleWidth(sheet.cssRules[0], 250);
console.log(sheet.cssRules[0].style.width);

250px

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser seit Version 66, Safari seit 16.4. Firefox unterstützt das CSS Typed OM (noch) nicht – vor der Nutzung mit 'styleMap' in CSSStyleRule.prototype prüfen und auf rule.style zurückfallen.
Nur deklarierte Werte: get() liefert undefined für Eigenschaften, die in der Regel nicht vorkommen – auch wenn das Element über Vererbung oder andere Regeln einen Wert hat. Für berechnete Werte Element.computedStyleMap() verwenden.
Kurzschreibweisen: Shorthands wie padding oder margin werden oft nicht als typisierter Wert geliefert, sondern als generischer CSSStyleValue. Für sauberes Rechnen die Einzeleigenschaften (padding-top …) abfragen.
Werte mit var() kommen als CSSUnparsedValue zurück und haben keine value/unit-Eigenschaft.
Cross-Origin-Stylesheets: Bei Stylesheets von fremden Ursprüngen ohne CORS wirft bereits der Zugriff auf sheet.cssRules einen SecurityError.
Ungültige Werte in set() (z. B. styleMap.set('width', 'rot')) lösen einen TypeError aus, statt still ignoriert zu werden wie bei style.width = ….
Nur Regeln vom Typ CSSStyleRule besitzen styleMap; @media- oder @keyframes-Regeln in cssRules vorher per instanceof CSSStyleRule herausfiltern.

Siehe auch

CSSStyleRule.style CSSStyleRule.selectorText CSSPageRule.style CSSFontFaceRule.style CSSKeyframeRule.style