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

CKTIS / JavaScript

Lire et suivre le ratio de pixels avec `matchMedia()`

Lisez le nombre de pixels de l’appareil par pixel CSS et détectez les variations de ce ratio grâce à une requête média sur la résolution.

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

Syntaxe

window.devicePixelRatio // read-only number
window.matchMedia(mediaQueryString) // returns a new MediaQueryList
window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`)
window.matchMedia('(min-resolution: 2dppx)').matches // boolean
query.addEventListener('change', listener)
query.removeEventListener('change', listener)

window.devicePixelRatio est une propriété en lecture seule. Elle indique le nombre de pixels de l’appareil par pixel CSS ; cette valeur peut être fractionnaire. Le zoom de page du navigateur ou le déplacement de la fenêtre vers un écran dont la mise à l’échelle diffère peut modifier ce ratio. Le zoom par pincement ne le modifie pas.

window.matchMedia() reçoit une requête média CSS sous forme de chaîne et renvoie un nouvel objet MediaQueryList. matches donne le résultat actuel. L’objet émet l’événement change seulement si ce booléen change. (min-resolution: 2dppx) teste la présence d’au moins deux pixels de l’appareil par pixel CSS ; passer de 2 à 3 ne franchit pas ce seuil.

Pour suivre le DPR, insérez sa valeur actuelle à la place de … dans la requête exacte (resolution: …dppx). Lors de change, retirez l’écouteur de l’ancien objet, lisez le nouveau DPR et rattachez l’écouteur à une nouvelle requête. Si la requête exacte ne correspond pas au départ, ne supposez pas que le prochain changement de DPR déclenchera l’événement. Retirez l’écouteur actif quand il n’est plus utile.

Ces API appartiennent au Window du navigateur, et non à ECMAScript 2024 ni à la portée globale d’un worker. Vérifiez leur prise en charge dans les navigateurs cibles ; addListener() et removeListener() sont des méthodes obsolètes conservées pour la compatibilité.

Exemples

function watchDpr(viewport) {
  let query;

  function stop() {
    query?.removeEventListener('change', update);
    query = undefined;
  }

  function update() {
    stop();
    const dpr = viewport.devicePixelRatio;
    query = viewport.matchMedia(`(resolution: ${dpr}dppx)`);
    query.addEventListener('change', update);
    console.log(`DPR: ${dpr}`);
  }

  update();
  return stop;
}

// Node.js test fixture: models only exact-resolution media queries.
function createTestWindow(dpr) {
  const queries = [];

  return {
    get devicePixelRatio() { return dpr; },

    matchMedia(media) {
      const [, value] = /^\(resolution: (.+)dppx\)$/.exec(media);
      const resolution = Number(value);
      const query = new EventTarget();
      Object.defineProperty(query, 'matches', { get: () => dpr === resolution });
      queries.push(query);
      return query;
    },

    setDpr(nextDpr) {
      // Snapshot the queries before listeners can create new ones.
      const previous = queries.map(query => [query, query.matches]);
      dpr = nextDpr;
      for (const [query, matched] of previous) {
        if (query.matches !== matched) {
          query.dispatchEvent(new Event('change'));
        }
      }
    },
  };
}

const stopDprWatch = (() => {
  if (typeof window !== 'undefined') return watchDpr(window);

  const testWindow = createTestWindow(1);
  const stop = watchDpr(testWindow);
  testWindow.setDpr(2);
  stop();
  testWindow.setDpr(3); // The watcher should not log after cleanup.
  return stop;
})();

Résultat

DPR: 1
DPR: 2

Dans la console du navigateur, la première ligne s’affiche immédiatement, les suivantes après les changements détectés. Les valeurs réelles dans le navigateur peuvent différer de celles affichées dans l’exemple. Appelez `stopDprWatch()` pour arrêter le suivi. Dans Node.js, un objet de test simule un passage du DPR de 1 à 2, puis le suivi s’arrête avant le passage simulé à 3.

Leçons associées

  • JavaScript · Leçon 34 · Avancé · Version : 4

Sources