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

CKTIS / JavaScript

MediaQueryList: a propriedade matches e o evento change

Lê `matches` para saber se uma consulta de multimédia CSS é satisfeita e escuta `change` para reagir apenas quando o resultado muda.

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

Sintaxe

const mql = window.matchMedia(mediaQueryString);

function onChange(event) {
  update(event.matches);
}

mql.addEventListener("change", onChange);
update(mql.matches);

// When observation is no longer needed:
mql.removeEventListener("change", onChange);

window.matchMedia(mediaQueryString) recebe uma consulta de multimédia CSS como cadeia de caracteres e devolve um novo objeto MediaQueryList. A sua propriedade booleana só de leitura matches é true se o documento satisfizer a consulta naquele momento e false caso contrário. A consulta (max-width: 600px) inclui uma área de visualização com exatamente 600 píxeis CSS de largura.

Regista a função com mql.addEventListener("change", onChange). O navegador dispara change nesse objeto MediaQueryList quando o resultado passa de false para true ou vice-versa, não sempre que as dimensões mudam. A função recebe um MediaQueryListEvent: event.matches contém o novo resultado e event.media contém o texto da consulta.

Registar a função não a chama de imediato. Lê mql.matches para inicializar o estado e usa event.matches para as alterações seguintes. Quando já não precisares de atualizações, chama mql.removeEventListener("change", onChange) no mesmo objeto e com a mesma função.

Esta é uma API do navegador, não faz parte do ECMAScript 2024. Não assumas que existe fora do navegador. addListener() e removeListener() são métodos antigos mantidos por compatibilidade; em código novo, prefere addEventListener() e removeEventListener().

Exemplos

(async () => {
  const frame = document.createElement("iframe");
  frame.style.cssText = "display: block; width: 800px; height: 80px; border: 0";
  frame.srcdoc = "<!doctype html><title>Media query demo</title>";

  const loaded = new Promise((resolve) => {
    frame.addEventListener("load", resolve, { once: true });
  });
  document.body.append(frame);
  await loaded;

  const view = frame.contentWindow;
  // Give the browser time to render and report media query changes.
  const afterRendering = () => new Promise((resolve) => {
    view.requestAnimationFrame(() => view.requestAnimationFrame(resolve));
  });
  await afterRendering();

  const mql = view.matchMedia("(max-width: 600px)");
  const onChange = (event) => console.log(`change: ${event.matches}`);

  mql.addEventListener("change", onChange);
  console.log(`initial: ${mql.matches}`);

  for (const width of [600, 500, 800]) {
    frame.style.width = `${width}px`;
    await afterRendering();
  }

  mql.removeEventListener("change", onChange);
  frame.style.width = "600px";
  await afterRendering();
  frame.remove();
})();

Resultado

initial: false
change: true
change: false

Abre `about:blank` no navegador e executa o código na consola. O código altera a largura da área de visualização do `iframe` de 800 para 600, depois para 500 e novamente para 800 píxeis CSS. A passagem para 500 não acrescenta nenhuma linha. Depois de o código deixar de escutar o evento, a nova passagem para 600 também não acrescenta nenhuma linha.

Lições relacionadas

  • JavaScript · Lição 29 · Avançado · Versão: 4
  • JavaScript · Lição 34 · Avançado · Versão: 4
  • JavaScript · Lição 35 · Avançado · Versão: 4
  • JavaScript · Lição 36 · Avançado · Versão: 4
  • JavaScript · Lição 37 · Avançado · Versão: 4
  • JavaScript · Lição 39 · Avançado · Versão: 4
  • JavaScript · Lição 45 · Avançado · Versão: 4
  • JavaScript · Lição 27 · Intermédio · Versão: 3
  • JavaScript · Lição 28 · Intermédio · Versão: 3
  • JavaScript · Lição 29 · Intermédio · Versão: 3

Fontes