MediaList — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaList

Beschreibung

MediaList ist eine geordnete Liste von Media-Queries in Textform. Du bekommst ein solches Objekt nicht über einen Konstruktor, sondern über bestehende CSSOM-Objekte: CSSStyleSheet.media (bzw. StyleSheet.media), CSSMediaRule.media und CSSImportRule.media. Es spiegelt z. B. das media-Attribut von <link rel="stylesheet"> und <style> wider, außerdem die Bedingung einer @media- oder @import-Regel.

Die Schnittstelle hat folgende Mitglieder:

mediaText: Die gesamte Liste als kommagetrennter String. Du kannst den Wert lesen und setzen. Beim Setzen wird die Liste komplett ersetzt.
length: Die Anzahl der Media-Queries (nur lesbar).
item(index): Gibt die Media-Query an Position index als String zurück, bei ungültigem Index null. Alternativ geht auch der Indexzugriff list[index].
appendMedium(medium): Hängt eine Media-Query an. Ist sie schon vorhanden, passiert nichts.
deleteMedium(medium): Entfernt eine Media-Query. Ist sie nicht vorhanden, wird eine NotFoundError-DOMException ausgelöst.
toString(): Gibt denselben Wert wie mediaText zurück.

Typische Einsatzfälle: Stylesheets zur Laufzeit nur für bestimmte Medien aktivieren (z. B. Druckansicht umschalten), die Bedingungen von @media-Regeln auslesen oder verändern und Werkzeuge wie Style-Inspektoren oder Tests für responsive Layouts bauen. Ob eine Query gerade zutrifft, sagt dir MediaList nicht. Dafür gibt es window.matchMedia().

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Für `item(index)`: Position der Media-Query, beginnend bei 0.
$medium Pflicht	string		Für `appendMedium()` und `deleteMedium()`: eine einzelne Media-Query als String, z. B. `"print"` oder `"(max-width: 600px)"`.

Rückgabewert

Typ

MediaList

Beschreibung

Eine Live-Liste der Media-Queries. item() gibt string | null zurück, appendMedium() und deleteMedium() geben void zurück.

Beispiele

MediaList eines Stylesheets auslesen

// HTML: <link rel="stylesheet" href="print.css" media="print, (max-width: 600px)">
const sheet = [...document.styleSheets].find((s) => s.href?.endsWith('print.css'));
const list = sheet.media; // MediaList

console.log(list.length);
console.log(list.mediaText);
for (let i = 0; i < list.length; i++) {
  console.log(i, list.item(i));
}

2 print, (max-width: 600px) 0 print 1 (max-width: 600px)

Druck-Stylesheet für die Bildschirmvorschau einschalten

const printSheet = document.querySelector('link[href$="print.css"]').sheet;

const togglePreview = (on) => {
  if (on) {
    printSheet.media.appendMedium('screen');
  } else if ([...printSheet.media].includes('screen')) {
    printSheet.media.deleteMedium('screen'); // wirft einen Fehler, wenn nicht vorhanden
  }
  console.log(printSheet.media.mediaText);
};

togglePreview(true);
togglePreview(false);

print, screen print

Breakpoint einer @media-Regel zur Laufzeit ändern

const style = document.createElement('style');
style.textContent = '@media (max-width: 600px) { body { background: tomato; } }';
document.head.append(style);

const rule = [...style.sheet.cssRules].find((r) => r instanceof CSSMediaRule);
console.log(rule.media.mediaText);

// Komplette Bedingung ersetzen
rule.media.mediaText = '(max-width: 800px)';
console.log(rule.conditionText);

(max-width: 600px) (max-width: 800px)

// Wichtig · Fallstricke

deleteMedium() wirft einen Fehler: Ist das Medium nicht in der Liste, wird eine NotFoundError-DOMException ausgelöst. Prüfe vorher, ob es vorhanden ist, oder fange den Fehler mit try/catch ab.
Serialisierung: Browser normalisieren die Queries. Leerzeichen, Groß- und Kleinschreibung und die Schreibweise können sich im Vergleich zum Quelltext ändern, z. B. (MAX-WIDTH:600px) → (max-width: 600px). Vergleiche deshalb nicht blind Strings aus dem Quelltext mit mediaText.
Ungültige Queries werden nicht verworfen, sondern als not all gespeichert.
Cross-Origin-Stylesheets: Auf cssRules fremder Stylesheets ohne CORS-Freigabe kannst du nicht zugreifen (SecurityError). sheet.media selbst ist aber lesbar.
Kein Zutreffen-Test: MediaList beschreibt nur die Bedingungen. Ob sie aktuell erfüllt sind, prüfst du mit matchMedia() und MediaQueryList.
Browser-Unterstützung: Wird von allen modernen Browsern unterstützt. Die Liste ist iterierbar, du kannst sie also mit for...of oder dem Spread-Operator durchlaufen.

Siehe auch

CSSStyleSheet StyleSheet CSSMediaRule CSSImportRule MediaQueryList Window.matchMedia()