CKTIS / JavaScript
MediaQueryList: aktuelles Ergebnis und das change-Ereignis
Mit MediaQueryList lässt sich das Ergebnis einer Media-Abfrage prüfen und auf Änderungen reagieren. Die Eigenschaft matches liefert den aktuellen booleschen Wert; das change-Ereignis meldet den Wechsel zwischen zutreffend und nicht zutreffend.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
const mql = window.matchMedia("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);window.matchMedia(query) gibt ein MediaQueryList-Objekt zurück, das das Ergebnis einer Media-Abfrage für das Dokument beschreibt. MediaQueryList.matches ist schreibgeschützt: true bedeutet, dass die Abfrage zutrifft, und false, dass sie nicht zutrifft. Es handelt sich um eine Eigenschaft, nicht um eine Methode: Lies mql.matches, nicht mql.matches().
MediaQueryList.change bezeichnet das Ereignis, das über mql.addEventListener("change", handler) beobachtet wird, und keine Methode namens mql.change(). Es wird ausgelöst, wenn das Abfrageergebnis zwischen true und false wechselt, nicht bei jeder Größenänderung. Bei (min-width: 600px) trifft eine Viewport-Breite von genau 600 CSS-Pixeln zu; ein Wechsel von 800 auf 900 ändert das Ergebnis nicht. Das an den Handler übergebene MediaQueryListEvent stellt das neue Ergebnis über event.matches bereit.
Das Registrieren eines Event-Listeners führt die anfängliche Aktualisierung nicht aus. Lies daher auch mql.matches, wie im Beispiel. Beim Entfernen einer Komponente beendest du das Lauschen mit removeEventListener("change", handler) und übergibst dabei dieselbe Funktionsreferenz. Im Beispiel ruft der Handler für change direkt query.removeEventListener('change', handleChange) auf, wenn event.matches den Wert true hat.
Dies ist eine Browser-API aus CSSOM View und keine Funktion einer bestimmten ECMAScript-Ausgabe; die Node-Version des Repositorys belegt keine Unterstützung. MDN kennzeichnet matches seit Juli 2015 und change seit September 2020 als weithin verfügbar. Prüfe die Kompatibilität älterer Browser gesondert; das veraltete addListener() wird für neuen Code nicht empfohlen.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>MediaQueryList matches and change</title>
</head>
<body>
<script>
const frame = document.createElement('iframe');
frame.title = 'Media query test viewport';
frame.style.cssText = 'display:block; width:320px; height:60px; border:0';
frame.srcdoc = '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Test viewport</title></head><body></body></html>';
frame.addEventListener('load', () => {
const query = frame.contentWindow.matchMedia('(min-width: 250px)');
const report = matches => console.log(matches ? 'wide' : 'narrow');
function handleChange(event) {
report(event.matches);
if (event.matches) {
query.removeEventListener('change', handleChange);
} else {
frame.style.width = '320px';
}
}
query.addEventListener('change', handleChange);
report(query.matches);
frame.style.width = '120px';
}, { once: true });
document.body.append(frame);
</script>
</body>
</html>Ergebnis
wide narrow wide
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.