Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Leer y observar la relación de píxeles con `matchMedia()`

Lee cuántos píxeles del dispositivo corresponden a un píxel CSS y detecta cambios en esa relación mediante una consulta de resolución.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

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 es una propiedad de solo lectura. Indica el número de píxeles del dispositivo por píxel CSS, que puede ser fraccionario. Cambiar el zoom de página del navegador o mover la ventana a una pantalla con otra escala puede modificar ese valor. El zoom con gesto de pellizco no lo modifica.

window.matchMedia() recibe una consulta de medios CSS como cadena y devuelve un nuevo objeto MediaQueryList. matches indica el resultado actual. El objeto emite change solo cuando ese booleano cambia. (min-resolution: 2dppx) comprueba si hay al menos dos píxeles del dispositivo por píxel CSS; pasar de 2 a 3 no cruza el umbral.

Para seguir los cambios del DPR, sustituye … por el valor actual en la consulta exacta (resolution: …dppx). Al recibir change, quita el listener del objeto anterior, lee el nuevo DPR y registra el listener en una consulta nueva. Si la consulta exacta no coincide al principio, no des por hecho que el próximo cambio de DPR disparará el evento. Retira el listener activo cuando ya no lo necesites.

Estas API pertenecen al Window del navegador, no a ECMAScript 2024 ni al ámbito global de un worker. Comprueba la compatibilidad en los navegadores de destino; addListener() y removeListener() son métodos obsoletos que se conservan por compatibilidad.

Ejemplos

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

Resultado

DPR: 1
DPR: 2

En la consola del navegador, la primera línea aparece de inmediato; las siguientes, tras los cambios detectados. Los valores reales en el navegador pueden diferir de los mostrados. Llama a `stopDprWatch()` para dejar de observar. En Node.js, un objeto de prueba simula un cambio del DPR de 1 a 2 y la observación se detiene antes del cambio simulado a 3.

Lecciones relacionadas

  • JavaScript · Lección 34 · Avanzado · Versión: 4

Fuentes