Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

MediaQueryList: bieżący wynik i zdarzenie change

MediaQueryList pozwala sprawdzić wynik zapytania o media i reagować na jego zmianę. Właściwość matches dostarcza bieżącą wartość logiczną, a zdarzenie change informuje o przejściu między dopasowaniem a jego brakiem.

Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Składnia

const mql = window.matchMedia("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);

window.matchMedia(query) zwraca obiekt MediaQueryList opisujący wynik zapytania o media dla dokumentu. MediaQueryList.matches jest właściwością tylko do odczytu: true oznacza dopasowanie, a false jego brak. To właściwość, nie metoda — odczytuj mql.matches, nie mql.matches().

MediaQueryList.change oznacza zdarzenie nasłuchiwane przez mql.addEventListener("change", handler), a nie metodę mql.change(). Jest emitowane, gdy wynik zapytania zmienia się między true a false, nie przy każdej zmianie rozmiaru. Dla (min-width: 600px) szerokość obszaru widoku równa 600 pikselom CSS spełnia warunek; przejście z 800 do 900 go nie zmienia. Obiekt MediaQueryListEvent przekazany do funkcji obsługi udostępnia nowy wynik jako event.matches.

Samo dodanie nasłuchiwania nie wykonuje początkowej aktualizacji. Odczytaj więc również mql.matches, jak w przykładzie. Przy usuwaniu komponentu zakończ nasłuchiwanie przez removeEventListener("change", handler), przekazując tę samą referencję funkcji. W przykładzie funkcja obsługi zdarzenia change wywołuje bezpośrednio query.removeEventListener('change', handleChange), jeśli event.matches ma wartość true.

To API przeglądarkowe z CSSOM View, nie funkcja konkretnej edycji ECMAScript; wersja Node w repozytorium nie potwierdza jego obsługi. MDN oznacza matches jako powszechnie dostępne od lipca 2015, a change od września 2020. Dla starszych przeglądarek sprawdź zgodność osobno; przestarzałe addListener() nie jest zalecane w nowym kodzie.

Przykłady

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>MediaQueryList matches and change</title>
</head>
<body>
  <script>
    const frame = document.createElement('iframe');
    frame.title = 'Media query test viewport';
    frame.style.cssText = 'display:block; width:320px; height:60px; border:0';
    frame.srcdoc = '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Test viewport</title></head><body></body></html>';

    frame.addEventListener('load', () => {
      const query = frame.contentWindow.matchMedia('(min-width: 250px)');
      const report = matches => console.log(matches ? 'wide' : 'narrow');

      function handleChange(event) {
        report(event.matches);
        if (event.matches) {
          query.removeEventListener('change', handleChange);
        } else {
          frame.style.width = '320px';
        }
      }

      query.addEventListener('change', handleChange);
      report(query.matches);
      frame.style.width = '120px';
    }, { once: true });

    document.body.append(frame);
  </script>
</body>
</html>

Wynik

wide
narrow
wide

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła