Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

window.matchMedia — testar media queries

window.matchMedia testa uma media query CSS a partir de JavaScript. Devolve uma MediaQueryList com o resultado atual em matches e permite observar alterações na correspondência da consulta.

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(query);
mql.matches;
mql.media;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);

window.matchMedia(query) cria uma nova MediaQueryList, não um valor booleano. Lê matches para obter o resultado atual; media contém a consulta serializada.

Passa uma consulta CSS como "(min-width: 768px)", sem @media. A característica de média width refere-se à largura da área de visualização (viewport) nos meios contínuos e à largura da caixa de página (page box) nos meios paginados, como a impressão. A unidade px significa píxeis CSS. Esta consulta não se limita ao tipo de média screen. O método testa uma condição; não aplica estilos por si só.

Esta é uma API de navegador de CSSOM View, não uma funcionalidade de ECMAScript. Antes de chamares window.matchMedia(query), verifica typeof window !== "undefined" && typeof window.matchMedia === "function"; o Node 24, por si só, não comprova que a API seja suportada. Esta verificação não confirma que o objeto devolvido tenha os métodos para registar e remover ouvintes de eventos.

Lê o resultado inicial em mql.matches, em que mql é a MediaQueryList devolvida. Regista a função de tratamento com mql.addEventListener("change", handler) apenas se typeof mql.addEventListener === "function" && typeof mql.removeEventListener === "function". Se faltar algum dos métodos, não registes a função; podes continuar a ler matches. O evento assinala uma alteração do resultado, não cada redimensionamento; event.matches fornece o novo resultado. Se registaste a função, na fase de limpeza chama mql.removeEventListener("change", handler) com a mesma função.

O exemplo usa all e a sua negação not all, pelo que o resultado é independente do tamanho da janela.

Exemplos

const always = window.matchMedia("all");
const never = window.matchMedia("not all");
console.log(always.matches);
console.log(never.matches);

Resultado

true
false

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.

Fontes