new MediaQueryListEvent() — Methode · JavaScript-Referenz

Signatur

new MediaQueryListEvent(type, options)

Beschreibung

Der Konstruktor MediaQueryListEvent() erzeugt ein Ereignisobjekt vom Typ MediaQueryListEvent. Solche Ereignisse löst der Browser normalerweise selbst auf einem MediaQueryList-Objekt aus (Ereignistyp "change"), wenn eine mit window.matchMedia() überwachte Media Query ihren Zustand ändert, z. B. beim Wechsel in den Dunkelmodus oder wenn ein Breakpoint über- bzw. unterschritten wird.

Selbst aufrufen muss man den Konstruktor nur selten. Nützlich ist er vor allem in Unit-Tests, wenn man Handler für Media-Query-Änderungen prüfen will, ohne das Browserfenster zu verändern, und beim Weiterleiten oder Simulieren von Änderungen an eigene EventTarget-Objekte oder Komponenten.

Über das Optionsobjekt legt man die schreibgeschützten Eigenschaften media (die Media Query als String) und matches (ob sie aktuell zutrifft) fest. Dazu kommen die üblichen Optionen aus EventInit wie bubbles und cancelable. Ein von Hand erzeugtes Ereignis ändert nicht den echten Zustand der Media Query. Es ist nur ein Datenträger für Listener.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignistyps. Für Media-Query-Änderungen ist das in der Regel `"change"`.
$options	object	{}	Optionales Initialisierungsobjekt (`MediaQueryListEventInit`, erweitert `EventInit`): `media` (`string`, Standard `""`): die serialisierte Media Query, z. B. `"(prefers-color-scheme: dark)"`. `matches` (`boolean`, Standard `false`): ob das Dokument der Media Query entspricht. `bubbles`, `cancelable`, `composed` (`boolean`, Standard `false`): allgemeine Event-Optionen.

Rückgabewert

Typ

MediaQueryListEvent

Beschreibung

Ein neues MediaQueryListEvent-Objekt mit den übergebenen Werten für type, media und matches.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const event = new MediaQueryListEvent('change', {
  media: '(prefers-color-scheme: dark)',
  matches: true
});

console.log(event.type);    // Ereignistyp
console.log(event.media);   // Media Query
console.log(event.matches); // Trifft zu?
console.log(event instanceof Event);

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

Theme-Handler im Test mit simulierter Änderung prüfen

// Handler, der normalerweise an matchMedia hängt
const applyTheme = (e) => {
  document.documentElement.dataset.theme = e.matches ? 'dark' : 'light';
};

const mql = window.matchMedia('(prefers-color-scheme: dark)');
mql.addEventListener('change', applyTheme);

// Test: Wechsel in den Dunkelmodus simulieren
applyTheme(new MediaQueryListEvent('change', {
  media: mql.media,
  matches: true
}));

console.log(document.documentElement.dataset.theme);

dark

Breakpoint-Änderung an eigenes EventTarget weiterleiten

const layoutBus = new EventTarget();

layoutBus.addEventListener('change', (e) => {
  console.log(`${e.media} → ${e.matches ? 'mobil' : 'desktop'}`);
});

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

// Echte Änderungen weiterreichen
mobile.addEventListener('change', (e) => {
  layoutBus.dispatchEvent(new MediaQueryListEvent('change', {
    media: e.media,
    matches: e.matches
  }));
});

// Anfangszustand einmalig melden
layoutBus.dispatchEvent(new MediaQueryListEvent('change', {
  media: mobile.media,
  matches: mobile.matches
}));

(max-width: 600px) → desktop // bei breitem Fenster

// Wichtig · Fallstricke

Ein selbst erzeugtes Ereignis hat isTrusted === false und ändert nicht den Wert von MediaQueryList.matches. Es informiert nur die Listener.
Ruft man dispatchEvent() mit so einem Ereignis direkt auf einem echten MediaQueryList-Objekt auf, werden dessen Listener ausgelöst. mql.matches zeigt danach aber weiterhin den echten Zustand. Das kann Tests verwirren, die beides prüfen.
Der Wert von media wird nicht geprüft oder normalisiert. Beliebige Strings sind erlaubt.
Kompatibilität: In allen modernen Browsern verfügbar (Chrome/Edge 39+, Firefox 55+, Safari 14+). Ältere Safari-Versionen kennen den Konstruktor nicht. In Node.js und in Test-Umgebungen wie jsdom fehlt er je nach Version. Dort ggf. auf new Event('change') mit zusätzlich gesetzten Eigenschaften ausweichen.
Das veraltete MediaQueryList.addListener() bekommt dasselbe Ereignisobjekt. Besser ist addEventListener('change', …).

Siehe auch

new DeviceMotionEvent() new MediaEncryptedEvent() new MediaStreamEvent() new InterestEvent() new MediaKeyMessageEvent()