MediaQueryListEvent.media — Eigenschaft · JavaScript-Referenz

Signatur

MediaQueryListEvent.media

Beschreibung

Die Eigenschaft media eines MediaQueryListEvent enthält die Media-Query als serialisierten String, z. B. "(max-width: 600px)". Das Event wird am MediaQueryList-Objekt ausgelöst, das von window.matchMedia() zurückgegeben wird, sobald sich der Wert von matches ändert, also wenn die Abfrage neu zutrifft oder nicht mehr zutrifft.

Nützlich ist media vor allem dann, wenn ein einziger Handler für mehrere Media-Queries zuständig ist. Anhand von event.media lässt sich feststellen, welche Abfrage das Event ausgelöst hat, zum Beispiel ein Breakpoint, prefers-color-scheme oder prefers-reduced-motion. Zusammen mit event.matches weiß man dann, welche Abfrage betroffen ist und ob sie jetzt zutrifft.

Der Wert ist die normalisierte Form der Abfrage, die der Browser erzeugt. Er kann sich deshalb in Leerzeichen, Groß-/Kleinschreibung oder Klammern von dem String unterscheiden, den man an matchMedia() übergeben hat. Für Vergleiche sollte man darum mql.media verwenden und nicht den ursprünglichen Literal-String.

Rückgabewert

Typ

string

Beschreibung

Die serialisierte Media-Query, deren Status sich geändert hat, z. B. "(prefers-color-scheme: dark)". Der Wert ist schreibgeschützt.

Beispiele

Einfacher Breakpoint-Listener

const mql = window.matchMedia('(max-width: 600px)');

mql.addEventListener('change', (event) => {
  console.log(`Query: ${event.media}, trifft zu: ${event.matches}`);
});

// Fenster auf unter 600px verkleinern ...

Query: (max-width: 600px), trifft zu: true

Ein Handler für mehrere Media-Queries

const queries = {
  dark: window.matchMedia('(prefers-color-scheme: dark)'),
  reducedMotion: window.matchMedia('(prefers-reduced-motion: reduce)'),
  mobile: window.matchMedia('(max-width: 768px)')
};

const handleChange = (event) => {
  // Normalisierten String über mql.media vergleichen, nicht über das Literal
  const [name] = Object.entries(queries)
    .find(([, mql]) => mql.media === event.media) ?? ['unbekannt'];
  document.documentElement.classList.toggle(`is-${name}`, event.matches);
  console.log(`${name} (${event.media}) -> ${event.matches}`);
};

for (const mql of Object.values(queries)) {
  mql.addEventListener('change', handleChange);
}

dark ((prefers-color-scheme: dark)) -> true

Event manuell erzeugen (z. B. für Tests)

const event = new MediaQueryListEvent('change', {
  media: '(orientation: landscape)',
  matches: true
});

console.log(event.media);
console.log(event.matches);

(orientation: landscape) true

// Wichtig · Fallstricke

Normalisierung: event.media enthält die serialisierte Form. Aus matchMedia('(MAX-WIDTH:600px)') kann zum Beispiel "(max-width: 600px)" werden. Vergleiche mit mql.media sind deshalb robuster als Vergleiche mit eigenen Literal-Strings.
Ungültige Abfragen werden zu "not all" serialisiert. Sie lösen nie ein change-Event aus.
Schreibgeschützt: Eine Zuweisung an event.media hat keine Wirkung (im Strict Mode wird ein TypeError ausgelöst).
Kompatibilität: Ältere Safari-Versionen (vor 14) unterstützen addEventListener an MediaQueryList nicht. Dort muss man das veraltete mql.addListener(handler) als Fallback verwenden. Die Eigenschaft media ist trotzdem verfügbar.
Das Event feuert nur bei einer Änderung. Den Anfangszustand muss man einmal selbst über mql.matches abfragen.

Siehe auch

MediaEncryptedEvent.initData MediaQueryListEvent.matches MediaQueryList.media MediaQueryList.matches HIDInputReportEvent.data