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. Das Event-Objekt besitzt die MatchMediaListEvent-Schnittstelle

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 der CSSOM-View Spezifikation erbte MediaQueryList noch nicht von EventTarget und implementierte sein eigenes Event-Handling mit addListener und removeListener. MDN beschreibt diese Methoden als obsolet, die Spezifikation hingegen benennt sie lediglich als Alias.

Der registrierte Handler bekommt ein MediaQueryListEvent Objekt übergeben. Dieses erbt von Event und erweitert es um zwei Nurlesen-Eigenschaften:

matches

ein Duplikat der gleichnamigen Eigenschaft des MediaQueryList-Objekts und gibt an, wie der aktuelle Match-Zustand der MediaQueryList ist.

media

Die String-Darstellung der MediaQueryList

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