Como depurar problemas de layout com o Flutter Inspector

Entendendo por que eles ocorrem e como resolvê-los

Observação: conhecer Row, Column e Expanded é útil, mas não obrigatório, para este artigo.

Como desenvolvedor Flutter, você provavelmente já teve problemas em que uma imagem foi cortada (ou nem ficou visível) no seu app. Talvez tenha recebido o erro “viewport was given unbounded height”. Na verdade, os dois tipos mais frequentes de erro no Flutter são problemas de layout: overflow de widget e problemas de “renderbox not laid out”. Você não está sozinho em ter problemas de layout, mas para onde ir para resolvê-los?

Felizmente, o Flutter Inspector, do Dart DevTools, pode ajudar você a entender por que eles acontecem e também como você pode resolvê-los. Neste artigo, você aprende a usar a ferramenta depurando 3 problemas comuns de layout. Assim, da próxima vez que encontrar um problema, você poderá resolvê-lo como um profissional!

O que é o Flutter Inspector?

O Flutter Inspector é uma ferramenta (parte do conjunto Dart DevTools) para explorar e visualizar árvores de widgets. Ele é perfeito para descobrir os detalhes do layout do seu app. Dê uma olhada na ferramenta no GIF a seguir:

Um GIF mostrando os recursos Details Tree e Layout Explorer do Flutter Inspector
Um GIF mostrando os recursos Details Tree e Layout Explorer do Flutter Inspector

Com o inspector, você pode selecionar widgets no app ou até remover o banner de debug. Ele resolve tudo, seja se você se pergunta por que seu widget está invisível ou tem curiosidade sobre como adicionar flex ao filho de um Row afeta a UI. O artigo se concentra nos seguintes recursos:

  • Details Tree — Permite examinar as propriedades de cada widget. Você pode examinar o tamanho real de um widget e ver como as constraints são passadas do widget pai.

  • Layout Explorer — Permite visualizar Flex widgets (Row, Column, Flex) e seus filhos. Ajustar o flex, o fit e o alinhamento do eixo permite ver as mudanças no seu app em execução.

Neste ponto, você pode estar se perguntando: “Como experimento essa ferramenta incrível?” Basta executar o Dart DevTools no app, e o Inspector é a primeira ferramenta que você vê. Para mais informações, veja como executar o Dart DevTools a partir da sua IDE ou da linha de comando.

A aventura de depuração 🤠

Vamos começar com um app de demonstração contendo 3 problemas de layout que você vai depurar. Você usará o Flutter Inspector para depurar cada problema separadamente e combinará os problemas corrigidos no final para completar um app de menu simples, que fica assim na captura de tela a seguir

App de menu final com os problemas corrigidos
App de menu final com os problemas corrigidos

Use os passos a seguir ao abordar um problema de layout. Para ajudar a lembrar, use a sigla COIN. Quem criou esse termo? Eu, agora mesmo.

  1. Verifique a mensagem de erro no console de debug para identificar o tipo de erro e o widget que causou o erro.

  2. Abra o Layout Explorer para visualizar um widget Flex e seus filhos.

  3. Inspecione o tamanho e as constraints do widget que causou o erro e de seu pai/filhos com o Details Tree.

  4. Volte ao seu código e corrija o problema.

O ideal é acompanhar o restante do artigo no seu próprio computador. Então, abra seu editor de texto ou IDE favorito e vamos juntos nessa aventura!

  1. Crie um novo projeto Flutter chamado menu.
bash
$ flutter create menu
  1. Substitua o conteúdo do arquivo lib/main.dart. Cada problema de layout fica separado em sua própria classe Example no código, começando com Example1 no corpo do app. Substitua lib/main.dart pelo código a seguir:
dart
import 'package:flutter/material.dart';
​
void main() {
  runApp(Menu());
}
​
class MenuItem extends StatelessWidget {
  const MenuItem(this.icon, this.itemText);
  final String icon;
  final String itemText;
  @override
  Widget build(BuildContext context) {
    return ListTile(
      leading: Text(
        icon,
        style: TextStyle(
          fontSize: 30.0,
        ),
      ),
      title: Text(itemText),
    );
  }
}
​
class Menu extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: Scaffold(
        appBar: AppBar(
          title: Text('Menu Demo'),
        ),
        body: Padding(
          padding: EdgeInsets.all(20.0),
          child: Column(
            children: [
              // Modify code here
              Example1(),
            ],
          ),
        ),
      ),
    );
  }
}
​
// Problem 1: Overflow error
class Example1 extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: EdgeInsets.only(bottom: 30.0),
      child: Row(
        children: [
          Text(
            'Explore the restaurant\'s delicious menu items below!',
            style: TextStyle(
              fontSize: 18.0,
            ),
          ),
        ],
      ),
    );
  }
}
​
// Problem 2: Viewport was given unbounded height error
class Example2 extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ListView(
      children: [
        MenuItem('🍔', 'Burger'),
        MenuItem('🌭', 'Hot Dog'),
        MenuItem('🍟', 'Fries'),
        MenuItem('🥤', 'Soda'),
        MenuItem('🍦', 'Ice Cream'),
      ],
    );
  }
}
​
// Problem 3: Invisible VerticalDivider
class Example3 extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        RaisedButton(
          onPressed: () {
            print('Pickup button pressed.');
          },
          child: Text(
            'Pickup',
          ),
        ),
        // This widget is not shown on screen initially.
        VerticalDivider(
          width: 20.0,
          thickness: 5.0,
        ),
        RaisedButton(
          onPressed: () {
            print('Delivery button pressed.');
          },
          child: Text(
            'Delivery',
          ),
        )
      ],
    );
  }
}
  1. Execute o app.

  2. Abra o Dart DevTools.

Problema de layout 1: erro de overflow

Quando você executa o app, vê uma caixa listrada em diagonal, amarela e preta, no fim da linha, parecida com fita de isolamento:

Isso significa que há um erro de overflow — o erro de layout mais comum no Flutter. Agora, vamos seguir os passos de depuração para identificar o problema e encontrar a correção certa.

1. Verifique a mensagem de erro no console.

Erro de overflow no Debug Console
Erro de overflow no Debug Console

Primeiro, identifique qual widget está causando o problema. A mensagem de erro indica que o Row na linha 54 de main.dart está causando o problema. Como Row é um widget Flex (o que significa que Row estende a classe Flex), você pode examiná-lo com o Layout Explorer.

2. Abra o Layout Explorer.

Vá até o DevTools e abra a aba Layout Explorer.

Erro de overflow no Layout Explorer
Erro de overflow no Layout Explorer

Clique em Row. (Os números na imagem correspondem aos passos a seguir.)

  1. Faixas vermelhas aparecem na parte inferior, indicando que algo está errado. Ao observar melhor as faixas, você percebe que Text (largura = 447) é mais largo que o widget pai, Row (largura = 335), causando o erro de overflow.

  2. Você precisa de uma forma de dizer ao Text que ele só pode ter a largura do Row e não mais que isso. Tente ajustar o flex do Text para 1. (Isso é parecido com envolver o Text com Expanded.) Como resultado, o Text encolhe, e as faixas vermelhas desaparecem. Pronto, parece corrigido. Não exatamente! Você ainda precisa atualizar o código, porque a ferramenta não mexe no seu código. Ela só mostra o que aconteceria se você mudasse algumas propriedades de layout.

Observação: você pode se perguntar por que nem todos os filhos de Row e Column são Expanded por padrão? A equipe do Flutter tomou essa decisão de design. Se todos os filhos fossem Expanded por padrão, isso criaria outros problemas de layout, como alguns filhos ficando espremidos demais ou esticados demais.

3. Inspecione o tamanho e as constraints com o Details Tree. Neste caso, você pode pular esta etapa, porque o problema já foi identificado.

4. Volte ao código e corrija.

Envolva o Text com Expanded usando a refatoração inteligente do VS Code (método semelhante em outros editores)
Envolva o Text com Expanded usando a refatoração inteligente do VS Code (método semelhante em outros editores)

Envolva o Text com Expanded. O flex padrão é 1, então você não precisa especificar essa propriedade.

Problema de layout 2: erro de altura não limitada

Vamos para o próximo exemplo substituindo Example1() dentro da Column por Example2() e fazendo hot reload.

dart
Column(
  children: [
    // Modify code here
    Example2(),
  ],
)

Nada aparece no app, apesar de ter um ListView com vários itens de menu na classe Example2:

O que está acontecendo?

1. Verifique a mensagem de erro no console.

Erro de altura não limitada no Debug Console
Erro de altura não limitada no Debug Console

ListView na linha 72 de main.dart está causando o erro “Vertical viewport was given unbounded height”. À primeira vista, os termos vertical viewport e unbounded não são claros, então continue para o próximo passo.

2. Abra o Layout Explorer.

Volte ao DevTools e abra a aba Layout Explorer.

O Layout Explorer não exibe os netos dos widgets Flex.
O Layout Explorer não exibe os netos dos widgets Flex.

Atualize a árvore clicando no ícone de atualizar no topo. Nada aparece depois de clicar em ListView porque o Layout Explorer só oferece suporte aos widgets Flex e aos seus filhos diretos. Curiosamente, clicar em Example2 e em Column também não resolve — o Layout Explorer continua em branco. Passe para o próximo passo.

3. Inspecione o tamanho e as constraints com o Details Tree.

Constraints e tamanho do ListView no Details Tree
Constraints e tamanho do ListView no Details Tree

Expanda o primeiro ListView de renderObject, que contém as informações para pintar o widget.

  1. O texto laranja indica que o tamanho está ausente — não é de se estranhar que o ListView não apareça no app.

  2. Depois de olhar a propriedade constraints, note que a constraint de altura está listada como infinity. A mensagem de erro agora faz mais sentido. ListView é um “viewport” recebendo uma altura não limitada — em outras palavras, infinita — na direção de rolagem.

As constraints são passadas do widget pai. Então, aqui está um resumo de como os widgets determinam suas constraints:

Column: ocupe quanta altura quiser.

ListView: Tudo bem, vou ocupar todo o espaço.

Column: Epa, mas isso é tipo infinito, cara.

E os widgets não sabem o que fazer … o tamanho não pode ser determinado porque ListView quer altura infinita, o que não pode ser representado na tela.

Observação: por que Column simplesmente não limita a altura de seus filhos à própria altura? Você pode acabar numa situação em que o primeiro filho ocupa todo o espaço, forçando o segundo filho a ter altura 0. E você não saberia disso de imediato, porque nenhum erro é lançado.

4. Volte ao seu código e corrija.

dart
class Example2 extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Expanded(
      child: ListView(
        ...
      ),
    );
  }
}

Lembre-se de antes que envolver um widget com Expanded dá a ele uma constraint limitada ao longo do eixo principal do pai (largura para Row, altura para Column). Nesse caso, o pai é Column, então Expanded fornece uma constraint de altura. Envolva o ListView com Expanded e faça hot reload para ver a lista aparecer no app.

Problema de layout 3: VerticalDivider invisível

Agora, substitua Example2() no Column por Example3().

dart
Column(
  children: [
    // Modify code here
    Example3(),
  ],
)

Dê uma olhada atenta na classe Example3 no código. Note que o VerticalDivider existe, mas só dois botões aparecem no app depois do hot reload:

Por que o VerticalDivider está invisível?

1. Verifique a mensagem de erro no console. Você não recebeu nenhuma mensagem de erro desta vez. Continue para o próximo passo.

2. Abra o Layout Explorer. Volte ao DevTools e clique na aba Layout Explorer.

VerticalDivider no Layout Explorer
VerticalDivider no Layout Explorer

Depois de atualizar a árvore, clique em VerticalDivider e role até o lado direito do Layout Explorer. Observe que a largura e a altura do VerticalDivider não têm constraints.

  1. Note que a altura do VerticalDivider é 0, o que explica por que ele não é exibido no app.

  2. Ajuste o flex para 1, como fez antes. A altura continua 0. Envolver um VerticalDivider com Expanded não vai resolver neste caso, porque Expanded fornece uma constraint de largura, e não de altura.

  3. A próxima coisa que você pode tentar é esticar a altura do divider até a altura dos botões elevados, então defina o alinhamento do eixo transversal como stretch. A altura continua 0, então passe para o próximo passo.

3. Inspecione o tamanho e as constraints com o Details Tree.

Inspecionando o Row e seus filhos usando o Details Tree
Inspecionando o Row e seus filhos usando o Details Tree
  1. Abra o primeiro renderObject em VerticalDivider. A propriedade constraints indica que o widget não tem constraints de largura nem de altura, o que corresponde ao que o Layout Explorer exibe. Mas, em additionalConstraints, a largura é 20 (como definida explicitamente no código de exemplo), mas a altura ainda não tem constraints. A largura não é o problema aqui, então vamos focar na altura.

  2. Suba para o widget pai, Row, e abra o renderObject para ver que Row também não tem constraint de altura.

Por quê?

A coisa mais importante a lembrar é que as constraints são repassadas para os filhos:

Column diz a Row: escolha a altura que quiser.

Row diz a VerticalDivider: escolha a largura que quiser. Como Column me disse para escolher a minha altura, você também pode escolher a sua própria altura.

VerticalDivider: a propriedade width é passada, então minha largura é 20. Eu posso escolher minha altura, então vou usar 0 como padrão.

4. Volte ao seu código e corrija.

dart
class Example3 extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      height: 50.0,
      child: Row(
        ...
      ),
    );
  }
}

Para que VerticalDivider tenha altura, é preciso fornecer uma constraint de altura. Envolva Row em SizedBox e defina uma altura fixa de 50.0. Isso força Row a passar uma constraint de altura para o VerticalDivider.

Hot reload. Pronto! VerticalDivider aparece na tela.

Observação: VerticalDivider se comporta de forma diferente de ListView por causa de suas definições únicas. Quando recebem a instrução de escolher a própria altura, ListView quer ser o mais alto possível, enquanto VerticalDivider quer ser o mais baixo possível. Mas ambos precisam de uma constraint de altura para aparecer corretamente no app!

Agora, vamos juntar o código corrigido dos 3 exemplos dentro de Column:

dart
Column(
  children: [
    // Modify code here
    Example1(),
    Example2(),
    Example3(),
  ],
)

Hot reload. Parabéns, você concluiu o app de menu!

Resumo

Ao longo deste tutorial, você aprendeu:

  • As constraints são repassadas pela árvore de widgets.

  • Expanded fornece constraints limitadas (bounded) para o filho de um Row ou Column.

  • O Flutter Inspector é o seu melhor amigo quando se trata de problemas de layout.

Para saber mais, confira entendendo constraints no flutter.dev.

Bom debugging!

Sobre a autora: Katie é prestes a se formar (rising senior) na University of Michigan, cursando Ciência da Computação. Atualmente ela é estagiária na equipe de Flutter Developer Relations, ajudando pessoas desenvolvedoras a aprender e criar apps incríveis. Para ver o que ela está fazendo, visite o GitHub e o LinkedIn.

Mais do Flutter