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
| // 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):