CKTIS / JavaScript
MediaQueryList: resultado atual e o evento change
MediaQueryList permite consultar o resultado de uma consulta de media e reagir quando este muda. A propriedade matches fornece o valor booleano atual, enquanto o evento change assinala as transições entre correspondência e ausência de correspondência.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
const mql = window.matchMedia("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);window.matchMedia(query) devolve um objeto MediaQueryList que descreve o resultado de uma consulta de media para o documento. MediaQueryList.matches é só de leitura: true significa que há correspondência e false que não há. É uma propriedade, não um método: lê mql.matches, não mql.matches().
MediaQueryList.change designa o evento observado através de mql.addEventListener("change", handler), não um método chamado mql.change(). É acionado quando o resultado da consulta passa de true para false ou vice-versa, e não em cada redimensionamento. Para (min-width: 600px), uma largura da área de visualização exatamente igual a 600 píxeis CSS corresponde; passar de 800 para 900 não altera o resultado. O objeto MediaQueryListEvent passado ao gestor expõe o novo resultado como event.matches.
Registar um listener não executa a atualização inicial. Lê também mql.matches, como faz o exemplo. Ao remover um componente, deixa de escutar com removeEventListener("change", handler), passando a mesma referência da função. No exemplo, a função que trata o evento change chama diretamente query.removeEventListener('change', handleChange) se event.matches tiver o valor true.
Esta é uma API do navegador de CSSOM View, não uma funcionalidade de uma edição específica de ECMAScript; a versão de Node do repositório não comprova o seu suporte. MDN indica que matches está amplamente disponível desde julho de 2015 e change desde setembro de 2020. Verifica separadamente a compatibilidade com navegadores mais antigos; o método obsoleto addListener() não é recomendado para código novo.
Exemplos
<!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>Resultado
wide narrow wide
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.