Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

MediaQueryList: la proprietà matches e l’evento change

Leggi `matches` per sapere se una media query CSS è soddisfatta e ascolta `change` per reagire solo quando l’esito cambia.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

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) riceve una media query CSS sotto forma di stringa e restituisce un nuovo oggetto MediaQueryList. La sua proprietà booleana di sola lettura matches vale true se il documento soddisfa la query in quel momento, altrimenti vale false. La query (max-width: 600px) include una larghezza del viewport di esattamente 600 pixel CSS.

Registra la funzione con mql.addEventListener("change", onChange). Il browser genera l’evento change su quell’oggetto MediaQueryList quando il risultato passa da false a true o viceversa, non a ogni ridimensionamento. La funzione riceve un MediaQueryListEvent: event.matches contiene il nuovo risultato e event.media il testo della query.

Registrare la funzione non la invoca subito. Leggi mql.matches per inizializzare lo stato e usa event.matches per le variazioni successive. Quando non ti servono più aggiornamenti, chiama mql.removeEventListener("change", onChange) sullo stesso oggetto passando la stessa funzione.

Questa è un’API del browser e non fa parte di ECMAScript 2024. Non darne per scontata la disponibilità al di fuori del browser. addListener() e removeListener() sono metodi precedenti mantenuti per compatibilità; nel nuovo codice preferisci addEventListener() e removeEventListener().

Esempi

(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();
})();

Risultato

initial: false
change: true
change: false

Apri `about:blank` nel browser ed esegui il codice nella console. Il codice cambia la larghezza del viewport dell’`iframe` da 800 a 600, poi a 500 e di nuovo a 800 pixel CSS. Il passaggio a 500 non aggiunge alcuna riga. Dopo la rimozione del listener, neanche il ritorno a 600 aggiunge righe.

Lezioni correlate

  • JavaScript · Lezione 29 · Avanzato · Versione: 4
  • JavaScript · Lezione 34 · Avanzato · Versione: 4
  • JavaScript · Lezione 35 · Avanzato · Versione: 4
  • JavaScript · Lezione 36 · Avanzato · Versione: 4
  • JavaScript · Lezione 37 · Avanzato · Versione: 4
  • JavaScript · Lezione 39 · Avanzato · Versione: 4
  • JavaScript · Lezione 45 · Avanzato · Versione: 4
  • JavaScript · Lezione 27 · Intermedio · Versione: 3
  • JavaScript · Lezione 28 · Intermedio · Versione: 3
  • JavaScript · Lezione 29 · Intermedio · Versione: 3

Fonti