Expanded: o que é e como funciona no Flutter

O que é Expanded

Expanded é um widget envoltório que pega um filho e o força a expandir para preencher o espaço disponível em um contêiner Flex (Row, Column, Flex). Expanded não tem representação visual própria — ele apenas gerencia as restrições (constraints) passadas ao elemento filho.

No núcleo do Expanded está o mecanismo Flex fornecido pelo framework Flutter. Quando Row ou Column calculam os tamanhos de seus filhos, eles primeiro alocam espaço para elementos inflexíveis (widgets regulares com tamanhos fixos), depois distribuem o espaço restante entre os filhos Expanded e Flexible proporcionalmente aos seus fatores flex.

Expanded usa Flexible.fit = FlexFit.tight. Isso significa que o filho de Expanded deve ocupar todo o espaço alocado, mesmo que seu próprio tamanho seja menor. Diferente de Flexible com Fit.loose, onde o filho pode ser menor que a área alocada, Expanded estica forçadamente o conteúdo.

Resumo: Expanded é a ferramenta principal para criar layouts proporcionais no Flutter. Use-o quando precisar que um elemento garanta preencher toda a largura ou altura disponível.

Expanded vs Flexible: diferenças principais

Expanded e Flexible ambos distribuem espaço em contêineres Flex, mas se comportam de forma fundamentalmente diferente. A diferença está na propriedade fit, que determina se o filho pode ser menor que o espaço disponível.

Expanded tem um modelo de comportamento estrito: seu fit é igual a FlexFit.tight. Isso significa que o widget filho recebe restrições iguais ao espaço disponível — nem mais, nem menos. Se o filho é menor, ele estica. Se é maior, ele encolhe. Flexible usa FlexFit.loose, permitindo que o elemento filho tenha qualquer tamanho dentro do espaço alocado.

Na prática: se uma Row contém dois Expanded com flex=1, cada um ocupará exatamente metade da largura. Se você substituí-los por Flexible com fit.loose, cada filho pode ser menor que a metade se seu próprio tamanho for menor — o espaço restante ficará vazio.

Resumo: use Expanded para layouts proporcionais estritos, Flexible quando o filho pode ser menor que o espaço disponível. Se não tiver certeza — comece com Expanded, ele oferece um comportamento mais previsível.

Fator flex: como o espaço é distribuído

Fator flex (parâmetro flex) é um valor numérico que determina a porção do espaço disponível que um Expanded receberá. Por padrão flex=1, significando distribuição igual entre todos os filhos Expanded.

O algoritmo de distribuição funciona em três etapas. Primeiro: Flutter calcula o tamanho intrínseco de todos os filhos inflexíveis. Segundo: o espaço restante é dividido pela soma de todos os fatores flex. Terceiro: cada Expanded recebe uma parte igual ao seu fator flex multiplicado pelo tamanho de uma unidade flex.

Por exemplo, uma Row de 300px de largura contém dois Expanded: o primeiro com flex=2, o segundo com flex=1. O espaço livre (300px menos filhos inflexíveis) é dividido em 3 partes. O primeiro recebe 2/3, o segundo recebe 1/3. Se não houver filhos inflexíveis, o primeiro recebe 200px, o segundo recebe 100px.

O fator flex pode ser qualquer número inteiro positivo. O valor 0 é um caso especial: Expanded com flex=0 se comporta como um widget inflexível regular, ocupando o espaço mínimo de acordo com o tamanho do filho. Este comportamento é equivalente a não ter Expanded.

Resumo: o fator flex é a chave para construir layouts flexíveis. Use proporções 1:1 para colunas iguais, 2:1 para painéis com área principal e lateral, 3:1 para interfaces com navegação estreita.

Exemplos de código com Expanded

Exemplo 1 demonstra o uso básico de Expanded em Row para criar três colunas iguais.

Row(
  children: [
    Expanded(
      child: Container(
        color: Colors.red,
      ),
    ),
    Expanded(
      child: Container(
        color: Colors.green,
      ),
    ),
    Expanded(
      child: Container(
        color: Colors.blue,
      ),
    ),
  ],
)

Neste exemplo, três Expanded com flex=1 (padrão) dividem a largura da Row igualmente. Os contêineres esticam até a altura total definida pela Row e ocupam partes iguais. Esta abordagem é conveniente para criar layouts baseados em colunas com distribuição proporcional.

Exemplo 2 mostra o uso de diferentes fatores flex para criar um layout com barra lateral e conteúdo principal.

Row(
  children: [
    Expanded(
      flex: 1,
      child: Container(
        color: Colors.grey.200,
        child: const Center(
          child: Text('Barra lateral'),
        ),
      ),
    ),
    Expanded(
      flex: 3,
      child: Container(
        color: Colors.white,
        child: const Center(
          child: Text('Área de conteúdo'),
        ),
      ),
    ),
  ],
)

O segundo exemplo cria um layout típico com uma barra lateral (25%) e uma área de conteúdo principal (75%). flex=1 e flex=3 dão uma proporção 1:3. Quando a largura da tela muda, as proporções são preservadas automaticamente — esta é a base das interfaces adaptativas.

Resumo: Expanded com diferentes fatores flex é uma ferramenta padrão para construir layouts adaptativos. A combinação de Expanded em Column permite criar arranjos proporcionais tanto horizontais quanto verticais.

Erros comuns ao usar Expanded

Erro 1: usar Expanded fora de Row, Column ou Flex. Se você colocar Expanded diretamente em Stack, ListView ou outro contêiner não-Flex, Flutter lança uma LayoutException com a mensagem "Expanded widgets must be placed inside Flex widgets". Solução: verifique o widget pai — apenas Row, Column ou Flex.

Erro 2: colocar Expanded dentro de ListView sem especificar shrinkWrap. ListView por padrão tem altura infinita na direção de rolagem, e Expanded não pode calcular sua parte. Solução: use shrinkWrap: true ou envolva o ListView em um SizedBox com altura fixa.

Erro 3: múltiplos Expanded com flex total excedendo o espaço disponível. Se uma Row com largura limitada contém Expanded bem como widgets com grande tamanho intrínseco, pode ocorrer transbordamento. Solução: verifique os tamanhos mínimos dos filhos inflexíveis e use FittedBox ou Flex fit se necessário.

Erro 4: Expanded aninhados em Column dentro de Row. Se um Expanded dentro de uma Column contém outro Expanded dentro de uma Row, pode surgir um conflito de restrições. Solução: limite a profundidade de aninhamento ou use ConstrainedBox para definir dimensões explicitamente em níveis intermediários.

Resumo: Expanded requer o contexto pai correto. Sempre verifique se Expanded está colocado diretamente em Row, Column ou Flex, e evite aninhamento sem dimensões explícitas.