Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

window.matchMedia — comprobar consultas de medios

window.matchMedia comprueba una consulta de medios CSS desde JavaScript. Devuelve una MediaQueryList con el resultado actual en matches y permite observar los cambios en la coincidencia de la consulta.

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

Sintaxis

const mql = window.matchMedia(query);
mql.matches;
mql.media;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);

window.matchMedia(query) crea una nueva MediaQueryList, no un valor booleano. Lee matches para obtener el resultado actual; media contiene la consulta serializada.

Pasa una consulta CSS como "(min-width: 768px)", sin @media. La característica de medios width se refiere al ancho del área de visualización (viewport) en los medios continuos y al ancho de la caja de página (page box) en los medios paginados, como la impresión. La unidad px significa píxeles CSS. Esta consulta no se limita al tipo de medio screen. El método comprueba una condición; no aplica estilos por sí mismo.

Esta es una API del navegador de CSSOM View, no una característica de ECMAScript. Antes de llamar a window.matchMedia(query), comprueba typeof window !== "undefined" && typeof window.matchMedia === "function"; Node 24 por sí solo no demuestra que la API esté disponible. Esta comprobación no verifica si el objeto devuelto tiene los métodos para gestionar escuchas de eventos.

Lee el resultado inicial en mql.matches, donde mql es la MediaQueryList devuelta. Registra el manejador con mql.addEventListener("change", handler) solo si typeof mql.addEventListener === "function" && typeof mql.removeEventListener === "function". Si falta alguno de los métodos, omite el registro; puedes seguir leyendo matches. El evento indica que el resultado ha cambiado, no cada cambio de tamaño; event.matches proporciona el nuevo resultado. Si registraste el manejador, llama a mql.removeEventListener("change", handler) con la misma función al limpiar.

El ejemplo usa all y su negación not all, por lo que el resultado no depende del tamaño de la ventana.

Ejemplos

const always = window.matchMedia("all");
const never = window.matchMedia("not all");
console.log(always.matches);
console.log(never.matches);

Resultado

true
false

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes