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

CKTIS / JavaScript

Window.matchMedia e MediaQueryList.matches

Verifica em JavaScript se uma consulta de multimédia CSS é satisfeita e reage apenas quando o resultado muda.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const mediaQueryList = window.matchMedia(mediaQueryString);
const matchesNow = mediaQueryList.matches;

window.matchMedia(query) recebe uma consulta de multimédia CSS como cadeia de caracteres e devolve um novo objeto MediaQueryList em cada chamada, não um booleano. Passa só a consulta, sem @media nem um bloco de regras. Coloca entre parênteses as condições sobre características do meio: (max-width: 600px) verifica se a área de visualização tem, no máximo, 600 píxeis CSS de largura, incluindo o limite.

Lê list.matches sem parênteses. É uma propriedade booleana só de leitura: devolve true se a lista de consultas de multimédia estiver vazia ou se o documento satisfizer, nesse momento, pelo menos uma consulta da lista separada por vírgulas, e false caso contrário. false não indica um erro de sintaxe. Voltar a ler a propriedade no mesmo objeto dá o resultado atual; um booleano guardado antes não se atualiza sozinho.

Se precisares do estado inicial, lê list.matches e usa depois list.addEventListener("change", handler) para acompanhar alterações. O evento é disparado quando o resultado passa de true para false ou vice-versa, não a cada alteração de tamanho. Lê o novo resultado em event.matches. Quando já não precisares de notificações, chama list.removeEventListener("change", handler) com a mesma função.

Esta API pertence ao navegador e não faz parte de ECMAScript 2024. Não partas do princípio de que está disponível fora de uma janela do navegador. Se só precisares de alterar estilos, usa @media em CSS: matchMedia() não aplica estilos por si só.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>matchMedia example</title>
</head>
<body>
  <script>
    console.log(window.matchMedia("all").matches);
    console.log(window.matchMedia("not all").matches);
  </script>
</body>
</html>

Resultado

true
false

Abre o ficheiro HTML num navegador e consulta a consola. `all` corresponde a todos os meios e `not all` a nenhum. O resultado é `true` seguido de `false`, independentemente da largura da área de visualização.

Lições relacionadas

  • JavaScript · Lição 3 · Avançado · Versão: 4
  • JavaScript · Lição 6 · Avançado · Versão: 4
  • JavaScript · Lição 7 · Avançado · Versão: 4
  • JavaScript · Lição 19 · Avançado · Versão: 4
  • JavaScript · Lição 41 · Intermédio · Versão: 3
  • JavaScript · Lição 42 · Intermédio · Versão: 3
  • JavaScript · Lição 43 · Intermédio · Versão: 3

Fontes