CKTIS / JavaScript
MediaQueryList: risultato corrente ed evento change
MediaQueryList consente di controllare il risultato di una media query e di reagire quando cambia. La proprietà matches fornisce il valore booleano corrente, mentre l’evento change segnala il passaggio tra corrispondenza e mancata corrispondenza.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
const mql = window.matchMedia("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);window.matchMedia(query) restituisce un oggetto MediaQueryList che descrive il risultato di una media query per il documento. MediaQueryList.matches è di sola lettura: true indica una corrispondenza, mentre false indica che non c’è corrispondenza. È una proprietà, non un metodo: leggi mql.matches, non mql.matches().
MediaQueryList.change indica l’evento osservato tramite mql.addEventListener("change", handler), non un metodo chiamato mql.change(). Si attiva quando il risultato della query passa da true a false o viceversa, non a ogni ridimensionamento. Per (min-width: 600px), una larghezza dell’area di visualizzazione di esattamente 600 pixel CSS soddisfa la condizione; passare da 800 a 900 non cambia il risultato. L’oggetto MediaQueryListEvent passato alla funzione di gestione espone il nuovo risultato come event.matches.
La registrazione di un listener non esegue l’aggiornamento iniziale. Leggi anche mql.matches, come fa l’esempio. Quando rimuovi un componente, interrompi l’ascolto con removeEventListener("change", handler), passando lo stesso riferimento alla funzione. Nell’esempio, la funzione che gestisce l’evento change chiama direttamente query.removeEventListener('change', handleChange) se event.matches vale true.
Questa è un’API del browser appartenente a CSSOM View, non una funzionalità di una specifica edizione di ECMAScript; la versione di Node del repository non ne dimostra il supporto. MDN indica che matches è ampiamente disponibile da luglio 2015 e change da settembre 2020. Verifica separatamente la compatibilità con i browser più vecchi; il metodo deprecato addListener() non è consigliato nel nuovo codice.
Esempi
<!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>Risultato
wide narrow wide
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.