MediaQuery — qué es, principio de funcionamiento y diseños adaptables

Qué es MediaQuery

MediaQuery es un widget y clase en Flutter que proporciona datos sobre el entorno multimedia de la aplicación. MediaQuery envuelve toda la aplicación en el widget raíz MaterialApp o CupertinoApp, y cualquier widget hijo puede acceder a estos datos a través de MediaQuery.of(context).

Cuando Flutter inicia una aplicación, crea una instancia de MediaQueryData que contiene todas las métricas del dispositivo actual. Estos datos se actualizan automáticamente ante cambios: rotación del dispositivo, cambio de tamaño de ventana (en escritorio), aparición del teclado o cambios en la configuración de accesibilidad del sistema. MediaQuery reconstruye el subárbol de widgets ante cualquier cambio de datos, proporcionando una adaptación reactiva de la interfaz.

MediaQueryData incluye: size (tamaño de pantalla), devicePixelRatio (densidad de píxeles), textScaleFactor (escala de fuente de la configuración del sistema), viewInsets (área cubierta por el teclado), viewPadding (márgenes del sistema), orientation (orientación) y platformBrightness (tema claro u oscuro).

En resumen: MediaQuery es la fuente central de información del dispositivo en Flutter. Acceder a MediaQuery.of(context) es el primer paso para construir cualquier interfaz adaptable.

Propiedades principales de MediaQueryData

MediaQueryData contiene docenas de propiedades, pero las más utilizadas son aquellas que afectan la construcción del diseño. Veamos las principales.

Size — Tamaño de pantalla

MediaQuery.of(context).size devuelve un objeto Size con el ancho y alto de la pantalla en píxeles independientes del dispositivo (dip). Estos valores no tienen en cuenta los márgenes del sistema. Para cálculos de diseños adaptables, size es la métrica principal: determina los puntos de interrupción para diseños móviles, de tableta y de escritorio.

ViewPadding — Márgenes del sistema

ViewPadding son los márgenes que el sistema reserva para la barra de estado, el notch (recorte en la pantalla), el panel de navegación del sistema y el indicador de inicio (en iOS). Sin tener en cuenta estos márgenes, el contenido puede quedar debajo de los elementos del sistema. MediaQuery.of(context).padding devuelve un EdgeInsets que debe aplicarse como padding al contenedor raíz de la página.

ViewInsets — Área del teclado

ViewInsets es el área de la pantalla cubierta por el teclado virtual. Para los campos de entrada, es fundamental monitorear viewInsets.bottom para elevar el contenido sobre el teclado. Flutter maneja esto automáticamente en scaffold, pero para diseños personalizados debes usar MediaQuery.of(context).viewInsets directamente.

Orientation — Orientación del dispositivo

Orientation — orientación vertical (portrait) u horizontal (landscape). Se determina comparando el ancho y el alto: si el ancho es menor que el alto — portrait, de lo contrario — landscape. En código de producción, la orientación se usa para cambiar entre disposición vertical y horizontal de los elementos.

En resumen: cuatro propiedades clave — size, viewPadding, viewInsets y orientation — cubren el 90% de las tareas de diseño adaptable. Las propiedades restantes (textScaleFactor, platformBrightness, devicePixelRatio) se usan para escenarios específicos.

Uso de MediaQuery para diseños adaptables

MediaQuery es la base del diseño adaptable en Flutter. Permite determinar puntos de interrupción, cambiar el diseño según el tamaño de pantalla y ajustar los márgenes para diferentes dispositivos.

Escenario típico: una aplicación móvil debe mostrar una lista de productos. En un teléfono (ancho < 600dp) — una columna. En una tableta (ancho 600–900dp) — dos columnas. En escritorio (ancho > 900dp) — tres columnas. MediaQuery.of(context).size.width permite seleccionar dinámicamente el número de columnas sin una pantalla separada para cada factor de forma.

Segundo escenario: tener en cuenta los márgenes de gestos del sistema en dispositivos modernos. En iPhones con Dynamic Island o Android con navegación por gestos, los márgenes del sistema consumen parte de la pantalla. MediaQuery.of(context).padding devuelve valores correctos para cada tipo de dispositivo, y Scaffold los aplica automáticamente a través de body. Para widgets personalizados, debes pasar explícitamente el padding desde MediaQuery.

Tercer escenario: adaptación a la configuración de accesibilidad del sistema. MediaQuery.of(context).textScaleFactor muestra cuánto ha aumentado el usuario el tamaño de fuente en la configuración. Con textScaleFactor > 1.3, el diseño puede romperse: los textos largos se salen de los límites de las tarjetas. Los diseños adaptables deben tener esto en cuenta y, si es necesario, cambiar a un diseño más simple.

En resumen: MediaQuery no es solo una fuente de métricas, sino una herramienta para construir interfaces verdaderamente adaptables. Úsalo para puntos de interrupción, área segura y consideraciones de accesibilidad.

Ejemplos de código con MediaQuery

Ejemplo 1 demuestra cómo obtener el tamaño de pantalla y aplicar puntos de interrupción para seleccionar el número de columnas.

int getColumnCount(BuildContext context) {
  final width = MediaQuery.of(context).size.width;
  if (width > 900) return 3;
  if (width > 600) return 2;
  return 1;
}

El ejemplo anterior muestra una función para seleccionar el número de columnas según el ancho de pantalla. Los puntos de interrupción 600 y 900 corresponden a los estándares generalmente aceptados de Material Design para teléfonos, tabletas y escritorio.

Ejemplo 2 — uso de MediaQuery con viewPadding para la colocación correcta del contenido teniendo en cuenta los márgenes del sistema.

Widget build(BuildContext context) {
  final padding = MediaQuery.of(context).padding;

  return Padding(
    padding: EdgeInsets.only(
      top: padding.top,
      left: padding.left,
      right: padding.right,
    ),
    child: const MyContent(),
  );
}

En este ejemplo, padding envuelve el contenido en Padding usando los márgenes del sistema. top tiene en cuenta la barra de estado y el notch, left/right las zonas seguras. bottom no se incluye porque Scaffold normalmente maneja la navegación inferior por sí mismo.

Ejemplo 3 — determinación de la orientación y cambio de disposición de los elementos.

Widget build(BuildContext context) {
  final isPortrait = MediaQuery.of(context).orientation == Orientation.portrait;

  return isPortrait
      ? const Column(
          children: [HeaderBanner(), ContentList()],
        )
      : const Row(
          children: [HeaderBanner(), ContentList()],
        );
}

En modo vertical (portrait), los elementos se disponen verticalmente (Column); en modo horizontal (landscape), horizontalmente (Row). Este enfoque aprovecha al máximo el espacio al rotar el dispositivo.

En resumen: MediaQuery es la herramienta principal para construir diseños adaptables. Siempre ten en cuenta los márgenes del sistema, los puntos de interrupción y la orientación al desarrollar interfaces en Flutter.

Errores comunes al trabajar con MediaQuery

Error 1: llamar a MediaQuery.of(context) fuera de un contexto donde MediaQuery esté configurado. Si un widget está por encima de MediaQuery en el árbol, la llamada provoca un error en tiempo de ejecución. Solución: siempre llamar a MediaQuery.of(context) dentro de widgets envueltos por MaterialApp o CupertinoApp, donde MediaQuery está configurado como widget raíz.

Error 2: olvidar el área segura. Los desarrolladores usan MediaQuery.size para posicionar elementos sin tener en cuenta los márgenes del sistema. En dispositivos con notch o navegación por gestos, el contenido termina debajo de la barra de estado. Solución: restar MediaQuery.of(context).padding de las coordenadas de posicionamiento.

Error 3: vinculación rígida a tamaños. Usar MediaQuery.of(context).size.width para establecer tamaños exactos de elementos (width: size.width * 0.3) solo funciona en dispositivos del mismo factor de forma. En escritorio o tableta, el diseño se ve poco natural. Solución: usar puntos de interrupción en combinación con Expanded y Flexible para un diseño flexible, no porcentajes fijos.

Error 4: ignorar textScaleFactor. Cuando el usuario aumenta la fuente del sistema, la interfaz puede romperse: los textos se salen de los límites de los contenedores. Solución: verificar MediaQuery.of(context).textScaleFactor y, en valores superiores a 1.3, cambiar a un diseño más simple con desplazamiento.

En resumen: MediaQuery es una herramienta potente pero sutil. Ten en cuenta los márgenes del sistema, la orientación y la configuración de accesibilidad para que la interfaz se vea correcta en todos los dispositivos.