Window: matchMedia() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die matchMedia() Methode des Window Interfaces gibt ein neues MediaQueryList Objekt zurück, das verwendet werden kann, um festzustellen, ob das document der Media-Query-Zeichenkette entspricht. Außerdem kann damit das Dokument überwacht werden, um festzustellen, wann es dieser Media-Query entspricht (oder nicht mehr entspricht).

Syntax

matchMedia(mediaQueryString)

Parameter

mediaQueryString

Ein String, der die Media-Query spezifiziert, die in eine MediaQueryList geparst wird.

Genau wie in CSS muss jede Media-Funktion in der Expression in Klammern gesetzt werden. Zum Beispiel: matchMedia("(max-width: 600px)") funktioniert, während matchMedia("max-width: 600px") nicht funktioniert. Schlüsselwörter für Medientypen (all, print, screen) und logische Operatoren (and, or, not, only) müssen nicht in Klammern gesetzt werden.

Rückgabewert

Ein neues MediaQueryList Objekt für die Media-Query. Verwenden Sie die Eigenschaften und Ereignisse dieses Objekts, um Übereinstimmungen zu erkennen und Änderungen dieser Übereinstimmungen über die Zeit zu überwachen.

Verwendungshinweise

Sie können die zurückgegebene Media-Query sowohl für sofortige als auch ereignisgesteuerte Überprüfungen verwenden, um zu sehen, ob das Dokument der Media-Query entspricht.

Um eine einmalige, sofortige Überprüfung durchzuführen, ob das Dokument der Media-Query entspricht, betrachten Sie den Wert der matches Eigenschaft, die true sein wird, wenn das Dokument die Anforderungen der Media-Query erfüllt.

Wenn Sie ständig informiert werden müssen, ob das Dokument der Media-Query entspricht oder nicht, können Sie stattdessen auf das change Ereignis achten, das dem Objekt übermittelt wird. Es gibt ein gutes Beispiel dafür im Artikel über Window.devicePixelRatio.

Beispiele

Dieses Beispiel führt die Media-Query (max-width: 600px) aus und zeigt den Wert der matches Eigenschaft des resultierenden MediaQueryList in einem <span> an. Das Ergebnis wird "true" anzeigen, wenn das Ansichtsfenster kleiner oder gleich 600 Pixel breit ist, und "false", wenn das Fenster breiter ist als das.

JavaScript

let mql = window.matchMedia("(max-width: 600px)");

document.querySelector(".mq-value").innerText = mql.matches;

Der JavaScript-Code übergibt die zu prüfende Media-Query an matchMedia(), um sie zu kompilieren, und setzt dann die <span> innerText auf den Wert der matches Eigenschaft des Ergebnisses, sodass deutlich wird, ob das Dokument momentan der Media-Query entspricht, als die Seite geladen wurde.

HTML

html

<span class="mq-value"></span>

Ein einfaches <span>, um die Ausgabe zu erhalten.

.mq-value {
  font:
    18px arial,
    sans-serif;
  font-weight: bold;
  color: #88f;
  padding: 0.4em;
  border: 1px solid #dde;
}

Ergebnis

Siehe Media-Queries programmatisch testen für zusätzliche Code-Beispiele.

Spezifikationen

Specification
CSSOM View Module # dom-window-matchmedia

Browser-Kompatibilität

BCD tables only load in the browser