Navigator: o que é, gerenciamento de telas no Flutter

O que é Navigator no Flutter

Navigator é um widget que gerencia uma pilha de objetos Route, implementando a navegação entre telas em uma aplicação Flutter. Cada chamada a push coloca um novo Route no topo da pilha, pop remove o Route superior e retorna à tela anterior. O MaterialApp cria automaticamente um Navigator para toda a aplicação, tornando-o acessível através de Navigator.of(context).

Diferente do StatefulWidget, onde a substituição de conteúdo ocorre via setState dentro de um único widget, o Navigator opera com telas completas que têm seu próprio ciclo de vida. Cada Route na pilha é um estado isolado com seu próprio BuildContext, prevenindo vazamentos de memória e simplificando o gerenciamento de dependências. Quando pop é chamado, o Route não utilizado é destruído, liberando recursos.

De acordo com o Guia de Navegação do Flutter (2026), o Navigator evoluiu de uma API imperativa (Navigator 1.0) para uma declarativa (Navigator 2.0). O Navigator 1.0 usa métodos push/pop diretamente, o que é conveniente para cenários simples. O Navigator 2.0 (Router) é adequado para aplicações com links profundos, navegação adaptativa e roteamento web.

Como o Navigator funciona internamente

Internamente, o Navigator usa Overlay — um widget especial que exibe Routes um sobre o outro. Cada Route cria sua própria posição no Overlay com um z-index correspondente à sua profundidade na pilha. Isso explica por que ao chamar push, a nova tela anima sobre a anterior, e ao chamar pop, a tela anterior já está pronta para exibição: ela não foi destruída, mas permaneceu no Overlay abaixo da nova.

Para animações de transição, o Navigator usa PageTransitionsTheme, que pode ser sobrescrito em ThemeData. Animações específicas da plataforma são definidas via CupertinoPageRoute para iOS (deslizar da direita) e MaterialPageRoute para Android (deslizar de baixo). O Navigator seleciona automaticamente a animação correta ao usar PlatformRoute.

Métodos do Navigator: push, pop e pushReplacement

O Navigator fornece um conjunto de métodos para gerenciar a pilha de Routes. Cada método resolve uma tarefa específica de navegação — desde uma transição simples até a substituição completa do histórico de telas. Vamos revisar os principais métodos com exemplos de uso.

Push e Pop: operações básicas

O método push recebe um Route e retorna um Future com o resultado passado durante pop. Isso permite receber dados da tela para a qual navegou. Por exemplo, uma tela de seleção de data pode retornar um DateTime através de Navigator.pop(context, selectedDate). O método pop sem argumentos retorna null, com um argumento — passa o valor para a tela chamadora.

PushReplacement: substituição de tela

pushReplacement substitui o Route atual por um novo, removendo o route atual da pilha. Isso é crítico para cenários onde o usuário não deve poder retornar à tela anterior. Um exemplo típico — a tela de login: após login bem-sucedido, a tela atual é substituída pela tela principal, e o botão Voltar não retorna ao formulário de login.

Rotas nomeadas e onGenerateRoute

O Navigator suporta navegação por rotas nomeadas através do método pushNamed. Em vez de criar um Route diretamente, o desenvolvedor especifica um identificador de string, e o Navigator cria automaticamente o Route com base na configuração no MaterialApp. Isso simplifica o código e centraliza a definição de rotas em um só lugar.

As rotas nomeadas são definidas através da propriedade routes no MaterialApp, onde cada chave é uma string de caminho e o valor é uma função que retorna um Widget. Para rotas dinâmicas (com parâmetros), usa-se onGenerateRoute — um callback que recebe RouteSettings e retorna um Route. Isso permite passar argumentos através do parâmetro arguments e implementar navegação profunda.

De acordo com o Flutter Cookbook (2026), a passagem de argumentos via pushNamed é feita com o parâmetro arguments: Object?. A tela receptora extrai os argumentos através de ModalRoute.of(context)!.settings.arguments, proporcionando transferência de dados com segurança de tipos sem variáveis globais ou InheritedWidget.

Tratamento de rotas desconhecidas

A propriedade onUnknownRoute no MaterialApp trata casos em que pushNamed é chamado com uma rota inexistente. Isso é útil para exibir uma tela 404 ou redirecionar para a página inicial. Em combinação com onGenerateRoute, garante cobertura completa de todos os cenários de navegação possíveis.

Navigator 2.0 e navegação declarativa com Router

Navigator 2.0 (também conhecido como API Router) é uma abordagem declarativa à navegação introduzida no Flutter 2.0. Diferente do Navigator 1.0 imperativo, onde o desenvolvedor chama push/pop, o Router gerencia a navegação através do estado, sincronizando automaticamente a URL do navegador com a tela atual. Isso é especialmente importante para aplicações web e versões desktop.

A arquitetura do Navigator 2.0 consiste em três componentes principais: RouteInformationParser analisa a URL em uma configuração de rota, RouterDelegate transforma a configuração em uma lista de Routes, e BackButtonDispatcher trata o botão Voltar do sistema. Essa arquitetura torna a navegação completamente previsível e testável.

Para simplificar o trabalho com Navigator 2.0, existem pacotes wrapper: go_router (recomendado pelo Google), auto_route e beamer. O go_router fornece um DSL declarativo para definir rotas com suporte a navegação aninhada, redirecionamentos e links profundos sem implementar manualmente o RouterDelegate. De acordo com pub.dev (2026), o go_router é usado em 35% dos novos projetos Flutter que preferem uma abordagem declarativa.

Exemplo de navegação em uma aplicação Flutter

Considere um exemplo do Navigator com rotas nomeadas e passagem de dados entre telas. O código demonstra uma tela de lista de produtos, a transição para uma tela de detalhes e o retorno com um resultado.

// Route configuration in MaterialApp
MaterialApp(
  initialRoute: '/',
  onGenerateRoute: (RouteSettings settings) {
    if (settings.name == '/') {
      return MaterialPageRoute(
        builder: (context) => const ProductListPage(),
      );
    }
    if (settings.name == '/product') {
      final productId = settings.arguments as String;
      return MaterialPageRoute(
        builder: (context) => ProductDetailPage(productId: productId),
      );
    }
    return MaterialPageRoute(
      builder: (context) => const NotFoundPage(),
    );
  },
)

// Navigation with data passing
final result = await Navigator.pushNamed(
  context,
  '/product',
  arguments: 'product_42',
);

// Getting data on the receiving screen
final args = ModalRoute.of(context)!.settings.arguments as String;

// Replace screen after login
Navigator.pushReplacementNamed(context, '/home');

// Clear stack to main screen
Navigator.pushNamedAndRemoveUntil(
  context,
  '/home',
  (route) => false,
);

No exemplo, Navigator.pushNamed passa o ID do produto para a tela de detalhes. Ao retornar via Navigator.pop(context, updatedProduct), a tela chamadora recebe os dados atualizados na variável result. pushReplacementNamed substitui a tela atual após a autorização, e pushNamedAndRemoveUntil com a condição (route) => false limpa completamente a pilha, impedindo a navegação de volta para telas anteriores.