5. 路由
一个应用程序有多个屏幕。[Flutter] 使用 [Navigator] 来管理它们:这是一个屏幕的栈 ,新屏幕([Navigator.push])被压入栈中,并从栈中弹出([Navigator.pop],或手机的返回键)。对于小型移动应用,这已经足够。但是一旦你需要 URL (/doctors/2)——也就是可以被引用、可以从链接打开、在 Web 上可以重新加载、并可以由守卫保护的屏幕——就要使用路由器。[go_router] 包由 [Flutter] 团队维护,并在其文档中被推荐,是使用最广泛的路由器。
5.1. 示例 17:路由器
5.1.1. 数据
| // "硬编码" 的数据,以便本示例不依赖服务器
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'),
];
|
“硬编码”的数据,以便在本示例中不依赖服务器:一个记录列表。
5.1.2. 路由
| // =========================================================================
// lib/ex17_router/routes.dart - 应用的路由(ROUTES)
// -------------------------------------------------------------------------
// 一个应用有多个界面("页面")。路由器(ROUTER)把一个
// 地址(ADDRESS,一个路径,就像 Web 上那样:/doctors/2)与一个界面关联起来。Flutter
// 提供了 Navigator(界面的栈:我们压入,我们弹出);
// 由 Flutter 团队维护的 go_router 包为它增加了
// 地址:链接、参数、浏览器的后退按钮
// 以及 Web 上手工输入的地址、Android 的返回键。
// '/doctors/:id' :id 是一个参数(/doctors/2 -> id = "2");
// ShellRoute 一个公共的 "外壳"(顶部栏、底部
// 导航栏),包在它的各个路由的界面外围;
// redirect 重定向:旧地址指向新地址;
// errorBuilder 不匹配任何路由的地址所显示的界面。
// =========================================================================
import 'package:go_router/go_router.dart';
import 'shell.dart';
import 'pages/home.dart';
// 延迟(DEFERRED)加载:在 Web 上,这个页面的代码只在首次访问时
// 才下载(flutter build web 会把它单独生成一个文件)
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(
// 起始地址(在手机上:没有地址栏)
initialLocation: '/',
routes: [
ShellRoute(
// child:当前子路由的界面,放置在外壳之中(IN)
builder: (context, state, child) => Shell(child: child),
routes: [
GoRoute(path: '/', builder: (context, state) => const Home()),
GoRoute(
path: '/doctors',
builder: (context, state) => const DoctorList(),
// 一个嵌套(NESTED)路由:/doctors/2
routes: [
GoRoute(
path: ':id',
// pathParameters:路径的参数,始终是字符串(STRINGS)
builder: (context, state) => DoctorDetail(id: state.pathParameters['id']!),
),
],
),
GoRoute(
path: '/search',
// uri.queryParameters:? 之后的参数(/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()),
),
// 重定向:这个路由没有界面,它返回另一个地址
GoRoute(path: '/physicians', redirect: (context, state) => '/doctors'),
],
),
],
errorBuilder: (context, state) => NotFoundPage(address: state.uri.toString()),
);
|
一条路由 把一个路径与一个屏幕关联起来。
- 第 23 行:一个延迟导入([deferred])。在 Web 上,这个页面的代码被编译成一个单独的文件,只在首次访问该页面时才下载([about.loadLibrary()])。在手机上,所有代码都已在应用中:[loadLibrary()] 会立即结束;
- 第 30–32 行:路由器,一个名为 [GoRouter] 的对象,只创建一次,位于任何组件之外。[initialLocation]:起始地址(手机上没有地址栏来显示它);
- 第 34–36 行:[ShellRoute] 是多个屏幕共用的容器:包含顶部栏和底部导航栏。它的 [builder] 接收 [child]——即当前路由的屏幕——并把它放入外壳中。这相当于 [React Router] 中的嵌套路由和 [<Outlet />];
- 第 38 行:一条路由——它的路径——以及一个生成其屏幕的函数。[state] ([GoRouterState])描述当前的导航:地址及其参数;
- 第 40–47 行:医生列表,以及一条嵌套路由:在 ['/doctors'] 之下的 [':id'] 构成路径 [/doctors/:id],其中 [:id] 是一个参数([/doctors/2]: [id] 等于 ["2"])。[state.pathParameters] 提供路径参数,它们始终是字符串;
- 第 52–54 行:[state.uri] 是完整地址;[queryParameters] 包含跟在 [?] 之后的参数([/search?q=pediatrician]);
- 第 57–59 行:由 [DeferredLoading] 组件按需加载的页面(稍后讨论);
- 第 62 行:一次重定向——这条路由没有屏幕;它的函数 [redirect] 返回另一个地址,导航会被重定向到该地址;
- 第 66 行:对应不匹配任何路由的地址的屏幕。
5.1.3. 启动
| // =========================================================================
// lib/ex17_router/main.dart
// -------------------------------------------------------------------------
// MaterialApp.router:应用不再只有一个(ONE)主界面(home),
// 由路由器根据地址决定显示哪个界面。
// usePathUrlStrategy():在 Web 上使用 "干净" 的地址(/doctors/2),
// 而不是默认形式(/#/doctors/2)。在其他平台上没有效果。
// =========================================================================
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,
),
);
}
|
- 第 16 行:在 Web 上,使用“干净”的地址([/doctors/2]),而不是默认形式([/#/doctors/2])。对手机没有任何影响;
- 第 17–21 行:[MaterialApp.router]:应用不再显示唯一的一个主屏幕([home]);由路由器根据地址来决定屏幕。
5.1.4. 应用的外壳
| // =========================================================================
// lib/ex17_router/shell.dart - 应用的 "外壳"
// -------------------------------------------------------------------------
// 顶部栏、底部导航栏,以及两者之间的
// 当前路由的界面(child)。
// - GoRouterState.of(context).uri : 当前地址;
// - context.go('/doctors') :跳转到某个地址。界面的栈
// 被这个地址对应的界面替换(REPLACED)(一个标签页);
// - context.push('/doctors/2') :把一个界面压入(PUSHING)当前
// 界面之上;返回键(或 context.pop())会将其弹出。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
// 标签页:(路径,标签,图标)
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;
// 活动标签页:其路径是当前地址开头部分的那一个
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 重新变回空格
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:底部标签栏,是移动端的典型控件
bottomNavigationBar: NavigationBar(
selectedIndex: active,
onDestinationSelected: (i) => context.go(tabs[i].$1),
destinations: [
for (final (_, label, icon) in tabs) NavigationDestination(icon: Icon(icon), label: label),
],
),
);
}
}
|
- 第 17–21 行:各个选项卡:记录(路径、标签、图标);
- 第 31 行:当前地址。[GoRouterState.of(context)] 是对继承数据的读取(见示例 14):每次导航时,外壳都会被重建;
- 第 33–36 行:当前选项卡:其路径是当前地址开头部分的那个选项卡。[for (final (i, (path, _, _)) in tabs.indexed)] 同时解析(序号,选项卡)这一对和选项卡记录,只保留路径([_]:“忽略”);
- 第 48–49 行:显示当前地址([Uri.decodeFull]:[%20] 重新变回空格);
- 第 53–54 行:当前路由的屏幕;
- 第 59–63 行:底部选项卡栏([NavigationBar]),是移动应用的典型特征。[onDestinationSelected] 接收被点击选项卡的索引;[context.go(path)] 跳转到它的地址。[tabs[i].$1]:位置记录的第一个字段。
使用 [go_router] 有两种导航方式:
- [context.go('/doctors')]:前往一个地址。屏幕栈会被该地址所描述的屏幕栈替换。切换选项卡时就这样做;
- [context.push('/doctors/2')]:把该地址对应的屏幕压入当前屏幕的上方。手机的返回键(或 [context.pop()])会把它弹出栈,你就回到原来的位置。这就是“进入”详情视图的方式。
5.1.5. 页面
| // lib/ex17_router/pages/home.dart
// Title:只要该页面处于显示状态,它就是浏览器标签页(Web)的标题,
// 或最近使用的应用列表(Android)中该应用的标题
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),
// 指向特定地址的链接
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')),
],
),
],
),
);
}
}
|
每个页面都放置一个 [Title] 组件:只要该页面处于显示状态,其标题就是浏览器标签页(在 Web 上)的标题,或最近使用的应用列表中该应用(在 [Android] 上)的标题。两个按钮通向特定的 URL:重定向 [/physicians],以及一个不存在的 URL。
| // lib/ex17_router/pages/doctor_list.dart - 带参数的链接
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:医生的界面被压入(PUSHED);返回键会回到这里
onTap: () => context.push('/doctors/${m.id}'),
),
],
),
);
}
}
|
- 第 22 行:点击一位医生,会把他的屏幕压入栈中。
| // =========================================================================
// lib/ex17_router/pages/doctor_detail.dart - 带参数的页面
// -------------------------------------------------------------------------
// 路由器把路径的 :id 参数传给它,这是一个字符串(STRING)("2")。
// context.pop() 弹出该界面(类似返回键);context.go()
// 跳转到另一个地址。如果我们从 /doctors/1 跳到 /doctors/2,
// Flutter 会复用同一个界面,只是用另一个 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:如果 id 不是数字则返回 null;firstWhere... orElse:未找到
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:下方是否还有界面?(如果我们在 Web 上是
// 直接到达这个地址的,则没有)
onPressed: () => context.canPop() ? context.pop() : context.go('/doctors'),
child: const Text('Back'),
),
FilledButton(
// pushReplacement:替换当前界面(不是压入)
onPressed: () => context.pushReplacement('/doctors/$next'),
child: const Text('Next doctor'),
),
],
),
],
),
);
}
}
|
- 第 16 行:路径参数 [:id],由路由器传给构造函数;
- 第 23–26 行:[int.tryParse]:得到数字 ID,或 [null];如果找不到医生,就显示一条消息;
- 第 45 行:返回:如果栈中其下方还有屏幕,就把当前屏幕弹出栈([canPop]);否则(如果你是通过 Web 直接进入这个地址的),就转到列表;
- 第 50 行:下一位医生替换当前屏幕(不叠加:返回键回到列表,而不是上一位医生)。
| // =========================================================================
// lib/ex17_router/pages/search.dart - 由地址驱动的页面
// -------------------------------------------------------------------------
// /search?q=pediatrician:页面完全由它的地址描述。
// 在 Web 上,可以收藏它、重新加载它,也可以
// 后退。搜索意味着跳转(GOING)到地址 /search?q=<input>:
// 页面显示地址所说的内容,仅此而已。
// =========================================================================
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:构建地址,并对需要编码的部分进行编码(空格 -> %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: [
// 一个非受控(NON-controlled)输入框,以地址中的值作为起始值;
// key:ValueKey(q):如果地址改变(返回键),Flutter
// 会重新创建该输入框,它随后取新的值
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)),
),
],
),
);
}
}
|
- 第 20–22 行:搜索就是前往地址 [/search?q=<input>]。[Uri] 通过对必要信息进行编码来生成该地址(空格变为 [%20])。页面完全由它的地址描述:在 Web 上,你可以为它添加书签、重新加载或后退;
- 第 38–43 行:一个不带验证的字段,以 URL 中的值作为初始值。[key: ValueKey(q)]:如果 URL 改变(浏览器的后退按钮),key 也随之改变;[Flutter] 会重新创建该字段,它由此取得新值。[textInputAction: TextInputAction.search]:手机键盘上的 Enter 键起放大镜的作用。
| // =========================================================================
// lib/ex17_router/pages/deferred_loading.dart
// -------------------------------------------------------------------------
// 一个代码按需加载的界面("deferred" 导入):
// load() 下载代码(一个 Future),代码到达之后由 builder() 构建
// 界面。在此期间:显示加载指示器。
// FutureBuilder 在 Future 完成时重建它的内容
// (见示例 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> {
// Future 只创建一次(ONCE)(而不是每次 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()),
);
}
}
|
- 第 25 行:代码已加载,且只启动一次(一个 [late] 字段,在首次读取时初始化):如果在 [build] 中启动,每次重建都会再次触发它;
- 第 29–33 行:[FutureBuilder] 在 [Future] 结束时重建其内容:在此期间显示加载指示器;然后显示屏幕(见示例 19)。
| // lib/ex17_router/pages/about.dart - 按需加载的页面
// (见 routes.dart 中的 "deferred as about" 导入)
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 - 未知地址的界面
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')),
],
),
),
),
);
}
}
|
未知地址屏幕有它自己的 [Scaffold]:它由 [errorBuilder] 构造,位于外壳之外。
5.1.6. 运行
主屏幕;一位医生的详情(叠加显示:顶部栏没有变化,但手机的返回键会带你回到列表);搜索;一个未知地址:
在 Web 上([flutter run -d chrome]),地址会显示在浏览器的地址栏中,后退和前进按钮可用,你也可以手动输入地址。
5.2. 示例 18:导航守卫
5.2.1. 会话
| // =========================================================================
// lib/ex18_guards/session.dart - 一个模拟(SIMULATED)的会话(没有服务器)
// -------------------------------------------------------------------------
// 已登录的用户必须能被各个界面(顶部栏、
// 日程)和路由器的守卫(是函数,不是
// 组件)所知。它存放在单个对象中,一个 ChangeNotifier:
// - 一个私有字段,即状态;
// - 读取和修改它的方法;
// - notifyListeners():通知它的订阅者(路由器、各个界面)
// 它发生变化的时候。
// (示例 23 会用真实的服务器做同样的事情。)
// =========================================================================
import 'package:flutter/foundation.dart';
enum Role { admin, doctor, user }
typedef User = ({String login, Role role});
// 三个 "硬编码" 的账户(密码 = 登录名)
const _accounts = {'admin': Role.admin, 'pelissier': Role.doctor, 'martin': Role.user};
class Session extends ChangeNotifier {
User? _user; // 状态:null 表示没有人登录
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();
}
}
// 应用唯一的会话
final session = Session();
|
已登录的用户必须能被各个屏幕(顶部栏、日程)和路由器的检查——这些都不是组件——所识别。它被存放在单个对象中,即一个 [ChangeNotifier] (见示例 14):
- 第 24 行:状态:一个用户,或 [null];
- 第 28–35 行:模拟的登录:三个“硬编码”的账户(密码 = 登录名)。它会通知其订阅者([notifyListeners()]);
- 第 45 行:应用唯一的会话,一个全局变量。(示例 23 将用真实的服务器做同样的事情。)
5.2.2. 守卫与受保护的路径
| // =========================================================================
// lib/ex18_guards/routes.dart - 由守卫保护(PROTECTED)的路由
// -------------------------------------------------------------------------
// redirect:go_router 在每次导航之前(BEFORE)调用的函数
// (GoRouter 上的那个:对所有路由生效;GoRoute 上的那个:
// 只对它自己生效)。它接收导航的状态(state.uri:
// 被请求的地址),并返回:
// - null:导航继续;
// - 一个地址:导航被替换为跳转到
// 该地址。
// refreshListenable:一个要监听(LISTEN)的对象;当它通知
// 变化时(会话:登录、登出),路由器会针对当前界面
// 重新评估它的守卫。
//
// 它是 NestJS 守卫(JwtAuthGuard、
// RolesGuard)在客户端的对应物 - 但有一个根本(FUNDAMENTAL)的区别:客户端守卫
// 只是一种便利。应用掌握在用户手中,用户
// 可以随意修改它。对数据真正的保护仍然是
// 服务器(SERVER)的保护(见关于黑盒的一章)。
// =========================================================================
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';
// "需要登录" 守卫:未登录 -> 跳到登录页,
// 并记住用户原本想去的地方
String? requireLogin(GoRouterState state) {
if (session.user == null) {
return Uri(path: '/login', queryParameters: {'redirect': state.uri.toString()}).toString();
}
return null;
}
// "需要角色" 守卫:一个构建(BUILDS)守卫的函数
String? Function(GoRouterState) requireRole(Set<Role> roles) {
return (state) {
final u = session.user;
if (u == null || !roles.contains(u.role)) {
// 已登录,但角色不对:回到主页,并附带一个原因
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',
// 各个守卫按顺序执行:第一个返回地址的守卫生效
redirect: (context, state) => requireLogin(state) ?? requireRole({Role.admin})(state),
// 只有通过守卫之后才会加载页面的代码
builder: (context, state) =>
DeferredLoading(load: administration.loadLibrary, builder: () => administration.Administration()),
),
],
),
],
// 任何其他地址(没有匹配的路由):回到主页
onException: (context, state, router) => router.go('/'),
);
|
使用 [go_router] 时,守卫是一个redirect 函数,在每次导航之前被调用([GoRouter] 上的那个:针对所有路由;[GoRoute] 上的那个:只针对该路由)。它接收导航状态并返回:
- [null]:导航继续进行;
- 一个地址:导航被替换为前往该地址的导航。
代码如下:
- 第 34–38 行:“需要登录”守卫:未登录?重定向到登录页面,同时保留原本想去的目的地(参数 [redirect]);
- 第 42–47 行:“需要角色”守卫由一个函数生成,该函数接收允许的角色并返回守卫。已登录,但角色不对:重定向到主页,并附上原因(参数 [denied]);
- 第 54 行:路由器监视会话:一旦检测到变化(登录、退出),就会重新评估当前屏幕的守卫。如果你在日程页面退出登录,就会立即被重定向到登录页面;
- 第 69 行:日程要求用户已登录;
- 第 75 行:管理页面要求用户已登录并且拥有角色(ADMIN):这些检查用 [??] 串联;第一个返回地址的检查优先生效;
- 第 77–78 行:管理页面的代码只有在通过守卫之后才会加载;
- 第 84 行:任何其他地址都会重定向到主页。
这相当于 [NestJS] 服务器端检查([JwtAuthGuard]、[RolesGuard])在客户端的对应物,但有一个根本区别:客户端守卫仅仅是一种便利措施(避免显示不必要的屏幕)。应用掌握在用户手中,用户可以随意修改它;真正的数据保护仍在服务器上,服务器会在每次请求时重新验证一切(参见关于黑盒的那一章)。
5.2.3. 外壳与页面
| // =========================================================================
// lib/ex18_guards/shell.dart - 链接,以及已登录的用户
// -------------------------------------------------------------------------
// ListenableBuilder:每当被监听的对象(会话)通知变化时,
// 就重建它的内容。因此顶部栏
// 跟随已登录的用户。
// =========================================================================
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;
// 一个链接:如果它指向当前显示的页面,则用粗体显示
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),
),
],
),
);
}
}
|
- 第 24–26 行:一个创建链接的局部函数:如果链接指向当前显示的页面,则以粗体显示;
- 第 33–37 行:每当被监视的对象(会话)发出变化信号时,[ListenableBuilder] 就会重建其内容:顶部栏随已登录的用户而变化;
- 第 46–48 行:退出登录,然后转到欢迎页面。
| // =========================================================================
// lib/ex18_guards/pages/login.dart
// -------------------------------------------------------------------------
// 登录之后,用户会被送回他们想要打开的页面
// (由守卫设置的 ?redirect=... 参数),或者回到主页。
// =========================================================================
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;
}
// 只接受内部(INTERNAL)路径:以 / 开头,但不以 // 开头
// (//site.com/... 指向的是另一个(ANOTHER)站点)- 不会重定向到其他站点
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)),
),
],
);
}
}
|
- 第 41–43 行:登录之后,用户被重定向到他想打开的页面(由守卫设置的参数 [redirect] ),或者重定向到主页。只接受内部路径:它以 [/] 开头,但不以 [//] 开头([//site.com/...] 指向另一个站点)。因此,在 Web 上,由第三方生成的登录 URL([/login?redirect=//pirate-site.com])永远不会把用户带到别处。
其他页面非常简单:
| import 'package:flutter/material.dart';
class Home extends StatelessWidget {
// ?denied=...:当角色不匹配时由 requireRole 守卫设置
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. 运行
在未登录的情况下,我们请求访问管理界面:守卫把我们重定向到登录页面(左图)。我们用账户 [martin] (角色 USER)登录:登录后回到管理界面,第二个守卫拒绝访问(中图)。用账户 [admin] 登录后,页面打开(右图):