CSSStyleProperties — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSStyleProperties extends CSSStyleDeclaration

Beschreibung

CSSStyleProperties ist die Schnittstelle des CSS Object Model (CSSOM), die du über element.style, window.getComputedStyle(element) und CSSStyleRule.style bekommst. Sie erbt von CSSStyleDeclaration und bringt deshalb dieselben generischen Mitglieder mit: cssText, length, parentRule, getPropertyValue(), setProperty(), removeProperty(), getPropertyPriority() und item().

Neu ist, dass die Spezifikation die benannten CSS-Eigenschaften jetzt direkt bei CSSStyleProperties festlegt und nicht mehr bei CSSStyleDeclaration. Für jede unterstützte CSS-Property gibt es mehrere Schreibweisen:

camelCase: style.backgroundColor
mit Bindestrich (Klammer-Schreibweise): style["background-color"]
Webkit-Präfix: style.webkitTransform bzw. style.WebkitTransform
Sonderfall cssFloat für die Property float, weil float früher ein reserviertes Wort war.

Du verwendest die Schnittstelle, um Styles per JavaScript zu lesen oder zu setzen: Inline-Styles über element.style (lesbar und schreibbar), endgültig berechnete Werte über getComputedStyle() (nur lesbar) und Regeln in Stylesheets über CSSStyleRule.style. Benutzerdefinierte Eigenschaften (--variablen) erreichst du nur über getPropertyValue() und setProperty(), nicht über Punkt-Schreibweise.

Rückgabewert

Typ

CSSStyleProperties

Beschreibung

Wird von HTMLElement.style, SVGElement.style, MathMLElement.style, window.getComputedStyle() und CSSStyleRule.style zurückgegeben. Die Schnittstelle hat keinen öffentlichen Konstruktor.

Beispiele

Inline-Styles über element.style setzen und lesen

const box = document.createElement("div");
document.body.append(box);

// camelCase- und Bindestrich-Schreibweise sind gleichwertig
box.style.backgroundColor = "rebeccapurple";
box.style["border-radius"] = "8px";
box.style.cssFloat = "left"; // entspricht CSS 'float'

console.log(box.style.backgroundColor);
console.log(box.style.borderRadius);
console.log(box.getAttribute("style"));

rebeccapurple 8px background-color: rebeccapurple; border-radius: 8px; float: left;

Berechnete Werte mit getComputedStyle() auslesen

const heading = document.querySelector("h1") ?? document.body;
const computed = getComputedStyle(heading);

// Werte sind aufgelöst, z. B. Farben als rgb(), Längen in px
console.log(computed.fontSize);
console.log(computed.getPropertyValue("color"));

try {
  computed.color = "red"; // nur lesbar
} catch (err) {
  console.log(err.name);
}

32px rgb(0, 0, 0) NoModificationAllowedError

CSS-Variablen und Priorität mit setProperty()

const root = document.documentElement;

// Benutzerdefinierte Eigenschaften gehen nur über setProperty/getPropertyValue
root.style.setProperty("--akzent", "#e63946");
root.style.setProperty("margin", "0", "important");

console.log(root.style.getPropertyValue("--akzent"));
console.log(root.style.getPropertyPriority("margin"));
console.log(getComputedStyle(root).getPropertyValue("--akzent").trim());

#e63946 important #e63946

Regel in einem Stylesheet über CSSStyleRule.style ändern

const sheet = new CSSStyleSheet();
sheet.replaceSync(".karte { padding: 1rem; color: navy; }");
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[0];
rule.style.padding = "2rem";
rule.style.removeProperty("color");

console.log(rule.style.cssText);
console.log(rule.style instanceof CSSStyleDeclaration);

padding: 2rem; true

// Wichtig · Fallstricke

Kompatibilität: CSSStyleProperties ist neu in der CSSOM-Spezifikation. Firefox stellt die Schnittstelle seit Version 138 bereit, andere Browser geben stattdessen weiterhin ein CSSStyleDeclaration-Objekt mit denselben Eigenschaften zurück. Für die Praxis ändert sich nichts. Prüfe aber lieber mit instanceof CSSStyleDeclaration (klappt überall) statt mit instanceof CSSStyleProperties, oder erkenne die Funktion per typeof CSSStyleProperties !== "undefined".
element.style enthält nur Inline-Styles, keine Werte aus Stylesheets. Den tatsächlich angewendeten Wert liefert getComputedStyle().
Das Objekt von getComputedStyle() ist nur lesbar und live: Es ändert sich, wenn sich die Styles ändern. Jeder Lesezugriff kann ein Neuberechnen des Layouts auslösen (Layout Thrashing). Lies deshalb am besten erst alle Werte und schreib danach.
Ungültige Werte werden beim Setzen stillschweigend ignoriert, es kommt keine Fehlermeldung. Zahlen ohne Einheit (style.width = 100) funktionieren nicht, außer bei Properties ohne Einheit wie opacity.
!important lässt sich nicht per Zuweisung setzen, nur mit setProperty(name, wert, "important").
Sicherheit: Wenn du nicht vertrauenswürdige Eingaben in cssText oder in url()-Werte schreibst, kannst du Datenabfluss per CSS ermöglichen. Prüfe die Werte vorher. Eine strikte CSP (style-src) blockiert das style-Attribut im HTML, aber nicht das Setzen über das CSSOM.

Siehe auch

StylePropertyMap CSSStyleDeclaration CSSStyleRule CSSStyleSheet CSSPerspective