Medienabfragen programmatisch testen

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.

Das DOM bietet Funktionen, mit denen die Ergebnisse einer Medienabfrage programmatisch über das MediaQueryList-Interface und dessen Methoden und Eigenschaften getestet werden können. Sobald Sie ein MediaQueryList-Objekt erstellt haben, können Sie das Ergebnis der Abfrage überprüfen oder Benachrichtigungen erhalten, wenn sich das Ergebnis ändert.

Erstellen einer Medienabfrageliste

Bevor Sie die Ergebnisse einer Medienabfrage auswerten können, müssen Sie das MediaQueryList-Objekt erstellen, das die Abfrage darstellt. Verwenden Sie dazu die Methode window.matchMedia.

Zum Beispiel, um eine Abfrageliste einzurichten, die bestimmt, ob sich das Gerät im Quer- oder Hochformat Orientierung befindet:

js
const mediaQueryList = window.matchMedia("(orientation: portrait)");

Überprüfen des Ergebnisses einer Abfrage

Sobald Sie Ihre Medienabfrageliste erstellt haben, können Sie das Ergebnis der Abfrage überprüfen, indem Sie den Wert ihrer matches-Eigenschaft betrachten:

js
if (mediaQueryList.matches) {
  /* The viewport is currently in portrait orientation */
} else {
  /* The viewport is not currently in portrait orientation, therefore landscape */
}

Erhalten von Abfragebenachrichtigungen

Wenn Sie fortlaufend über Änderungen am ausgewerteten Ergebnis der Abfrage informiert sein müssen, ist es effizienter, einen Listener zu registrieren, als das Abfrageergebnis abzufragen. Rufen Sie dazu die Methode addEventListener() auf dem MediaQueryList-Objekt auf und übergeben Sie eine Callback-Funktion, die aufgerufen wird, wenn sich der Status der Medienabfrage ändert (z. B. wenn der Medienabfragetest von true zu false wechselt):

js
// Create the query list.
const mediaQueryList = window.matchMedia("(orientation: portrait)");

// Define a callback function for the event listener.
function handleOrientationChange(mql) {
  // …
}

// Run the orientation change handler once.
handleOrientationChange(mediaQueryList);

// Add the callback function as a listener to the query list.
mediaQueryList.addEventListener("change", handleOrientationChange);

Dieser Code erstellt die Medienabfrageliste zum Testen der Orientierung und fügt ihr einen Ereignislistener hinzu. Nachdem der Listener definiert wurde, wird dieser auch direkt aufgerufen. Dadurch passt unser Listener die Einstellungen basierend auf der aktuellen Geräteorientierung an; andernfalls könnte unser Code annehmen, dass sich das Gerät im Hochformat befindet, auch wenn es tatsächlich im Querformat ist.

Die Funktion handleOrientationChange() würde das Ergebnis der Abfrage betrachten und alles Notwendige bei einer Orientierungänderung ausführen:

js
function handleOrientationChange(evt) {
  if (evt.matches) {
    /* The viewport is currently in portrait orientation */
  } else {
    /* The viewport is currently in landscape orientation */
  }
}

Oben definieren wir den Parameter als evt — ein Ereignisobjekt des Typs MediaQueryListEvent, das auch die Eigenschaften media und matches umfasst, sodass Sie diese Merkmale der MediaQueryList abfragen können, indem Sie direkt darauf zugreifen oder auf das Ereignisobjekt zugreifen.

Beenden von Abfragebenachrichtigungen

Um keine Benachrichtigungen mehr über Änderungen des Werts Ihrer Medienabfrage zu erhalten, rufen Sie removeEventListener() auf der MediaQueryList auf und übergeben Sie den Namen der zuvor definierten Callback-Funktion:

js
mediaQueryList.removeEventListener("change", handleOrientationChange);

Spezifikationen

Specification
CSSOM View Module
# the-mediaquerylist-interface

Browser-Kompatibilität

Siehe auch