MediaQuery — o que é, princípio de funcionamento e layouts adaptáveis

O que é MediaQuery

MediaQuery é um widget e classe no Flutter que fornece dados sobre o ambiente de mídia da aplicação. MediaQuery envolve toda a aplicação no widget raiz MaterialApp ou CupertinoApp, e qualquer widget filho pode acessar esses dados através de MediaQuery.of(context).

Quando o Flutter inicia uma aplicação, ele cria uma instância de MediaQueryData contendo todas as métricas do dispositivo atual. Esses dados são atualizados automaticamente em mudanças: rotação do dispositivo, redimensionamento de janela (no desktop), aparecimento do teclado ou alteração nas configurações de acessibilidade do sistema. MediaQuery reconstrói a subárvore de widgets em qualquer mudança de dados, fornecendo adaptação reativa da interface.

MediaQueryData inclui: size (tamanho da tela), devicePixelRatio (densidade de pixels), textScaleFactor (escala da fonte das configurações do sistema), viewInsets (área coberta pelo teclado), viewPadding (margens do sistema), orientation (orientação) e platformBrightness (tema claro ou escuro).

Em resumo: MediaQuery é a fonte central de informações do dispositivo no Flutter. Acessar MediaQuery.of(context) é o primeiro passo para construir qualquer interface adaptável.

Propriedades principais do MediaQueryData

MediaQueryData contém dezenas de propriedades, mas as mais usadas são aquelas que afetam a construção do layout. Vamos ver as principais.

Size — Tamanho da tela

MediaQuery.of(context).size retorna um objeto Size com a largura e altura da tela em pixels independentes de dispositivo (dip). Esses valores não consideram as margens do sistema. Para cálculos de layout adaptável, size é a métrica principal: determina pontos de quebra para layouts móveis, tablet e desktop.

ViewPadding — Margens do sistema

ViewPadding são as margens que o sistema reserva para a barra de status, notch (recorte na tela), painel de navegação do sistema e indicador de início (no iOS). Sem considerar essas margens, o conteúdo pode ficar sob elementos do sistema. MediaQuery.of(context).padding retorna um EdgeInsets que deve ser aplicado como padding ao contêiner raiz da página.

ViewInsets — Área do teclado

ViewInsets é a área da tela coberta pelo teclado virtual. Para campos de entrada, é crítico monitorar viewInsets.bottom para elevar o conteúdo acima do teclado. Flutter lida com isso automaticamente no scaffold, mas para layouts personalizados você precisa usar MediaQuery.of(context).viewInsets diretamente.

Orientation — Orientação do dispositivo

Orientation — orientação retrato (portrait) ou paisagem (landscape). É determinada comparando largura e altura: se a largura é menor que a altura — retrato, caso contrário — paisagem. Em código de produção, a orientação é usada para alternar entre disposição vertical e horizontal dos elementos.

Em resumo: quatro propriedades principais — size, viewPadding, viewInsets e orientation — cobrem 90% das tarefas de design adaptável. As propriedades restantes (textScaleFactor, platformBrightness, devicePixelRatio) são usadas para cenários específicos.

Usando MediaQuery para layouts adaptáveis

MediaQuery é a base do design adaptável no Flutter. Através dele determinam-se pontos de quebra, alterna-se o layout conforme o tamanho da tela e ajustam-se as margens para diferentes dispositivos.

Cenário típico: um aplicativo móvel precisa exibir uma lista de produtos. No telefone (largura < 600dp) — uma coluna. No tablet (largura 600–900dp) — duas colunas. No desktop (largura > 900dp) — três colunas. MediaQuery.of(context).size.width permite selecionar dinamicamente o número de colunas sem uma tela separada para cada fator de forma.

Segundo cenário: considerar as margens de gestos do sistema em dispositivos modernos. Em iPhones com Dynamic Island ou Android com navegação por gestos, as margens do sistema consomem parte da tela. MediaQuery.of(context).padding retorna valores corretos para cada tipo de dispositivo, e Scaffold os aplica automaticamente através de body. Para widgets personalizados, você precisa passar explicitamente o padding do MediaQuery.

Terceiro cenário: adaptação às configurações de acessibilidade do sistema. MediaQuery.of(context).textScaleFactor mostra quanto o usuário aumentou o tamanho da fonte nas configurações. Com textScaleFactor > 1.3, o layout pode quebrar — textos longos ultrapassam os limites dos cartões. Layouts adaptáveis devem considerar isso e, se necessário, alternar para um layout mais simples.

Em resumo: MediaQuery não é apenas uma fonte de métricas, mas uma ferramenta para construir interfaces verdadeiramente adaptáveis. Use-o para pontos de quebra, área segura e considerações de acessibilidade.

Exemplos de código com MediaQuery

Exemplo 1 demonstra como obter o tamanho da tela e aplicar pontos de quebra para selecionar o número de colunas.

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

O exemplo acima mostra uma função para selecionar o número de colunas com base na largura da tela. Os pontos de quebra 600 e 900 correspondem aos padrões geralmente aceitos do Material Design para telefones, tablets e desktop.

Exemplo 2 — uso de MediaQuery com viewPadding para posicionamento correto do conteúdo considerando as margens do 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(),
  );
}

Neste exemplo, padding envolve o conteúdo em Padding usando as margens do sistema. top considera a barra de status e o notch, left/right as áreas seguras. bottom não está incluído porque Scaffold geralmente lida com a navegação inferior por conta própria.

Exemplo 3 — determinação da orientação e mudança de disposição dos 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()],
        );
}

No modo retrato, os elementos são dispostos verticalmente (Column); no modo paisagem, horizontalmente (Row). Essa abordagem aproveita ao máximo o espaço ao girar o dispositivo.

Em resumo: MediaQuery é a principal ferramenta para construir layouts adaptáveis. Sempre considere as margens do sistema, pontos de quebra e orientação ao desenvolver interfaces Flutter.

Erros comuns ao trabalhar com MediaQuery

Erro 1: chamar MediaQuery.of(context) fora de um contexto onde MediaQuery está configurado. Se um widget está acima de MediaQuery na árvore, a chamada causa um erro em tempo de execução. Solução: sempre chamar MediaQuery.of(context) dentro de widgets envolvidos por MaterialApp ou CupertinoApp, onde MediaQuery está configurado como widget raiz.

Erro 2: esquecer a área segura. Desenvolvedores usam MediaQuery.size para posicionar elementos sem considerar as margens do sistema. Em dispositivos com notch ou navegação por gestos, o conteúdo fica sob a barra de status. Solução: subtrair MediaQuery.of(context).padding das coordenadas de posicionamento.

Erro 3: vinculação rígida a tamanhos. Usar MediaQuery.of(context).size.width para definir tamanhos exatos de elementos (width: size.width * 0.3) funciona apenas em dispositivos do mesmo fator de forma. No desktop ou tablet, o layout parece não natural. Solução: usar pontos de quebra em combinação com Expanded e Flexible para um layout flexível, não porcentagens fixas.

Erro 4: ignorar textScaleFactor. Quando o usuário aumenta a fonte do sistema, a interface pode quebrar — textos ultrapassam os limites dos contêineres. Solução: verificar MediaQuery.of(context).textScaleFactor e em valores acima de 1.3 alternar para um layout mais simples com rolagem.

Em resumo: MediaQuery é uma ferramenta poderosa, mas sutil. Considere as margens do sistema, orientação e configurações de acessibilidade para garantir que a interface pareça correta em todos os dispositivos.