CSSStyleDeclaration — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSStyleDeclaration

Beschreibung

CSSStyleDeclaration ist die Schnittstelle für CSS-Deklarationsblöcke, also eine Sammlung von Paaren aus Eigenschaft und Wert. Instanzen erzeugt man nicht selbst. Man bekommt sie über drei Wege:

HTMLElement.style – die Inline-Stile eines Elements (das style-Attribut), lesbar und schreibbar.
window.getComputedStyle(element) – die berechneten Endwerte aller Eigenschaften, nur lesbar.
CSSStyleRule.style – die Deklarationen einer Regel in einem Stylesheet (z. B. über document.styleSheets).

Die wichtigsten Mitglieder sind getPropertyValue(name), setProperty(name, value, priority), removeProperty(name), getPropertyPriority(name), die Eigenschaften cssText (der gesamte Block als Zeichenkette), length und item(index) sowie parentRule. Außerdem gibt es für jede CSS-Eigenschaft eine Zugriffseigenschaft in camelCase, z. B. style.backgroundColor für background-color.

Für CSS Custom Properties (--meine-variable) funktionieren nur setProperty() und getPropertyValue(). Einen camelCase-Zugriff gibt es dafür nicht. Brauchst du typisierte Werte statt Zeichenketten, ist die CSS Typed OM (element.attributeStyleMap) die modernere Alternative.

Rückgabewert

Typ

CSSStyleDeclaration

Beschreibung

Wird von element.style, getComputedStyle() und CSSStyleRule.style zurückgegeben. Es gibt keinen öffentlichen Konstruktor.

Beispiele

Inline-Stile setzen und lesen

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

// camelCase-Zugriff
box.style.backgroundColor = 'tomato';
box.style.padding = '1rem';

// Bindestrich-Schreibweise über setProperty, hier mit !important
box.style.setProperty('border-radius', '8px', 'important');

console.log(box.style.cssText);
console.log(box.style.getPropertyPriority('border-radius'));
console.log(box.style.length);

background-color: tomato; padding: 1rem; border-radius: 8px !important; important 6

Berechnete Stile auslesen (nur lesbar)

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

console.log(computed.getPropertyValue('font-size')); // z. B. "32px"
console.log(computed.display);                      // z. B. "block"

try {
  computed.setProperty('color', 'red');
} catch (err) {
  console.log(err.name); // Schreiben ist nicht erlaubt
}

32px block NoModificationAllowedError

CSS Custom Properties für Theme-Wechsel

const root = document.documentElement;

const setTheme = (dark) => {
  root.style.setProperty('--bg', dark ? '#111' : '#fff');
  root.style.setProperty('--fg', dark ? '#eee' : '#222');
};

setTheme(true);
console.log(root.style.getPropertyValue('--bg'));

// Variable wieder entfernen, removeProperty gibt den alten Wert zurück
const old = root.style.removeProperty('--bg');
console.log(old, root.style.getPropertyValue('--bg') === '');

#111 #111 true

Alle Deklarationen durchlaufen

const el = document.createElement('p');
el.style.cssText = 'color: navy; margin: 0 auto; font-weight: bold';

for (let i = 0; i < el.style.length; i++) {
  const name = el.style.item(i);
  console.log(`${name}: ${el.style.getPropertyValue(name)}`);
}

color: navy margin-top: 0px margin-right: auto margin-bottom: 0px margin-left: auto font-weight: bold

// Wichtig · Fallstricke

Kurzschreibweisen werden aufgelöst: Aus margin werden intern die Einzeleigenschaften margin-top, margin-right usw. Deshalb zählen length und item() die Einzeleigenschaften. Bei getComputedStyle() können Kurzschreibweisen je nach Browser einen leeren String liefern. Frag dort besser die Einzeleigenschaften ab.
element.style enthält nur Inline-Stile: Werte aus Stylesheets tauchen dort nicht auf. Für den tatsächlich wirksamen Wert brauchst du getComputedStyle().
Ungültige Werte werden stillschweigend verworfen: Nach style.width = '10' (ohne Einheit) bleibt der alte Wert erhalten, und es wird kein Fehler geworfen.
Priorität: !important geht nur über den dritten Parameter von setProperty(). Mit style.color = 'red !important' ist der Wert ungültig und wird ignoriert.
cssText ersetzt alles: Wer cssText zuweist, überschreibt alle vorhandenen Inline-Stile.
Sicherheit/CSP: Inline-Stile über das CSSOM zu setzen, verstößt nicht gegen style-src ohne 'unsafe-inline'. Das style-Attribut per setAttribute('style', …) zu setzen, wird dagegen blockiert. Übernimm Benutzereingaben trotzdem nie ungeprüft in cssText, weil z. B. url() ungewollte Anfragen auslösen kann.
Performance: Wenn du Stile liest, nachdem du sie geschrieben hast (z. B. offsetWidth oder getComputedStyle), erzwingst du ein synchrones Layout. Lese- und Schreibzugriffe deshalb bündeln.
Die Schnittstelle wird in allen Browsern unterstützt. Vendor-Präfixe wie webkitTransform sind veraltet.

Siehe auch

CSSNestedDeclarations CSSFunctionDeclarations CSSStyleProperties CSSStyleRule CSSStyleSheet