Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

MediaQueryList : la propriété matches et l’évènement change

Lisez `matches` pour connaître le résultat actuel d’une requête média CSS et écoutez `change` pour réagir uniquement lorsque ce résultat change.

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

Syntaxe

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) prend une requête média CSS sous forme de chaîne et renvoie un nouvel objet MediaQueryList. Sa propriété booléenne matches, en lecture seule, vaut true si le document satisfait actuellement la requête, et false sinon. La requête (max-width: 600px) inclut une zone d’affichage de largeur égale à 600 pixels CSS.

Enregistrez la fonction avec mql.addEventListener("change", onChange). Le navigateur déclenche change sur cet objet MediaQueryList lorsque le résultat passe de false à true ou inversement, pas à chaque redimensionnement. La fonction reçoit un MediaQueryListEvent : event.matches contient le nouveau résultat et event.media le texte de la requête.

Enregistrer la fonction ne l’appelle pas immédiatement. Lisez mql.matches pour initialiser l’état, puis utilisez event.matches pour les changements suivants. Pour arrêter l’écoute, appelez mql.removeEventListener("change", onChange) sur le même objet avec la même fonction.

Il s’agit d’une API de navigateur, qui ne fait pas partie d’ECMAScript 2024. Ne présumez pas qu’elle existe en dehors du navigateur. addListener() et removeListener() sont d’anciennes méthodes conservées pour la compatibilité ; dans du nouveau code, préférez addEventListener() et removeEventListener().

Exemples

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

Résultat

initial: false
change: true
change: false

Ouvrez `about:blank` dans le navigateur et exécutez le code dans sa console. Le code fait passer la largeur de la zone d’affichage de l’`iframe` de 800 à 600, puis à 500, puis à nouveau à 800 pixels CSS. Le passage à 500 n’ajoute aucune ligne. Après l’arrêt de l’écoute, un nouveau passage à 600 n’ajoute pas non plus de ligne.

Leçons associées

  • JavaScript · Leçon 29 · Avancé · Version : 4
  • JavaScript · Leçon 34 · Avancé · Version : 4
  • JavaScript · Leçon 35 · Avancé · Version : 4
  • JavaScript · Leçon 36 · Avancé · Version : 4
  • JavaScript · Leçon 37 · Avancé · Version : 4
  • JavaScript · Leçon 39 · Avancé · Version : 4
  • JavaScript · Leçon 45 · Avancé · Version : 4
  • JavaScript · Leçon 27 · Intermédiaire · Version : 3
  • JavaScript · Leçon 28 · Intermédiaire · Version : 3
  • JavaScript · Leçon 29 · Intermédiaire · Version : 3

Sources