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 der Window-Schnittstelle gibt ein neues MediaQueryList-Objekt zurück, mit dem dann überprüft werden kann, ob das document mit dem Media Query-String übereinstimmt. Außerdem kann damit das Dokument überwacht werden, um festzustellen, wann es mit dieser Media Query übereinstimmt oder nicht mehr übereinstimmt.

Syntax

matchMedia(mediaQueryString)

Parameter

mediaQueryString

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

Genau wie in CSS muss jede Media Feature in Klammern innerhalb des Ausdrucks eingefasst sein. Zum Beispiel funktionieren matchMedia("(width <= 600px)") oder matchMedia("(orientation: landscape)"), während matchMedia("width < 600px") oder matchMedia("orientation: landscape") nicht funktionieren. 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 im Laufe der Zeit zu überwachen.

Nutzungshinweise

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

Um eine einmalige, sofortige Prüfung durchzuführen, ob das Dokument mit der Media Query übereinstimmt, sehen Sie sich den Wert der matches-Eigenschaft an. Diese ist true, wenn das Dokument die Anforderungen der Media Query erfüllt.

Wenn Sie ständig informiert bleiben müssen, ob das Dokument mit der Media Query übereinstimmt oder nicht, können Sie stattdessen das change-Ereignis des Objekts beobachten. Im Artikel zu Window.devicePixelRatio gibt es ein gutes Beispiel dafür.

Beispiele

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

JavaScript

let mql = window.matchMedia("(width <= 600px)");

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

Der JavaScript-Code übergibt die Media Query, die abgeglichen werden soll, an matchMedia(), um sie zu kompilieren, und setzt dann die innerText des <span> auf den Wert der matches-Eigenschaft der Ergebnisse, sodass er angibt, ob das Dokument bei der Seite geladen wurde, die Media Query erfüllt oder nicht.

HTML

html

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

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

.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 Codebeispiele.

Spezifikationen

Specification
CSSOM View Module # dom-window-matchmedia