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

CKTIS / JavaScript

MediaQueryList: resultado actual y el evento change

MediaQueryList permite consultar el resultado de una consulta de medios y reaccionar cuando cambia. La propiedad matches proporciona el valor booleano actual, mientras que el evento change indica las transiciones entre coincidencia y ausencia de coincidencia.

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("(min-width: 600px)");
mql.matches;
mql.addEventListener("change", handler);
mql.removeEventListener("change", handler);

window.matchMedia(query) devuelve un objeto MediaQueryList que describe el resultado de una consulta de medios para el documento. MediaQueryList.matches es de solo lectura: true significa que hay coincidencia y false que no la hay. Es una propiedad, no un método: lee mql.matches, no mql.matches().

MediaQueryList.change hace referencia al evento que se escucha mediante mql.addEventListener("change", handler), no a un método llamado mql.change(). Se activa cuando el resultado de la consulta cambia entre true y false, no con cada cambio de tamaño. Para (min-width: 600px), una anchura del área de visualización de exactamente 600 píxeles CSS cumple la condición; pasar de 800 a 900 no cambia el resultado. El MediaQueryListEvent que recibe la función de gestión expone el nuevo resultado como event.matches.

Registrar un listener no realiza la actualización inicial. Lee también mql.matches, como hace el ejemplo. Al eliminar un componente, deja de escuchar con removeEventListener("change", handler), pasando la misma referencia de función. En el ejemplo, la función que gestiona el evento change llama directamente a query.removeEventListener('change', handleChange) si event.matches vale true.

Esta es una API del navegador de CSSOM View, no una característica de una edición concreta de ECMAScript; la versión de Node del repositorio no demuestra que sea compatible. MDN indica que matches está ampliamente disponible desde julio de 2015 y change desde septiembre de 2020. Comprueba por separado la compatibilidad con navegadores antiguos; no se recomienda usar el obsoleto addListener() en código nuevo.

Ejemplos

<!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>

Resultado

wide
narrow
wide

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