WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

MediaQueryList: die Eigenschaft matches und das Ereignis change

Mit `matches` liest du das aktuelle Ergebnis einer CSS-Medienabfrage. Mit `change` reagierst du nur darauf, dass sich das Ergebnis ändert.

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

Syntax

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) nimmt eine CSS-Medienabfrage als Zeichenkette entgegen und liefert ein neues MediaQueryList-Objekt. Seine schreibgeschützte boolesche Eigenschaft matches ist true, wenn das Dokument die Abfrage derzeit erfüllt, andernfalls false. Die Abfrage (max-width: 600px) schließt eine Viewportbreite von genau 600 CSS-Pixeln ein.

Registriere die Funktion mit mql.addEventListener("change", onChange). Der Browser löst change auf diesem MediaQueryList-Objekt aus, wenn das Ergebnis von false auf true wechselt oder umgekehrt, nicht bei jeder Größenänderung. Die Funktion erhält ein MediaQueryListEvent: event.matches enthält das neue Ergebnis und event.media den Abfragetext.

Das Registrieren des Listeners ruft ihn nicht sofort auf. Lies mql.matches für den Anfangszustand und verwende event.matches für spätere Änderungen. Wenn du keine weiteren Meldungen brauchst, rufe mql.removeEventListener("change", onChange) auf demselben Objekt mit derselben Funktion auf.

Dies ist eine Browser-API und kein Bestandteil von ECMAScript 2024. Außerhalb eines Browsers kannst du ihre Verfügbarkeit nicht voraussetzen. addListener() und removeListener() sind ältere Methoden zur Kompatibilität; verwende in neuem Code vorzugsweise addEventListener() und removeEventListener().

Beispiele

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

Ergebnis

initial: false
change: true
change: false

Öffne `about:blank` im Browser und führe den Code in der Browserkonsole aus. Der Code stellt die Viewportbreite des `iframe` von 800 auf 600, dann auf 500 und wieder auf 800 CSS-Pixel. Bei 500 erscheint keine neue Ausgabe. Nach dem Entfernen des Listeners erzeugt auch der erneute Wechsel auf 600 keine Ausgabe.

Zugehörige Lektionen

  • JavaScript · Lektion 29 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 34 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 35 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 36 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 37 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 39 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 45 · Fortgeschritten · Version: 4
  • JavaScript · Lektion 27 · Mittlere Stufe · Version: 3
  • JavaScript · Lektion 28 · Mittlere Stufe · Version: 3
  • JavaScript · Lektion 29 · Mittlere Stufe · Version: 3

Quellen