Skip to content

5. 路由

一个应用程序有多个屏幕。[Flutter] 使用 [Navigator] 来管理它们:这是一个屏幕的栈 ,新屏幕([Navigator.push])被压入栈中,并从栈中弹出([Navigator.pop],或手机的返回键)。对于小型移动应用,这已经足够。但是一旦你需要 URL (/doctors/2)——也就是可以被引用、可以从链接打开、在 Web 上可以重新加载、并可以由守卫保护的屏幕——就要使用路由器。[go_router] 包由 [Flutter] 团队维护,并在其文档中被推荐,是使用最广泛的路由器。

5.1. 示例 17:路由器

5.1.1. 数据

1
2
3
4
5
6
7
8
// "硬编码" 的数据,以便本示例不依赖服务器
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] 登录后,页面打开(右图):