CKTIS / JavaScript
MediaQueryList: huidig resultaat en het change-event
Met MediaQueryList kun je het resultaat van een mediaquery bekijken en op veranderingen reageren. De eigenschap matches geeft de huidige booleaanse waarde; het change-event meldt overgangen tussen wel en niet overeenkomen.
Versie: 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) retourneert een MediaQueryList-object dat het resultaat van een mediaquery voor het document beschrijft. MediaQueryList.matches is alleen-lezen: true betekent dat de query overeenkomt en false dat dit niet zo is. Het is een eigenschap, geen methode: lees mql.matches, niet mql.matches().
MediaQueryList.change verwijst naar het event dat je met mql.addEventListener("change", handler) observeert, niet naar een methode met de naam mql.change(). Het wordt geactiveerd wanneer het queryresultaat wisselt tussen true en false, niet bij elke wijziging van de afmetingen. Bij (min-width: 600px) komt een viewportbreedte van precies 600 CSS-pixels overeen; een verandering van 800 naar 900 wijzigt het resultaat niet. Het aan de handler doorgegeven MediaQueryListEvent bevat het nieuwe resultaat in event.matches.
Het registreren van een listener voert de eerste update niet uit. Lees daarom ook mql.matches, zoals in het voorbeeld. Stop bij het verwijderen van een component met luisteren via removeEventListener("change", handler) en geef daarbij dezelfde functiereferentie door. In het voorbeeld roept de handler voor het change-event rechtstreeks query.removeEventListener('change', handleChange) aan als event.matches de waarde true heeft.
Dit is een browser-API uit CSSOM View, geen functie van een bepaalde ECMAScript-editie; de Node-versie van de repository toont niet aan dat deze API wordt ondersteund. MDN vermeldt dat matches sinds juli 2015 en change sinds september 2020 breed beschikbaar zijn. Controleer de compatibiliteit met oudere browsers afzonderlijk; het verouderde addListener() wordt niet aanbevolen voor nieuwe code.
Voorbeelden
<!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>Resultaat
wide narrow wide
De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.