CSSMediaRule.media — Eigenschaft · JavaScript-Referenz

Signatur

CSSMediaRule.media

Beschreibung

Die Eigenschaft media eines CSSMediaRule-Objekts gibt die Media-Query-Liste einer @media-Regel als MediaList zurück. Über dieses Objekt kannst du die Bedingungen der Regel auslesen, zum Beispiel screen and (min-width: 900px). Du kannst sie aber auch zur Laufzeit ändern.

Die Eigenschaft selbst ist schreibgeschützt: Du kannst ihr kein neues Objekt zuweisen. Die zurückgegebene MediaList ist aber veränderbar. Mit mediaText, appendMedium() und deleteMedium() passt du die Bedingungen an. Der Browser wertet die Regel danach sofort neu aus.

Typische Einsatzfälle sind Werkzeuge, die Stylesheets untersuchen (etwa Debugger oder Überprüfungen von Haltepunkten), das dynamische Verschieben von Haltepunkten, ohne CSS neu zu laden, und das Erzeugen von Dokumentation aus vorhandenen Stylesheets.

Rückgabewert

Typ

MediaList

Beschreibung

Eine live mit der Regel verbundene MediaList. Sie hat mediaText (die gesamte Liste als String), length und item(index) sowie die Methoden appendMedium() und deleteMedium().

Beispiele

Alle @media-Regeln eines Stylesheets auflisten

const style = document.createElement('style');
style.textContent = `
  body { margin: 0; }
  @media screen and (min-width: 900px) { body { font-size: 18px; } }
  @media print { nav { display: none; } }
`;
document.head.append(style);

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

for (const rule of rules) {
  console.log(rule.media.mediaText);
}

screen and (min-width: 900px) print

Haltepunkt zur Laufzeit ändern

const style = document.createElement('style');
style.textContent = '@media (min-width: 768px) { .sidebar { display: block; } }';
document.head.append(style);

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

// Die MediaList selbst ist veränderbar
mediaRule.media.mediaText = '(min-width: 1024px)';
console.log(mediaRule.media.mediaText);
console.log(mediaRule.cssText);

(min-width: 1024px) @media (min-width: 1024px) { .sidebar { display: block; } }

Einzelne Medien hinzufügen und entfernen

const sheet = new CSSStyleSheet();
sheet.replaceSync('@media screen { h1 { color: teal; } }');

const { media } = sheet.cssRules[0];
media.appendMedium('print');
console.log(media.length, media.item(1));

media.deleteMedium('screen');
console.log(media.mediaText);

2 print print

Prüfen, ob eine Regel gerade greift

const findActiveMediaRules = (sheet) =>
  [...sheet.cssRules]
    .filter((r) => r instanceof CSSMediaRule)
    .filter((r) => window.matchMedia(r.media.mediaText).matches)
    .map((r) => r.media.mediaText);

console.log(findActiveMediaRules(document.styleSheets[0]));

["screen and (min-width: 900px)"] // abhängig vom Viewport

// Wichtig · Fallstricke

Schreibschutz: Eine Zuweisung wie rule.media = '...' hat keine Wirkung. Im Strict Mode kann sie einen TypeError auslösen. Änderungen laufen immer über rule.media.mediaText oder die Methoden der MediaList.
Serialisierung: Browser normalisieren mediaText. Leerzeichen, Groß- und Kleinschreibung oder die Schreibweise von Bereichsabfragen wie (width >= 600px) können vom Originalquelltext abweichen. Vergleiche daher nicht blind als String.
Ungültige Queries: Nicht auswertbare Media Queries werden zu not all und greifen nie.
Cross-Origin-Stylesheets: Auf cssRules von Stylesheets anderer Herkunft ohne CORS-Freigabe kannst du nicht zugreifen. Es wird ein SecurityError geworfen. Umschließe den Zugriff daher mit try/catch.
Verschachtelung: @media-Regeln können in anderen Gruppierungsregeln stecken (@supports, @layer, CSS Nesting). Um alle Regeln zu finden, musst du cssRules rekursiv durchlaufen.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Das in den Beispielen genutzte CSSStyleSheet.replaceSync() (konstruierbare Stylesheets) ist erst seit 2023 überall verfügbar.

Siehe auch

CSSImportRule.media CSSScopeRule.end CSSImportRule.href CSSNamespaceRule.prefix CSSPageRule.style