JavaScript/Window/matchMedia

Die Methode Window.matchMedia gibt ein MediaQueryList-Objekt zurück, das das Ergebnis einer Medienabfrage (Media Queries) enthält.

Browserunterstützung
caniuse.com

Syntax

mql = window.matchMedia(mediaQueryString)

• mediaQueryString: Zeichenkette, die das Medienmerkmal enthält, nach dem geprüft werden soll.
• mql: Rückgabewert ist ein MediaQueryList-Objekt

Das MediaQueryList-Objekt trägt den Begriff „List“ im Namen, ist aber keine Liste. Es repräsentiert die im mediaQueryString angegebene Medienabfrage und ihr Ergebnis. Dieses Ergebnis ist kein „Schnappschuss“ des Zustandes beim Aufruf der Methode, sondern aktualisiert sich automatisch. Diese Aktualisierung können Sie darüber hinaus auch überwachen: MediaQueryList ist ein EventTarget und stellt ein change Event bereit, das ausgelöst wird, sobald sich das Ergebnis der Abfrage ändert.

MediaQueryList-Objekt: Eigenschaften

• matches: gibt true zurück, wenn die Bedingung erfüllt ist
• media: gibt die abgefragte MediaQueryList zurück
• onchange: hier kann direkt eine Callback-Funktion für das change-Event hinterlegt werden

Ereignisse

• change: wird ausgelöst, wenn sich der Wert von matches ändert

Methoden

• addEventListener: registriert einen EventListener nach aktuellen Standards.
• removeEventListener: entfernt einen EventListener
• addListener: veraltet! - Synonym zu addEventListener('change', funktion)
• removeListener: veraltet! - Synonym zu removeEventListener('change', funktion)

Beachte: In früheren Versionen des CSSOM erbte MediaQueryList noch nicht von EventTarget und implementierte sein eigenes Event-Handling mit addListener und removeListener.

Der registrierte Handler bekommt in neueren Browsern ein MediaQueryListEvent Objekt übergeben. Dabei handelt es sich um ein Event Objekt, das um die Nurlesen-Eigenschaften media und matches erweitert wurde. Diese spiegeln die entsprechenden Eigenschaften aus dem MediaQueryList-Objekt wieder.

Anwendungsbeispiel

if (window.matchMedia('(min-width: 35em)').matches) {
  /* Der Viewport ist mindestens 35em breit */
} else {
  /* Das Medienmerkmal trifft nicht zu, alle anderen Viewports */
}

Color-Picker

Sie können mit Window.matchMedia nicht nur Breiten, sondern auch eine Vielzahl anderer Medienmerkmale überprüfen.

Color-Picker auf monochromen Bildschirmen?

if (window.matchMedia('(min-color: 2)').matches) {
  /* Color-Picker */
} else {
  /* Das Medienmerkmal trifft nicht zu, monochromer Bildschirm */
}

In diesem Beispiel wird die Farbtiefe des Bildschirms mit color abgefragt.

Ein color-picker in Javascript, der unter monochromen Displays entweder durch einen „Schade, sie haben leider kein Farbdisplay“-Hinweis oder durch ein reines Graustufen-Äquivalent ersetzt wird.

Siehe auch

• JavaScript und CSS/CSS-Eigenschaften auslesen
  Medienabfrage mit matchMedia, um die viewBox eines SVG von landscape auf portrait zu ändern
• Dark Mode
  kombinierte Abfrage von prefers-color-scheme und Nutzerauswahl
• Hintergrundvideo
  Nutzer, die keine Animation und Bewegung mögen, erhalten mit window.matchMedia('(prefers-reduced-motion: reduce)') nur ein Standbild
• JavaScript/Fullscreen
  Überprüfung mit matchMedia, ob der display-mode im Fullscreen-Modus ist.

Weblinks

• MediaEvent: window.matchMedia • Pendant zu Media Queries
• christianheilmann: Conditional loading of resources with mediaqueries