Route — o que é, tipos e criação de rotas no Flutter

O que é Route no Flutter

Route é a base do sistema de navegação do Flutter. Cada tela que o usuário vê em um aplicativo é representada por um objeto Route localizado na pilha do Navigator. Route abstrai a tela do código de controle: Navigator adiciona e remove Route, enquanto dentro de Route está a interface que o usuário vê. Esta arquitetura separa a responsabilidade entre navegação e exibição.

Ao contrário da simples substituição de widgets, Route fornece serviços indisponíveis para widgets comuns: ModalBarrier (escurecimento do fundo quando um diálogo está aberto), controle de animação de entrada e saída, manipulação do botão físico de voltar no Android e integração com animação Hero para transições suaves entre telas.

De acordo com Flutter Cookbook (2026), Route é um elemento chave para animação Hero: um widget Hero em uma Route anima automaticamente a transição para um widget Hero na próxima Route, criando um efeito de elemento “voando”. Isso é possível precisamente porque Route mantém ambas as telas no Overlay durante a animação.

Route como bloco de construção da navegação

Route é a base tanto para aplicativos móveis simples (através do Navigator 1.0) quanto para cenários complexos com links profundos (Navigator 2.0). No Navigator 2.0, Route representa uma Page que o RouterDelegate converte a partir da configuração de rota. Portanto, entender Route é essencial para trabalhar com qualquer sistema de navegação do Flutter — independentemente da abordagem ou pacote escolhido.

Tipos de Route: MaterialPageRoute e CupertinoPageRoute

Flutter fornece várias implementações embutidas de Route, cada uma adaptando o comportamento a uma plataforma específica. Escolher o tipo correto de Route afeta a experiência do usuário: animação Material no Android e animação Cupertino no iOS criam a sensação de um aplicativo “nativo”.

MaterialPageRoute: padrão para Android

MaterialPageRoute é a implementação de Route mais usada. Ela anima a nova tela entrando de baixo para cima com aparecimento gradual. Ao sair, a tela anima de cima para baixo, retornando à sua posição original. A barra de ferramentas (AppBar) e o corpo da tela animam separadamente, criando um efeito de hierarquia.

CupertinoPageRoute: estilo de navegação iOS

CupertinoPageRoute imita o UINavigationController do iOS. A nova tela entra pela direita, cobrindo a anterior. A característica chave é o suporte ao gesto interativo de deslizar para trás, implementado através de CupertinoBackGestureDetector. Este gesto é manipulado mesmo durante a animação, proporcionando um comportamento natural familiar aos usuários de iPhone.

Ciclo de vida da Route: da criação ao descarte

Route tem seu próprio ciclo de vida, que difere do ciclo de vida de um StatefulWidget comum. Compreender este ciclo é necessário para a inicialização adequada de dados, inscrições em streams e liberação de recursos ao fechar uma tela.

Estágios do ciclo de vida da Route

O ciclo de vida da Route consiste em quatro estágios principais. Transição — Route é criada e animada na entrada (didPush é chamado). Ativo — Route é totalmente exibida e interage com o usuário. Inativo — outra Route cobre a atual (diálogo, folha inferior), mas a Route permanece na pilha. Descartado — Route é removida da pilha e destruída, didPop e dispose são chamados.

Os métodos do ciclo de vida de Route podem ser sobrescritos em uma implementação personalizada. Por exemplo, didPop é chamado quando Route é removida da pilha — aqui você pode salvar dados de rascunho. didChangeNext é chamado quando a próxima Route na pilha mudou — útil para atualizar a UI quando o histórico de navegação muda.

De acordo com Flutter API Route.didPop (2026), é importante não confundir o ciclo de vida da Route com o ciclo de vida do State dentro da Route. StatefulWidget dentro de Route tem seu próprio initState e dispose, que são chamados durante os estágios de Transição e Descartado respectivamente. Route vive mais que seu State interno — Route permanece no Overlay mesmo quando seus widgets estão temporariamente ocultos por outra Route.

Passagem de dados via Route entre telas

Route fornece mecanismos para passar dados tanto na entrada (quando criada) quanto na saída (quando concluída). A passagem adequada de dados via Route elimina a necessidade de variáveis globais e InheritedWidget, tornando a navegação type-safe e previsível.

Para passar dados para uma nova tela, use o construtor do widget receptor ou o parâmetro arguments no Navigator.pushNamed. Dentro de Route, os dados são acessíveis através de RouteSettings.arguments, que é armazenado no objeto Route. Esta abordagem funciona para todos os tipos de Route — MaterialPageRoute, CupertinoPageRoute e implementações personalizadas.

Para retornar dados, use o segundo argumento de Navigator.pop(context, result). Navigator.push retorna Future, que é concluído com o valor passado para pop. Se pop for chamado sem argumento, Future é concluído com null. Este mecanismo é análogo ao startActivityForResult no Android e ao completion handler no iOS, mas implementado através de Dart Futures.

Passagem de dados através do construtor de Route

Ao chamar Navigator.push diretamente com MaterialPageRoute, os dados são passados através do construtor da tela de destino. MethodChannel não é usado — esta é uma interação pura de Dart. Esta abordagem é preferível para passagem type-safe de objetos complexos.

Exemplo de criação de Route personalizado

Vamos ver um exemplo de criação de um Route personalizado com sua própria animação e passagem de dados. PageRouteBuilder permite definir animações de entrada e saída com controle total sobre a curva de animação e duração.

// Route personalizado com animação de deslizamento
Navigator.push(context, PageRouteBuilder(
  pageBuilder: (context, animation, secondaryAnimation) {
    return DetailPage(productId: '42');
  },
  transitionsBuilder: (context, animation, secondaryAnimation, child) {
    const begin = Offset(0.0, 0.3);
    const end = Offset.zero;
    final tween = Tween(begin: begin, end: end);
    final offsetAnimation = animation.drive(tween);
    return SlideTransition(position: offsetAnimation, child: child);
  },
  transitionDuration: const Duration(milliseconds: 400),
));

// Retornar dados da tela
ElevatedButton(
  onPressed: () => Navigator.of(context).pop({'selected': true, 'id': '42'}),
  child: const Text('Selecionar'),
);

// Obter resultado na tela de chamada
final result = await Navigator.push(context, MaterialPageRoute(
  builder: (context) => const SelectionPage(),
));
if (result != null) {
  print('Selecionado: ${result['selected']}');
}

No exemplo, PageRouteBuilder define uma animação personalizada de deslizamento de baixo com transparência. transitionDuration define a velocidade da animação. O código também demonstra a passagem de resultado: a tela de detalhe retorna um Map com a seleção do usuário, e a tela de chamada recebe estes dados através do Future do push. Route garante isolamento completo: rascunhos na tela de detalhe não afetam o estado da lista.