matchMedia()
Sprawdza w JavaScripcie, czy strona spełnia zapytanie medialne CSS, np. (max-width: 600px), i pozwala reagować na jego zmiany.
- Zwraca
- Obiekt
MediaQueryListz właściwościamimatchesimedia.
Przykład
#const mobile = matchMedia('(max-width: 600px)')
const prefersDark = matchMedia('(prefers-color-scheme: dark)')
console.log(mobile.media)
console.log(mobile.matches)
console.log(prefersDark.matches)
if (!mobile.matches) {
console.log('Pokazuję pełne menu z nazwami sekcji')
}(max-width: 600px) false true Pokazuję pełne menu z nazwami sekcji
Wynik dotyczy szerokiego okna na komputerze z włączonym ciemnym motywem systemu. Na telefonie mobile.matches ma wartość true. Wynik zależy od urządzenia, dlatego ten przykład nie uruchamia się w podglądzie.
Definicja i zastosowanie
#Funkcja matchMedia() (pełna nazwa to window.matchMedia()) przyjmuje zapytanie medialne w tej samej postaci co reguła @media w CSS i zwraca obiekt MediaQueryList. Jego właściwość matches ma wartość true, gdy warunek jest spełniony, a media zawiera treść zapytania. W ten sposób sprawdzisz szerokość okna, orientację ekranu czy preferencje użytkownika.
Obiekt zgłasza zdarzenie change za każdym razem, gdy wynik zapytania się zmieni, np. gdy użytkownik zwęzi okno poniżej progu albo przełączy system w tryb ciemny. Obsługę podpinasz przez addEventListener("change", …), a obiekt zdarzenia też ma pole matches. To wydajniejsze niż sprawdzanie window.innerWidth przy każdym zdarzeniu resize, bo funkcja wywoła się tylko przy przekroczeniu progu.
Szczególnie przydatne są zapytania o preferencje: (prefers-color-scheme: dark) mówi, czy system używa ciemnego motywu, a (prefers-reduced-motion: reduce), czy użytkownik prosi o ograniczenie animacji. Warto je uwzględniać w skryptach, które same animują elementy albo wybierają motyw strony.
Składnia
#window.matchMedia(mediaQueryString)
mediaQueryList.matches
mediaQueryList.media
mediaQueryList.addEventListener("change", listener)Parametry
#mediaQueryString
napis
Zapytanie medialne zapisane jak w CSS, np."(max-width: 600px)"albo"(prefers-color-scheme: dark)".
Więcej przykładów
#const nav = document.querySelector('#nav')
const narrow = matchMedia('(max-width: 600px)')
function updateNav(query) {
nav.textContent = query.matches ? 'Menu ☰' : 'Kursy · Ranking · Profil · Ustawienia'
}
updateNav(narrow)
narrow.addEventListener('change', updateNav)
console.log('Nasłuchuję zmian:', narrow.media)Treść menu zależy od szerokości ramki z przykładem. Zwęź albo poszerz okno przeglądarki tak, żeby ramka przekroczyła 600 px, a menu przełączy się samo, bez nasłuchiwania zdarzenia resize.
const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)')
function scrollToTop() {
window.scrollTo({ top: 0, behavior: reduceMotion.matches ? 'auto' : 'smooth' })
}
console.log(reduceMotion.matches ? 'Przewijanie bez animacji' : 'Płynne przewijanie')Płynne przewijanie
Większość osób nie ma włączonego ograniczenia ruchu, więc zwykle zobaczysz ten wynik. Po włączeniu redukcji animacji w ustawieniach systemu matches zmieni się na true, a strona przewinie się bez animacji.
Obsługa przeglądarek
#Szeroko dostępne
Działa we wszystkich nowoczesnych przeglądarkach, także na telefonach. Możesz używać bez obaw.
- Chrome
- Edge
- Firefox
- Safari
Dobre praktyki
#- Do reagowania na zmiany używaj
addEventListener("change", …). Starsza metodaaddListener()jest przestarzała. - Trzymaj progi szerokości w skryptach zgodne z punktami przełamania w CSS. Inaczej przy tej samej szerokości skrypt i style mogą zachowywać się różnie.
- Sam wygląd zmieniaj w CSS przez
@media.matchMedia()przydaje się wtedy, gdy od zapytania zależy logika, np. czy włączyć animację albo który komponent pokazać.
Powiązane hasła
#- getComputedStyle()Zwraca obliczone style elementu, czyli wartości CSS, które przeglądarka faktycznie zastosowała po uwzględnieniu wszystkich reguł.
- EventTarget.addEventListener()Rejestruje funkcję wywoływaną za każdym razem, gdy na elemencie wystąpi zdarzenie, np. kliknięcie.
- ResizeObserverWywołuje funkcję za każdym razem, gdy zmieni się rozmiar obserwowanego elementu, bez względu na przyczynę zmiany.
- Element.scrollIntoView()Przewija stronę i przewijane kontenery tak, żeby element pojawił się na ekranie, skokiem albo płynnie.
- Element.classListObiekt do dodawania, usuwania, przełączania i sprawdzania klas CSS elementu.
Widzisz błąd albo brakuje przykładu? Napisz do nas.