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

CKTIS / JavaScript

Ler e acompanhar a proporção de píxeis com `matchMedia()`

Lê o número de píxeis do dispositivo por píxel CSS e deteta alterações nessa proporção através de uma consulta de resolução.

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

Sintaxe

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 é uma propriedade só de leitura. Indica o número de píxeis do dispositivo por píxel CSS; o valor pode ser fracionário. O zoom da página no navegador ou a mudança da janela para um ecrã com outra escala pode alterar a proporção. O zoom por gesto de pinça não a altera.

window.matchMedia() recebe uma consulta multimédia CSS como cadeia de carateres e devolve um novo objeto MediaQueryList. matches indica o resultado atual. O objeto emite change apenas quando esse valor booleano muda. (min-resolution: 2dppx) verifica se há pelo menos dois píxeis do dispositivo por píxel CSS; passar de 2 para 3 não atravessa o limiar.

Para acompanhar alterações do DPR, substitui … pelo DPR atual na consulta exata (resolution: …dppx). Ao receber change, remove o listener do objeto anterior, lê o novo DPR e regista o listener numa nova consulta. Se a consulta exata não corresponder logo de início, não assumas que a próxima alteração de DPR vai disparar o evento. Remove o listener ativo quando já não for necessário.

Estas API pertencem ao Window do navegador, não ao ECMAScript 2024 nem ao âmbito global de um worker. Verifica o suporte nos navegadores-alvo; addListener() e removeListener() são métodos descontinuados, mantidos por compatibilidade.

Exemplos

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

Na consola do navegador, a primeira linha aparece de imediato; as seguintes surgem após alterações detetadas. Os valores reais no navegador podem diferir dos apresentados. Chama `stopDprWatch()` para parar a monitorização. Em Node.js, um objeto de teste simula uma alteração do DPR de 1 para 2 e a monitorização termina antes da alteração simulada para 3.

Lições relacionadas

  • JavaScript · Lição 34 · Avançado · Versão: 4

Fontes