CSSMediaRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSMediaRule extends CSSConditionRule

Beschreibung

CSSMediaRule ist die CSSOM-Darstellung einer @media-Regel in einem Stylesheet. Man erhält solche Objekte nicht über einen Konstruktor. Sie tauchen in CSSStyleSheet.cssRules (oder verschachtelt in anderen Gruppierungsregeln) auf und lassen sich mit rule instanceof CSSMediaRule oder rule.constructor.name erkennen.

Die Vererbungskette lautet CSSRule → CSSGroupingRule → CSSConditionRule → CSSMediaRule. Die wichtigsten Mitglieder sind:

media (nur lesbar, MediaList): die Liste der Medienabfragen. Die Liste selbst kann man mit appendMedium(), deleteMedium() oder mediaText verändern.
conditionText (von CSSConditionRule geerbt): die Bedingung als Zeichenkette, z. B. "(max-width: 600px)".
cssRules (CSSRuleList): die Regeln innerhalb des @media-Blocks.
insertRule(rule, index) und deleteRule(index): fügen Regeln innerhalb des Blocks ein oder entfernen sie.
cssText, parentStyleSheet, parentRule: von CSSRule geerbt.

Typische Einsatzfälle sind Werkzeuge, die Breakpoints auslesen, Theme-Editoren, die responsive Regeln zur Laufzeit ändern, und Tests, die prüfen, welche Medienabfragen ein Stylesheet enthält. Ob eine Bedingung gerade zutrifft, verrät CSSMediaRule selbst nicht zuverlässig. Dafür ist window.matchMedia(rule.conditionText) gedacht.

Rückgabewert

Typ

CSSMediaRule

Beschreibung

Instanzen findet man in CSSStyleSheet.cssRules oder in CSSGroupingRule.cssRules. Es gibt keinen öffentlichen Konstruktor.

Beispiele

Alle @media-Regeln eines Stylesheets auflisten

const style = document.createElement('style');
style.textContent = `
  body { margin: 0; }
  @media (max-width: 600px) { body { font-size: 14px; } }
  @media print { nav { display: none; } }
`;
document.head.append(style);

const mediaRules = [...style.sheet.cssRules]
  .filter((rule) => rule instanceof CSSMediaRule);

for (const rule of mediaRules) {
  console.log(rule.conditionText, '→', rule.cssRules.length, 'Regel(n)');
}

(max-width: 600px) → 1 Regel(n) print → 1 Regel(n)

Breakpoint zur Laufzeit ändern

const style = document.createElement('style');
style.textContent = '@media (max-width: 600px) { .sidebar { display: none; } }';
document.head.append(style);

const rule = style.sheet.cssRules[0];
console.log(rule.media.mediaText);

// Breakpoint auf 800px anheben
rule.media.mediaText = '(max-width: 800px)';
console.log(rule.conditionText);
console.log(rule.cssText);

(max-width: 600px) (max-width: 800px) @media (max-width: 800px) { .sidebar { display: none; } }

Regeln innerhalb des @media-Blocks einfügen und löschen

const style = document.createElement('style');
style.textContent = '@media (prefers-color-scheme: dark) { body { background: #111; } }';
document.head.append(style);

const darkRule = style.sheet.cssRules[0];

// Neue Regel am Ende des Blocks einfügen
const index = darkRule.insertRule('a { color: #8cf; }', darkRule.cssRules.length);
console.log(darkRule.cssRules.length, darkRule.cssRules[index].cssText);

// Erste Regel wieder entfernen
darkRule.deleteRule(0);
console.log(darkRule.cssRules.length);

2 a { color: rgb(136, 204, 255); } 1

Prüfen, ob eine @media-Regel gerade zutrifft

const style = document.createElement('style');
style.textContent = '@media (min-width: 1024px) { .grid { columns: 3; } }';
document.head.append(style);

const rule = style.sheet.cssRules[0];
const mql = window.matchMedia(rule.conditionText);

console.log(`Aktiv: ${mql.matches}`);
mql.addEventListener('change', (e) => {
  console.log(`Regel jetzt ${e.matches ? 'aktiv' : 'inaktiv'}`);
});

Aktiv: true (bei einem Fenster ab 1024px Breite)

// Wichtig · Fallstricke

Cross-Origin-Stylesheets: Kommt ein Stylesheet von einer fremden Origin und wird es ohne passende CORS-Header ausgeliefert, wirft der Zugriff auf sheet.cssRules einen SecurityError. Setze deshalb crossorigin am <link> und liefere die Datei mit CORS-Headern aus, oder fange den Fehler mit try/catch ab.
Verschachtelung: @media-Regeln können in @supports, @layer, anderen @media-Regeln oder (bei CSS Nesting) in Stilregeln stecken. Um alle zu finden, muss man die cssRules jeder CSSGroupingRule rekursiv durchlaufen.
Normalisierung: Browser normalisieren cssText, mediaText und Farbwerte (z. B. #8cf → rgb(136, 204, 255)). Vergleiche deshalb keine Rohzeichenketten.
insertRule() wirft einen SyntaxError, wenn die Regel ungültig ist, und einen IndexSizeError, wenn der Index außerhalb des gültigen Bereichs liegt.
conditionText ist in CSSMediaRule praktisch nur lesbar. Ändere die Bedingung über media.mediaText.
Kompatibilität: Das Interface wird von allen modernen Browsern unterstützt. conditionText ist über CSSConditionRule in allen aktuellen Browsern verfügbar.

Siehe auch

CSSImportRule CSSPageRule CSSRule CSSScopeRule CSSStyleRule