CKTIS / JavaScript
MediaQueryList : résultat actuel et événement change
MediaQueryList permet de consulter le résultat d’une requête média et de réagir lorsqu’il change. La propriété matches fournit la valeur booléenne actuelle, tandis que l’événement change signale le passage entre une correspondance et une absence de correspondance.
Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
const mql = window.matchMedia("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);window.matchMedia(query) renvoie un objet MediaQueryList qui décrit le résultat d’une requête média pour le document. MediaQueryList.matches est en lecture seule : true indique une correspondance et false une absence de correspondance. C’est une propriété, pas une méthode : lisez mql.matches, et non mql.matches().
MediaQueryList.change désigne l’événement observé avec mql.addEventListener("change", handler), et non une méthode appelée mql.change(). Il se déclenche lorsque le résultat de la requête passe de true à false ou inversement, pas à chaque redimensionnement. Pour (min-width: 600px), une largeur de zone d’affichage exactement égale à 600 pixels CSS correspond ; passer de 800 à 900 ne change pas le résultat. L’objet MediaQueryListEvent transmis au gestionnaire expose le nouveau résultat avec event.matches.
L’ajout d’un écouteur ne réalise pas la mise à jour initiale. Lisez également mql.matches, comme dans l’exemple. Lors de la suppression d’un composant, arrêtez l’écoute avec removeEventListener("change", handler), en transmettant la même référence de fonction. Dans l’exemple, le gestionnaire de l’événement change appelle directement query.removeEventListener('change', handleChange) si event.matches vaut true.
Il s’agit d’une API de navigateur de CSSOM View, et non d’une fonctionnalité d’une édition particulière d’ECMAScript ; la version de Node du dépôt ne permet pas d’établir sa prise en charge. MDN indique que matches est largement disponible depuis juillet 2015 et change depuis septembre 2020. Vérifiez séparément la compatibilité avec les anciens navigateurs ; addListener(), désormais obsolète, n’est pas recommandé pour le nouveau code.
Exemples
<!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>Résultat
wide narrow wide
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.