StylePropertyMap.set() — Methode · JavaScript-Referenz

Signatur

StylePropertyMap.prototype.set(property, ...values)

Beschreibung

Die Methode set() gehört zum CSS Typed Object Model (Houdini). Sie schreibt einen Wert für eine CSS-Eigenschaft in eine StylePropertyMap, typischerweise in element.attributeStyleMap (das Inline-style-Attribut) oder in CSSStyleRule.styleMap (eine Regel in einem Stylesheet). Ein schon vorhandener Wert der Eigenschaft wird dabei vollständig ersetzt.

Im Gegensatz zu element.style.width = "100px" übergibt man hier keine Zeichenketten, sondern typisierte Werte wie CSS.px(100), CSS.percent(50) oder new CSSUnitValue(1, "em"). Der Browser muss sie deshalb nicht erst als Text parsen und die Werte lassen sich direkt mit Zahlen berechnen. Zeichenketten werden aber weiterhin angenommen und nach der CSS-Grammatik der Eigenschaft geparst.

Listenwertige Eigenschaften wie transition-property oder background-image nehmen mehrere Werte als weitere Argumente an. Custom Properties (--meine-variable) werden ebenfalls unterstützt.

Die Methode ist nur auf veränderbaren Maps vorhanden. Die Map aus element.computedStyleMap() ist eine schreibgeschützte StylePropertyMapReadOnly und hat kein set().

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft in CSS-Schreibweise (mit Bindestrich), z. B. `"background-color"`, `"margin-top"` oder eine Custom Property wie `"--abstand"`. Die camelCase-Schreibweise wird nicht akzeptiert.
$...values Pflicht	CSSStyleValue \| string		Ein oder mehrere Werte: `CSSStyleValue`-Objekte (z. B. `CSSUnitValue`, `CSSKeywordValue`, `CSSTransformValue`) oder CSS-Zeichenketten. Mehr als ein Wert ist nur bei listenwertigen Eigenschaften erlaubt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Änderung wird sofort in der Map und damit im zugehörigen Stil (Inline-Stil bzw. CSS-Regel) wirksam.

Beispiele

Inline-Stil mit typisierten Werten setzen

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

// Typisierte Werte statt Zeichenketten
box.attributeStyleMap.set('width', CSS.px(240));
box.attributeStyleMap.set('opacity', CSS.number(0.8));
box.attributeStyleMap.set('display', new CSSKeywordValue('flex'));

// Zeichenketten werden ebenfalls geparst
box.attributeStyleMap.set('background-color', 'rebeccapurple');

console.log(box.getAttribute('style'));

width: 240px; opacity: 0.8; display: flex; background-color: rebeccapurple;

Rechnen mit Werten, ohne Zeichenketten zu parsen

const panel = document.querySelector('#panel');
panel.attributeStyleMap.set('margin-left', CSS.px(10));

const vergroessern = () => {
  const aktuell = panel.attributeStyleMap.get('margin-left'); // CSSUnitValue
  panel.attributeStyleMap.set('margin-left', CSS.px(aktuell.value + 10));
  console.log(panel.attributeStyleMap.get('margin-left').toString());
};

document.querySelector('#weiter').addEventListener('click', vergroessern);

20px (nach dem ersten Klick)

Transformation und Custom Property setzen

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

karte.attributeStyleMap.set('transform', new CSSTransformValue([
  new CSSTranslate(CSS.px(20), CSS.px(0)),
  new CSSRotate(CSS.deg(15))
]));

// Custom Property (wird als nicht geparster Wert gespeichert)
karte.attributeStyleMap.set('--akzent', 'tomato');

console.log(karte.attributeStyleMap.get('transform').toString());

translate(20px, 0px) rotate(15deg)

Regel in einem Stylesheet ändern und mehrere Listenwerte übergeben

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

const regel = sheet.cssRules[0];
regel.styleMap.set('color', 'white');
// Listenwertige Eigenschaft: mehrere Werte
regel.styleMap.set('transition-property', 'color', 'background-color');

console.log(regel.cssText);

.btn { color: white; transition-property: color, background-color; }

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen CSS Typed OM seit Version 66, Safari seit 16.4. Firefox hat die Unterstützung erst spät bekommen. Prüfen Sie die Unterstützung vorab, z. B. mit if ('attributeStyleMap' in Element.prototype), und greifen Sie sonst auf element.style.setProperty() zurück.
Ungültige Werte: Passt ein Wert nicht zur Eigenschaft (z. B. set('width', CSS.deg(10)) oder eine Zeichenkette, die sich nicht parsen lässt), wird ein TypeError geworfen. Anders als bei element.style wird der Wert also nicht stillschweigend ignoriert.
Unbekannte Eigenschaften (keine Custom Property) und mehrere Werte für nicht listenwertige Eigenschaften führen ebenfalls zu einem TypeError.
Der Eigenschaftsname muss in CSS-Schreibweise angegeben werden ('font-size', nicht 'fontSize').
set() ersetzt vorhandene Werte. Um bei Listen-Eigenschaften etwas hinzuzufügen, verwenden Sie append().
computedStyleMap() gibt eine schreibgeschützte Map zurück. Ein Aufruf von set() darauf ist nicht möglich.
Die Priorität !important lässt sich über set() nicht setzen. Dafür brauchen Sie style.setProperty(name, value, 'important').

Siehe auch

StylePropertyMap StylePropertyMap.append() StylePropertyMap.delete() StylePropertyMap.clear() StylePropertyMapReadOnly.get() Element.computedStyleMap() CSSUnitValue CSSStyleDeclaration.setProperty()