WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Gerätepixelverhältnis mit `matchMedia()` lesen und beobachten

Ermittle die Anzahl der Gerätepixel pro CSS-Pixel und erkenne Änderungen dieses Verhältnisses mit einer Medienabfrage zur Auflösung.

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

Syntax

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 ist eine schreibgeschützte Eigenschaft. Sie gibt an, wie viele Gerätepixel auf ein CSS-Pixel kommen; der Wert muss nicht ganzzahlig sein. Der Seitenzoom des Browsers oder ein Wechsel auf einen Bildschirm mit anderer Skalierung kann den Wert ändern. Zoomen per Zwei-Finger-Geste ändert ihn nicht.

window.matchMedia() nimmt eine CSS-Medienabfrage als Zeichenkette entgegen und liefert ein neues MediaQueryList-Objekt. matches liefert das aktuelle Ergebnis. Das Objekt löst change nur aus, wenn dieser boolesche Wert umspringt. (min-resolution: 2dppx) prüft auf mindestens zwei Gerätepixel pro CSS-Pixel; bei einem Wechsel von 2 auf 3 wird die Schwelle nicht überschritten.

Um DPR-Änderungen zu verfolgen, setze den aktuellen DPR-Wert für … in die exakte Abfrage (resolution: …dppx) ein. Entferne bei change den Listener vom alten Objekt, lies den neuen DPR-Wert und registriere den Listener für eine neue Abfrage. Wenn die exakte Abfrage anfangs nicht zutrifft, rechne nicht damit, dass die nächste DPR-Änderung das Ereignis auslöst. Entferne den aktiven Listener, sobald du ihn nicht mehr brauchst.

Beide APIs gehören zum Window des Browsers, nicht zu ECMAScript 2024 oder zum globalen Gültigkeitsbereich eines Workers. Prüfe die Unterstützung in den Zielbrowsern; addListener() und removeListener() sind veraltete Kompatibilitätsmethoden.

Beispiele

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

Ergebnis

DPR: 1
DPR: 2

In der Browserkonsole erscheint die erste Zeile sofort, weitere nach erkannten Änderungen. Die tatsächlichen Werte im Browser können von den gezeigten abweichen. Mit `stopDprWatch()` beendest du die Beobachtung. In Node.js simuliert ein Testobjekt einen DPR-Wechsel von 1 auf 2; vor dem simulierten Wechsel auf 3 endet die Beobachtung.

Zugehörige Lektionen

  • JavaScript · Lektion 34 · Fortgeschritten · Version: 4

Quellen