Skip to content

5. Roteamento

Um aplicativo tem várias telas. O [Flutter] as gerencia por meio de [Navigator]: uma pilha de telas, na qual uma nova tela ([Navigator.push]) é empilhada e da qual ela é desempilhada ([Navigator.pop], ou o botão Voltar do celular). Isso basta para um pequeno aplicativo móvel. Mas, assim que você quer URLs (/doctors/2) — ou seja, telas que podem ser referenciadas, abertas a partir de um link, recarregadas na web e protegidas por guards —, usa-se um roteador. O pacote [go_router], mantido pela equipe do [Flutter] e recomendado em sua documentação, é o mais utilizado.

5.1. Exemplo 17: o roteador

5.1.1. Os dados

1
2
3
4
5
6
7
8
// dados "fixos no código", para não depender de um servidor neste exemplo
typedef Doctor = ({int id, String title, String firstName, String lastName, String specialty});

const doctors = <Doctor>[
  (id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner'),
  (id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician'),
  (id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner'),
];

Dados “fixos no código”, para não depender de um servidor neste exemplo: uma lista de records.

5.1.2. As rotas

// =========================================================================
// lib/ex17_router/routes.dart - as ROTAS do aplicativo
// -------------------------------------------------------------------------
// Um aplicativo tem várias telas ("páginas"). O ROTEADOR associa um
// ENDEREÇO (um caminho, como na web: /doctors/2) a uma tela. O Flutter
// fornece o Navigator (uma PILHA de telas: empilhamos, desempilhamos); o
// pacote go_router, mantido pela equipe do Flutter, acrescenta a ele os
// endereços: links, parâmetros, o botão Voltar do navegador
// e endereços digitados à mão na web, o botão Voltar do Android.
//   '/doctors/:id'   :id é um parâmetro (/doctors/2 -> id = "2");
//   ShellRoute       um "shell" comum (barra superior, barra de
//                    navegação inferior) ao redor das telas das suas rotas;
//   redirect         um redirecionamento: o endereço antigo leva ao novo;
//   errorBuilder     a tela de um endereço que não corresponde a nenhuma rota.
// =========================================================================

import 'package:go_router/go_router.dart';

import 'shell.dart';
import 'pages/home.dart';
// carregamento TARDIO: na web, o código desta página só é baixado
// na primeira visita (flutter build web gera um arquivo separado para ele)
import 'pages/about.dart' deferred as about;
import 'pages/deferred_loading.dart';
import 'pages/doctor_detail.dart';
import 'pages/doctor_list.dart';
import 'pages/not_found_page.dart';
import 'pages/search.dart';

final router = GoRouter(
  // o endereço inicial (em um celular: não há barra de endereço)
  initialLocation: '/',
  routes: [
    ShellRoute(
      // child: a tela da rota filha atual, colocada DENTRO do shell
      builder: (context, state, child) => Shell(child: child),
      routes: [
        GoRoute(path: '/', builder: (context, state) => const Home()),
        GoRoute(
          path: '/doctors',
          builder: (context, state) => const DoctorList(),
          // uma rota ANINHADA: /doctors/2
          routes: [
            GoRoute(
              path: ':id',
              // pathParameters: os parâmetros do caminho, sempre STRINGS
              builder: (context, state) => DoctorDetail(id: state.pathParameters['id']!),
            ),
          ],
        ),
        GoRoute(
          path: '/search',
          // uri.queryParameters: os parâmetros após o ? (/search?q=pediatrician)
          builder: (context, state) => Search(q: state.uri.queryParameters['q'] ?? ''),
        ),
        GoRoute(
          path: '/about',
          builder: (context, state) =>
              DeferredLoading(load: about.loadLibrary, builder: () => about.About()),
        ),
        // um redirecionamento: a rota não tem tela, ela retorna outro endereço
        GoRoute(path: '/physicians', redirect: (context, state) => '/doctors'),
      ],
    ),
  ],
  errorBuilder: (context, state) => NotFoundPage(address: state.uri.toString()),
);

Uma rota associa um caminho a uma tela.

  • Linha 23: uma importação adiada ([deferred]). Na web, o código desta página é compilado em um arquivo separado, que só é baixado na primeira visita à página ([about.loadLibrary()]). Em um celular, todo o código já está no aplicativo: [loadLibrary()] termina imediatamente;
  • linhas 30–32: o roteador, um objeto chamado [GoRouter], é criado uma única vez, fora de qualquer widget. [initialLocation]: o endereço inicial (em um celular, não há barra de endereços para exibi-lo);
  • linhas 34–36: uma [ShellRoute] é um contêiner comum a várias telas: a barra superior e a barra de navegação inferior. Seu [builder] recebe [child] — a tela da rota atual — e a coloca dentro do shell. Isso equivale às rotas aninhadas e ao [<Outlet />] do [React Router];
  • linha 38: uma rota — seu caminho — e uma função que gera sua tela. [state] ([GoRouterState]) descreve a navegação atual: o endereço e seus parâmetros;
  • linhas 40–47: a lista de médicos e uma rota aninhada: [':id'] sob ['/doctors'] resulta no caminho [/doctors/:id], em que [:id] é um parâmetro ([/doctors/2]: [id] é igual a ["2"]). [state.pathParameters] fornece os parâmetros do caminho, que são sempre strings;
  • linhas 52–54: [state.uri] é o endereço completo; [queryParameters] contém os parâmetros que vêm depois de [?] ([/search?q=pediatrician]);
  • linhas 57–59: a página carregada sob demanda pelo widget [DeferredLoading] (tratado mais adiante);
  • linha 62: um redirecionamento — a rota não tem tela; sua função [redirect] devolve outro endereço, para o qual a navegação é redirecionada;
  • linha 66: a tela de um endereço que não corresponde a nenhuma rota.

5.1.3. Inicialização

// =========================================================================
// lib/ex17_router/main.dart
// -------------------------------------------------------------------------
// MaterialApp.router: o aplicativo não tem mais UMA tela inicial (home),
// o roteador decide a tela, a partir do endereço.
// usePathUrlStrategy(): na web, endereços "limpos" (/doctors/2)
// em vez da forma padrão (/#/doctors/2). Sem efeito em outras plataformas.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_web_plugins/url_strategy.dart';

import 'routes.dart';

void main() {
  usePathUrlStrategy();
  runApp(
    MaterialApp.router(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      routerConfig: router,
    ),
  );
}
  • linha 16: na web, endereços “limpos” ([/doctors/2]) em vez da forma padrão ([/#/doctors/2]). Não tem efeito em um celular;
  • Linhas 17–21: [MaterialApp.router]: o aplicativo não exibe mais UMA tela inicial ([home]); o roteador determina a tela com base no endereço.

5.1.4. O shell do aplicativo

// =========================================================================
// lib/ex17_router/shell.dart - o "shell" do aplicativo
// -------------------------------------------------------------------------
// A barra superior, a barra de navegação inferior e, entre as duas,
// a tela da rota atual (child).
//   - GoRouterState.of(context).uri : o endereço atual;
//   - context.go('/doctors')        : ir para um endereço. A pilha de
//     telas é SUBSTITUÍDA pela deste endereço (uma aba);
//   - context.push('/doctors/2')    : EMPILHAR uma tela sobre a
//     tela atual; o botão Voltar (ou context.pop()) a desempilha.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

// as abas: (caminho, rótulo, ícone)
const tabs = [
  ('/', 'Home', Icons.home),
  ('/doctors', 'Doctors', Icons.people),
  ('/search?q=general practitioner', 'Search', Icons.search),
  ('/about', 'About', Icons.info),
];

class Shell extends StatelessWidget {
  final Widget child;

  const Shell({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    final address = GoRouterState.of(context).uri;
    // a aba ativa: aquela cujo caminho é o início do endereço atual
    int active = 0;
    for (final (i, (path, _, _)) in tabs.indexed) {
      final start = Uri.parse(path).path;
      if (start != '/' && address.path.startsWith(start)) active = i;
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Example 17 - the router')),
      body: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          Container(
            color: Colors.grey.shade100,
            padding: const EdgeInsets.all(8),
            // Uri.decodeFull: %20 volta a ser um espaço
            child: Text(
              'current address: ${Uri.decodeFull(address.toString())}',
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          Expanded(
            child: Padding(padding: const EdgeInsets.all(16), child: child),
          ),
        ],
      ),
      // NavigationBar: a barra de abas inferior, típica de um celular
      bottomNavigationBar: NavigationBar(
        selectedIndex: active,
        onDestinationSelected: (i) => context.go(tabs[i].$1),
        destinations: [
          for (final (_, label, icon) in tabs) NavigationDestination(icon: Icon(icon), label: label),
        ],
      ),
    );
  }
}
  • Linhas 17–21: as abas: records (caminho, rótulo, ícone);
  • linha 31: o endereço atual. [GoRouterState.of(context)] é uma leitura de dados herdados (veja o exemplo 14): o shell é reconstruído a cada navegação;
  • linhas 33–36: a aba ativa: aquela cujo caminho é o início do endereço atual. [for (final (i, (path, _, _)) in tabs.indexed)] decompõe tanto o par (índice, aba) quanto o record da aba, mantendo apenas o caminho ([_]: “ignorado”);
  • linhas 48–49: o endereço atual, exibido ([Uri.decodeFull]: [%20] volta a ser um espaço);
  • linhas 53–54: a tela da rota atual;
  • linhas 59–63: a barra de abas inferior ([NavigationBar]), típica de um aplicativo móvel. [onDestinationSelected] recebe o índice da aba tocada; [context.go(path)] leva ao seu endereço. [tabs[i].$1]: o primeiro campo de um record posicional.

Duas formas de navegar, com o [go_router]:

  • [context.go('/doctors')]: ir a um endereço. A pilha de telas é substituída pela descrita por esse endereço. É o que se faz para trocar de aba;
  • [context.push('/doctors/2')]: empilhar a tela desse endereço sobre a tela atual. O botão Voltar do celular (ou [context.pop()]) a desempilha, e você volta para onde estava. É assim que se “entra” em uma view de detalhes.

5.1.5. As páginas

// lib/ex17_router/pages/home.dart
// Title: o título da aba do navegador (web) ou do aplicativo na
// lista de aplicativos recentes (Android), enquanto a página é exibida
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

class Home extends StatelessWidget {
  const Home({super.key});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'Home',
      color: Colors.indigo,
      child: ListView(
        children: [
          const Text(
            'Welcome. Touch the tabs: the screen changes, and so does its address. On the web, '
            "the address is displayed in the browser's bar, the Back and Forward buttons "
            'work, as well as the reload (F5) of any page.',
          ),
          const SizedBox(height: 16),
          // links para endereços específicos
          Wrap(
            spacing: 8,
            children: [
              OutlinedButton(onPressed: () => context.go('/physicians'), child: const Text('/physicians (redirect)')),
              OutlinedButton(onPressed: () => context.go('/unknown-page'), child: const Text('Broken link')),
            ],
          ),
        ],
      ),
    );
  }
}

Cada página coloca um widget [Title]: seu título é o da aba do navegador (na web) ou o do aplicativo na lista de aplicativos recentes (no [Android]), enquanto a página estiver exibida. Dois botões levam a URLs específicas: o redirecionamento [/physicians], e uma URL que não existe.

// lib/ex17_router/pages/doctor_list.dart - links com um parâmetro
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../data.dart';

class DoctorList extends StatelessWidget {
  const DoctorList({super.key});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'Doctors',
      color: Colors.indigo,
      child: ListView(
        children: [
          for (final m in doctors)
            ListTile(
              title: Text('${m.title} ${m.firstName} ${m.lastName}'),
              trailing: const Icon(Icons.chevron_right),
              // push: a tela do médico é EMPILHADA; o botão Voltar retorna aqui
              onTap: () => context.push('/doctors/${m.id}'),
            ),
        ],
      ),
    );
  }
}
  • Linha 22: tocar em um médico empilha sua tela na pilha.
// =========================================================================
// lib/ex17_router/pages/doctor_detail.dart - uma página com um parâmetro
// -------------------------------------------------------------------------
// O roteador lhe passa o parâmetro :id do caminho, uma STRING ("2").
// context.pop() desempilha a tela (como o botão Voltar); context.go()
// leva a outro endereço. Se formos de /doctors/1 para /doctors/2,
// o Flutter reutiliza a mesma tela, simplesmente reconstruída com outro id.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../data.dart';

class DoctorDetail extends StatelessWidget {
  final String id;

  const DoctorDetail({super.key, required this.id});

  @override
  Widget build(BuildContext context) {
    // int.tryParse: null se id não for um número; firstWhere... orElse: não encontrado
    final number = int.tryParse(id);
    final found = doctors.where((m) => m.id == number);
    if (found.isEmpty) {
      return Text('Doctor no. $id does not exist.', style: const TextStyle(color: Colors.red));
    }
    final doctor = found.first;
    final next = doctor.id % doctors.length + 1;
    return Title(
      title: '${doctor.firstName} ${doctor.lastName}',
      color: Colors.indigo,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text('${doctor.title} ${doctor.firstName} ${doctor.lastName}', style: Theme.of(context).textTheme.titleLarge),
          Text('Specialty: ${doctor.specialty}'),
          const SizedBox(height: 16),
          Wrap(
            spacing: 8,
            children: [
              OutlinedButton(
                // canPop: há uma tela abaixo? (não, se chegamos
                // diretamente a este endereço, na web)
                onPressed: () => context.canPop() ? context.pop() : context.go('/doctors'),
                child: const Text('Back'),
              ),
              FilledButton(
                // pushReplacement: substitui a tela atual (sem empilhar)
                onPressed: () => context.pushReplacement('/doctors/$next'),
                child: const Text('Next doctor'),
              ),
            ],
          ),
        ],
      ),
    );
  }
}
  • linha 16: o parâmetro de caminho [:id], que o roteador passa ao construtor;
  • linhas 23–26: [int.tryParse]: o ID numérico ou [null]; se um médico não for encontrado, uma mensagem é exibida;
  • linha 45: Voltar: a tela é desempilhada se houver outra abaixo dela ([canPop]); caso contrário (se você chegou diretamente a esse endereço pela web), vai-se para a lista;
  • linha 50: o médico seguinte substitui a tela atual (sem empilhar: o botão Voltar retorna à lista, não ao médico anterior).
// =========================================================================
// lib/ex17_router/pages/search.dart - uma página conduzida pelo endereço
// -------------------------------------------------------------------------
// /search?q=pediatrician: a página é inteiramente descrita pelo seu endereço.
// Na web, ela pode ser adicionada aos favoritos, recarregada, e podemos
// voltar. Pesquisar significa IR ao endereço /search?q=<entrada>:
// a página exibe o que o endereço diz, e nada mais.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../data.dart';

class Search extends StatelessWidget {
  final String q;

  const Search({super.key, required this.q});

  void _search(BuildContext context, String input) {
    // Uri: constrói o endereço, codificando o que for preciso (espaço -> %20)
    context.go(Uri(path: '/search', queryParameters: {'q': input.trim()}).toString());
  }

  @override
  Widget build(BuildContext context) {
    final results = doctors
        .where((m) => '${m.firstName} ${m.lastName} ${m.specialty}'.toLowerCase().contains(q.toLowerCase()))
        .toList();
    return Title(
      title: 'Search',
      color: Colors.indigo,
      child: ListView(
        children: [
          // um campo NÃO controlado, que começa com o valor do endereço;
          // key: ValueKey(q): se o endereço muda (botão Voltar), o Flutter
          // recria o campo, que então assume o novo valor
          TextFormField(
            key: ValueKey(q),
            initialValue: q,
            decoration: const InputDecoration(hintText: 'name or specialty', suffixIcon: Icon(Icons.search)),
            textInputAction: TextInputAction.search,
            onFieldSubmitted: (input) => _search(context, input),
          ),
          const SizedBox(height: 8),
          for (final m in results) ListTile(title: Text('${m.firstName} ${m.lastName} (${m.specialty})')),
          if (results.isEmpty)
            const ListTile(
              title: Text('No result.', style: TextStyle(color: Colors.grey)),
            ),
        ],
      ),
    );
  }
}
  • Linhas 20–22: pesquisar significa IR ao endereço [/search?q=<input>]. [Uri] gera o endereço codificando as informações necessárias (um espaço se torna [%20]). A página é totalmente descrita pelo seu endereço: na web, você pode salvá-la nos favoritos, recarregá-la ou voltar;
  • linhas 38–43: um campo não validado que começa com o valor da URL. [key: ValueKey(q)]: se a URL mudar (botão Voltar do navegador), a chave muda; o [Flutter] recria o campo, que assume o novo valor. [textInputAction: TextInputAction.search]: a tecla Enter do teclado do celular funciona como uma lupa.
// =========================================================================
// lib/ex17_router/pages/deferred_loading.dart
// -------------------------------------------------------------------------
// Uma tela cujo código é carregado sob demanda (import "deferred"):
// load() baixa o código (um Future), builder() constrói a tela
// quando o código chega. Enquanto isso: um indicador de carregamento.
// FutureBuilder reconstrói seu conteúdo quando o Future termina
// (veja o exemplo 19).
// =========================================================================

import 'package:flutter/material.dart';

class DeferredLoading extends StatefulWidget {
  final Future<void> Function() load;
  final Widget Function() builder;

  const DeferredLoading({super.key, required this.load, required this.builder});

  @override
  State<DeferredLoading> createState() => _DeferredLoadingState();
}

class _DeferredLoadingState extends State<DeferredLoading> {
  // o Future é criado UMA vez (e não a cada build)
  late final Future<void> _loading = widget.load();

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: _loading,
      builder: (context, snapshot) => snapshot.connectionState == ConnectionState.done
          ? widget.builder()
          : const Center(child: CircularProgressIndicator()),
    );
  }
}
  • linha 25: o código é carregado e iniciado UMA ÚNICA vez (um campo [late] inicializado na primeira leitura): se fosse iniciado em [build], cada reconstrução o dispararia novamente;
  • Linhas 29–33: [FutureBuilder] reconstrói seu conteúdo quando o [Future] termina: enquanto isso, um indicador de carregamento; depois, a tela (veja o exemplo 19).
// lib/ex17_router/pages/about.dart - uma página carregada sob demanda
// (veja o import "deferred as about" de routes.dart)
import 'package:flutter/material.dart';

class About extends StatelessWidget {
  const About({super.key});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'About',
      color: Colors.indigo,
      child: const Text(
        'On the web, this page was downloaded on the first visit (Network tab '
        'of the developer tools: a main.dart.js_1.part.js file). On a phone, '
        'all the code is already in the application.',
      ),
    );
  }
}
// lib/ex17_router/pages/not_found_page.dart - a tela de endereços desconhecidos
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

class NotFoundPage extends StatelessWidget {
  final String address;

  const NotFoundPage({super.key, required this.address});

  @override
  Widget build(BuildContext context) {
    return Title(
      title: 'Page not found',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Page not found')),
        body: Padding(
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text('No page at the address $address.', style: const TextStyle(color: Colors.red)),
              const SizedBox(height: 16),
              FilledButton(onPressed: () => context.go('/'), child: const Text('Back to home')),
            ],
          ),
        ),
      ),
    );
  }
}

A tela de endereços desconhecidos tem seu próprio [Scaffold]: ele é construído por [errorBuilder], fora do shell.

5.1.6. Execução

A tela inicial; os detalhes de um médico (empilhado: a barra superior não mudou, mas o botão Voltar do celular leva você de volta à lista); a pesquisa; um endereço desconhecido:

Na web ([flutter run -d chrome]), o endereço aparece na barra do navegador, os botões Voltar e Avançar funcionam e você pode digitar um endereço manualmente.

5.2. Exemplo 18: guards de navegação

5.2.1. A sessão

// =========================================================================
// lib/ex18_guards/session.dart - uma sessão SIMULADA (sem servidor)
// -------------------------------------------------------------------------
// O usuário logado precisa ser conhecido pelas TELAS (a barra superior,
// a agenda) e pelos GUARDS do roteador (funções, que não são
// widgets). Ele é guardado em um único objeto, um ChangeNotifier:
//   - um campo privado, o estado;
//   - métodos para lê-lo e modificá-lo;
//   - notifyListeners(): notifica seus inscritos (o roteador, as telas)
//     quando ele muda.
// (O exemplo 23 fará a mesma coisa com um servidor de verdade.)
// =========================================================================

import 'package:flutter/foundation.dart';

enum Role { admin, doctor, user }

typedef User = ({String login, Role role});

// três contas "fixas no código" (senha = login)
const _accounts = {'admin': Role.admin, 'pelissier': Role.doctor, 'martin': Role.user};

class Session extends ChangeNotifier {
  User? _user; // o estado: null, ninguém está logado

  User? get user => _user;

  bool logIn(String login, String password) {
    final role = _accounts[login];
    if (role == null || password != login) {
      return false;
    }
    _user = (login: login, role: role);
    notifyListeners();
    return true;
  }

  void logOut() {
    _user = null;
    notifyListeners();
  }
}

// a única sessão do aplicativo
final session = Session();

O usuário conectado deve ser reconhecido pelas telas (a barra superior, a agenda) e pelos controles do roteador — recursos que não são widgets. Ele é guardado em um único objeto, um [ChangeNotifier] (veja o exemplo 14):

  • linha 24: o status: um usuário ou [null];
  • linhas 28–35: a conexão, simulada: três contas “fixas no código” (senha = login). Ela notifica seus assinantes ([notifyListeners()]);
  • linha 45: a sessão única do aplicativo, uma variável global. (O exemplo 23 fará a mesma coisa com um servidor real.)

5.2.2. Guards e caminhos protegidos

// =========================================================================
// lib/ex18_guards/routes.dart - rotas PROTEGIDAS por guards
// -------------------------------------------------------------------------
// redirect: uma função que o go_router chama ANTES de cada navegação
// (a do GoRouter: para todas as rotas; a de uma GoRoute:
// somente para ela). Ela recebe o estado da navegação (state.uri:
// o endereço solicitado) e retorna:
//   - null: a navegação continua;
//   - um endereço: a navegação é substituída por uma navegação para
//     este endereço.
// refreshListenable: um objeto a ESCUTAR; quando ele notifica uma
// alteração (a sessão: login, logout), o roteador reavalia
// seus guards para a tela atual.
//
// É o equivalente, no lado do cliente, dos guards do NestJS (JwtAuthGuard,
// RolesGuard) - com uma diferença FUNDAMENTAL: um guard de cliente é
// apenas uma comodidade. O aplicativo está nas mãos do usuário, que
// pode modificá-lo à vontade. A proteção real dos dados continua sendo
// a do SERVIDOR (veja o capítulo sobre a caixa-preta).
// =========================================================================

import 'package:go_router/go_router.dart';

import 'shell.dart';
import 'pages/home.dart';
import 'pages/administration.dart' deferred as administration;
import 'pages/schedule.dart';
import 'pages/login.dart';
import '../ex17_router/pages/deferred_loading.dart';
import 'session.dart';

// o guard "login obrigatório": não logado -> para a página de login,
// lembrando para onde o usuário queria ir
String? requireLogin(GoRouterState state) {
  if (session.user == null) {
    return Uri(path: '/login', queryParameters: {'redirect': state.uri.toString()}).toString();
  }
  return null;
}

// o guard "papel obrigatório": uma função que CONSTRÓI um guard
String? Function(GoRouterState) requireRole(Set<Role> roles) {
  return (state) {
    final u = session.user;
    if (u == null || !roles.contains(u.role)) {
      // logado, mas sem o papel certo: de volta à página inicial, com um motivo
      return Uri(path: '/', queryParameters: {'denied': state.uri.path}).toString();
    }
    return null;
  };
}

final router = GoRouter(
  refreshListenable: session,
  routes: [
    ShellRoute(
      builder: (context, state, child) => Shell(child: child),
      routes: [
        GoRoute(
          path: '/',
          builder: (context, state) => Home(denied: state.uri.queryParameters['denied']),
        ),
        GoRoute(
          path: '/login',
          builder: (context, state) => Login(redirectTo: state.uri.queryParameters['redirect']),
        ),
        GoRoute(
          path: '/schedule',
          redirect: (context, state) => requireLogin(state),
          builder: (context, state) => const Schedule(),
        ),
        GoRoute(
          path: '/administration',
          // os guards, em ordem: o primeiro que retornar um endereço vence
          redirect: (context, state) => requireLogin(state) ?? requireRole({Role.admin})(state),
          // o código da página só é carregado depois que os guards são superados
          builder: (context, state) =>
              DeferredLoading(load: administration.loadLibrary, builder: () => administration.Administration()),
        ),
      ],
    ),
  ],
  // qualquer outro endereço (nenhuma rota corresponde): de volta à página inicial
  onException: (context, state, router) => router.go('/'),
);

Com o [go_router], um guard é uma função de redirecionamento, chamada antes de cada navegação (a de [GoRouter]: para todas as rotas; a de [GoRoute]: apenas para aquela rota). Ela recebe o estado da navegação e devolve:

  • [null]: a navegação continua;
  • um endereço: a navegação é substituída por uma navegação para esse endereço.

O código:

  • linhas 34–38: o guard de “conexão obrigatória”: não está conectado? Redireciona para a página de login, mantendo o destino pretendido (parâmetro [redirect]);
  • linhas 42–47: o guard de “papel obrigatório” é gerado por uma função que recebe os papéis permitidos e devolve o guard. Conectado, mas sem o papel correto: redireciona para a página inicial, com um motivo (parâmetro [denied]);
  • linha 54: o roteador monitora a sessão: quando detecta uma mudança (login, logout), reavalia os guards da tela atual. Se você fizer logout estando na agenda, é imediatamente redirecionado para a página de login;
  • linha 69: a agenda exige que o usuário esteja conectado;
  • linha 75: a página de administração exige que o usuário esteja conectado E tenha o papel (ADMIN): as verificações são encadeadas com [??]; a primeira que devolver um endereço prevalece;
  • Linhas 77–78: o código da página de administração só é carregado depois que os guards são superados;
  • linha 84: qualquer outro endereço redireciona para a página inicial.

Este é o equivalente, no cliente, das verificações do servidor [NestJS] ([JwtAuthGuard], [RolesGuard]), com uma diferença FUNDAMENTAL: um guard no cliente é apenas uma comodidade (para evitar exibir uma tela desnecessária). O aplicativo está nas mãos do usuário, que pode modificá-lo como quiser; a verdadeira proteção dos dados continua no servidor, que reverifica tudo a cada requisição (veja o capítulo sobre a caixa-preta).

5.2.3. O shell e as páginas

// =========================================================================
// lib/ex18_guards/shell.dart - os links e o usuário logado
// -------------------------------------------------------------------------
// ListenableBuilder: reconstrói seu conteúdo a cada vez que o objeto
// escutado (a sessão) notifica uma alteração. A barra superior portanto
// acompanha o usuário logado.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import 'session.dart';

class Shell extends StatelessWidget {
  final Widget child;

  const Shell({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    final path = GoRouterState.of(context).uri.path;

    // um link: em negrito se designa a página exibida
    Widget link(String target, String label) => TextButton(
      onPressed: () => context.go(target),
      child: Text(label, style: TextStyle(fontWeight: path == target ? FontWeight.bold : FontWeight.normal)),
    );

    return Scaffold(
      appBar: AppBar(
        title: const Text('Example 18 - the guards'),
        actions: [
          ListenableBuilder(
            listenable: session,
            builder: (context, _) {
              final u = session.user;
              if (u == null) {
                return TextButton(onPressed: () => context.go('/login'), child: const Text('log in'));
              }
              return Row(
                children: [
                  Chip(label: Text('${u.login} ${u.role.name.toUpperCase()}')),
                  IconButton(
                    tooltip: 'log out',
                    icon: const Icon(Icons.logout),
                    onPressed: () {
                      session.logOut();
                      context.go('/');
                    },
                  ),
                ],
              );
            },
          ),
        ],
      ),
      body: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Wrap(
            children: [
              link('/', 'Home'),
              link('/schedule', 'Schedule (logged in)'),
              link('/administration', 'Administration (ADMIN)'),
            ],
          ),
          const Divider(),
          Expanded(
            child: Padding(padding: const EdgeInsets.all(16), child: child),
          ),
        ],
      ),
    );
  }
}
  • linhas 24–26: uma função local que cria um link: em negrito se ele se refere à página atualmente exibida;
  • linhas 33–37: [ListenableBuilder] reconstrói seu conteúdo toda vez que o objeto monitorado (a sessão) sinaliza uma mudança: a barra superior acompanha o usuário conectado;
  • linhas 46–48: logout e, em seguida, a página de boas-vindas.
// =========================================================================
// lib/ex18_guards/pages/login.dart
// -------------------------------------------------------------------------
// Depois de fazer login, o usuário é enviado de volta à página que queria
// abrir (parâmetro ?redirect=... definido pelo guard), ou à página inicial.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

import '../session.dart';

class Login extends StatefulWidget {
  final String? redirectTo;

  const Login({super.key, this.redirectTo});

  @override
  State<Login> createState() => _LoginState();
}

class _LoginState extends State<Login> {
  final _login = TextEditingController();
  final _password = TextEditingController();
  bool _error = false;

  @override
  void dispose() {
    _login.dispose();
    _password.dispose();
    super.dispose();
  }

  void _submit() {
    if (!session.logIn(_login.text.trim(), _password.text)) {
      setState(() => _error = true);
      return;
    }
    // só um caminho INTERNO é aceito: ele começa com /, mas não com //
    // (//site.com/... designa OUTRO site) - nenhum redirecionamento para outro site
    final r = widget.redirectTo;
    final internal = r != null && r.startsWith('/') && !r.startsWith('//');
    context.go(internal ? r : '/');
  }

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: [
        if (widget.redirectTo != null)
          Card(
            color: Colors.amber.shade50,
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Text('Log in to open ${widget.redirectTo}.'),
            ),
          ),
        TextField(
          controller: _login,
          decoration: const InputDecoration(labelText: 'login'),
        ),
        TextField(
          controller: _password,
          obscureText: true,
          decoration: const InputDecoration(labelText: 'password'),
          onSubmitted: (_) => _submit(),
        ),
        const SizedBox(height: 16),
        Align(
          alignment: Alignment.centerLeft,
          child: FilledButton(onPressed: _submit, child: const Text('Log in')),
        ),
        if (_error)
          const Padding(
            padding: EdgeInsets.only(top: 8),
            child: Text('Incorrect login or password.', style: TextStyle(color: Colors.red)),
          ),
      ],
    );
  }
}
  • linhas 41–43: depois do login, o usuário é redirecionado para a página que queria abrir (parâmetro [redirect] definido pelo guard) ou para a página inicial. Somente um caminho interno é aceito: ele começa com [/], mas não com [//] ([//site.com/...] refere-se a OUTRO site). Na web, uma URL de login gerada por terceiros ([/login?redirect=//pirate-site.com]) nunca levará, portanto, a outro lugar.

As outras páginas são muito simples:

import 'package:flutter/material.dart';

class Home extends StatelessWidget {
  // ?denied=...: definido pelo guard requireRole quando o papel não é adequado
  final String? denied;

  const Home({super.key, this.denied});

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: [
        if (denied != null)
          Card(
            color: Colors.red.shade50,
            child: Padding(padding: const EdgeInsets.all(12), child: Text('Your role does not allow opening $denied.')),
          ),
        const Text(
          'Public page. Try the two other links, logged in or not '
          '(admin, pelissier, martin - password = login).',
        ),
      ],
    );
  }
}
import 'package:flutter/material.dart';

import '../session.dart';

class Schedule extends StatelessWidget {
  const Schedule({super.key});

  @override
  Widget build(BuildContext context) {
    return Text.rich(
      TextSpan(
        children: [
          const TextSpan(text: 'The schedule of '),
          TextSpan(
            text: session.user?.login,
            style: const TextStyle(fontWeight: FontWeight.bold),
          ),
          const TextSpan(text: ': this page requires being logged in.'),
        ],
      ),
    );
  }
}
import 'package:flutter/material.dart';

class Administration extends StatelessWidget {
  const Administration({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text(
      'Administration: page reserved for the ADMIN role, loaded on demand (on the web, its '
      'code is only downloaded on the first visit, and only if the guards allowed it).',
    );
  }
}
// =========================================================================
// lib/ex18_guards/main.dart
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_web_plugins/url_strategy.dart';

import 'routes.dart';

void main() {
  usePathUrlStrategy();
  runApp(
    MaterialApp.router(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      routerConfig: router,
    ),
  );
}

5.2.4. Execução

Sem estar conectado, solicitamos acesso à interface de administração: o guard nos redireciona para a página de login (à esquerda). Fazemos login com a conta [martin] (papel USER): o login nos leva de volta à interface de administração, onde o segundo guard nega o acesso (no meio). Depois de fazer login com a conta [admin], a página se abre (à direita):