跳到正文
CH 09工程化Flutter8 分钟阅读

Flutter 路由与导航、资源与主题

第 9 章 · Flutter 路由与导航、资源与主题

本章示例examples/ch09-navigation在线阅读源码下载 zip

run

$cd examples/ch09-navigation && flutter run -d macos

已验证

  • flutter analyze 0 告警、flutter test 14 个用例全绿、flutter build macos --debug 真实构建并启动成功
  • 完整工程已打包:打包下载
本章目录 · 17 节

9.1 本章目标

  • 用 Navigator 1.0 完成页面跳转、带参数、带返回值;
  • 分清三条路径:直接 push、routes 具名表、onGenerateRoute + onUnknownRoute;
  • 会用 PopScope 拦截返回(桌面端 Alt+←、Android 返回键、Esc 都走这条路);
  • 会声明和加载 assets,并知道为什么"读资源"和"解析资源"要分成两层;
  • 会用 ThemeData / ColorScheme.fromSeed 做亮暗主题,用 ThemeExtension 加自定义颜色槽;
  • 知道 Flutter 桌面端与移动端在导航上的行为差异。

9.2 路由:页面栈 + 返回值

Flutter 的导航模型是栈(stack):

操作 API 类比
入栈 Navigator.push(route) / pushNamed(name) 打开新窗口/页面
出栈 Navigator.pop(result) 关闭并返回值
替换栈顶 pushReplacement 登录后替换登录页
清栈后入栈 pushAndRemoveUntil 退出登录回首页
系统返回 Navigator.maybePop() 交给路由自己决定

直接构造路由

dartlib/src/routes.dart源文件
// examples/ch09-navigation/lib/src/routes.dart
Future<String?> result = await Navigator.of(context).push<String>(
  MaterialPageRoute<String>(
    builder: (BuildContext context) => const DetailPage(
      args: DetailArgs(title: '直接构造的路由', note: '返回时把这段文字带回去'),
    ),
  ),
);

push<T> 的 T 是返回值类型,pop<T>(value) 传回什么,await push 就拿到什么。这相当于 Go 里"调用一个函数、等它返回",只不过中间隔着用户的交互时间。

类型检查:MaterialPageRoute<String> 配 pop('文字') 是编译期检查的;如果 route 是 void 却 pop('文字'),运行时会断言失败。示例最初 onGenerateRoute 里写的是 MaterialPageRoute<void>,配合 pushNamed<String> 直接崩——改成 MaterialPageRoute<String> 才通过。

具名路由 + 强类型参数

dart
Navigator.of(context).pushNamed<String>(
  detailRoute,
  arguments: const DetailArgs(title: '具名路由 + 参数'),
);

arguments 的类型是 Object?——丢掉了类型安全。所以要在 onGenerateRoute 里立刻转回来:

dart
onGenerateRoute: (RouteSettings settings) {
  if (settings.name == detailRoute) {
    final Object? args = settings.arguments;
    return MaterialPageRoute<String>(
      settings: settings,
      builder: (_) => DetailPage(
        args: args is DetailArgs ? args : const DetailArgs(title: '未知参数'),
      ),
    );
  }
  return null; // 交给 onUnknownRoute
},
onUnknownRoute: (RouteSettings settings) => MaterialPageRoute<void>(
  builder: (_) => UnknownPage(name: settings.name),
),

settings: settings 这一步很关键:不传的话,ModalRoute.of(context).settings.name 是 null,你在页面里拿不到"当前路由名",分析埋点之类都会失灵。示例测试断言了 当前路由: /detail。

方案 类型安全 适合
直接 MaterialPageRoute ✅ 编译期 参数复杂、一次性跳转
routes 表 ❌ 无参数 无参页面(关于页、设置页)
onGenerateRoute + DetailArgs ⚠️ 手动转一次 生产里最常见的折中
go_router(第三方) ✅ URL 化 深链接、Web-like 路由(ch16 会讲)

生产项目建议用 go_router:它把路由表变成声明式配置,支持 URL/深链接、嵌套路由、重定向。Navigator 1.0 足够理解原理,也足够应付本教程其余章节。

9.3 PopScope:拦截返回

"用户填了一半就想退出"是最常见的需求。PopScope 让你在出栈前插手:

dart
PopScope<void>(
  canPop: !_dirty,                          // 有未保存内容就不许直接 pop
  onPopInvokedWithResult: _onPopInvoked,    // 被拦下时调用(didPop == false)
  child: Scaffold(...),
)
dart
Future<void> _onPopInvoked(bool didPop, Object? result) async {
  if (didPop) return;
  final bool discard = await showDialog<bool>(/* 确认框 */) ?? false;
  if (!mounted || !discard) return;
  setState(() => _note.clear());            // 1. 解除拦截
  await WidgetsBinding.instance.endOfFrame; // 2. 等这一帧把 canPop 更新到路由上
  if (!mounted) return;
  Navigator.of(context).pop();              // 3. 现在才能真正出栈
}

顺序不能错:如果直接 Navigator.pop(),canPop 还是 false,会再次触发 _onPopInvoked,弹第二次确认框——死循环。

两个实测出来的坑

  1. maybePop 返回 true 不代表出栈成功。源码里对 doNotPop 分支的处理是"调回调,然后返回 true(表示请求已被处理)"。所以判断是否真的出栈要看界面或 ModalRoute.isCurrent:

    dart
    final bool handled = await Navigator.of(pageContext).maybePop();
    expect(handled, isTrue);                                  // 请求被处理了
    expect(find.byKey(const Key('detail-note')), findsOneWidget); // 但还在详情页
    
  2. 测试里模拟"系统返回"要用 maybePop(),不要直接 route.didPop()——后者绕过 PopScope 的 popDisposition 检查,测不到拦截逻辑。

桌面端的行为差异:macOS/Windows/Linux 上"返回"来自 AppBar 的返回箭头、Alt+←(或 Cmd+[)、以及自定义快捷键;Android 上是系统返回键/手势;iOS 是滑动返回。PopScope 对所有来源都生效。

9.4 资源(assets):打包进安装包的文件

声明

yamlpubspec.yaml源文件
# examples/ch09-navigation/pubspec.yaml
flutter:
  uses-material-design: true
  assets:
    - assets/data/profile.json

整个目录也可以:- assets/images/(注意结尾的 /)。

读取

dart
final String raw = await rootBundle.loadString('assets/data/profile.json');

关键认知:rootBundle 读的是打进安装包的资源,不是文件系统路径。桌面端也一样——assets/ 在构建时被塞进 AssetManifest.bin,运行时由 Flutter 引擎提供。所以:

  • ✅ 用相对路径 assets/xxx,由 pubspec.yaml 声明;
  • ❌ 不要用 File('assets/xxx') 读——打包后那个目录不存在;
  • ✅ 需要读写用户目录(配置、数据库)时用 path_provider(ch14)。

分层:传输与解析分开

示例把"读"和"解析"拆成两层:

dartlib/src/profile.dart源文件
// examples/ch09-navigation/lib/src/profile.dart
class Profile {
  factory Profile.parse(String raw) =>
      Profile.fromJson(jsonDecode(raw) as Map<String, Object?>);

  factory Profile.fromJson(Map<String, Object?> json) => Profile(
        name: json['name'] as String? ?? '未知',
        role: json['role'] as String? ?? '',
        tags: (json['tags'] as List<Object?>? ?? const <Object?>[])
            .whereType<String>()
            .toList(growable: false),
      );
}
dart
class ProfileCard extends StatefulWidget {
  const ProfileCard({super.key, this.loader = _loadFromBundle});
  final Future<String> Function() loader;   // ← 注入点
  static Future<String> _loadFromBundle() =>
      rootBundle.loadString('assets/data/profile.json');
}

好处立刻体现:解析逻辑可以脱离 I/O 单测(喂字符串),UI 逻辑可以注入假 loader 单测,真资源只留一个冒烟测试。ch12(JSON)和 ch13(网络)会把这条原则执行得更彻底。

测试资源的两个坑

  1. rootBundle 的缓存会跨测试"中毒"。CachingAssetBundle 缓存的 Future 是在第一个测试的 fake-async 时钟里创建的;后续测试拿到这个 Future,它的完成回调永远等不到 → 界面永远"加载中…"。解决:在真资源测试里用 loadString(..., cache: false),或者直接在 tester.runAsync 里跑。

    dart
    await tester.runAsync(() async {
      await tester.pumpWidget(/* 用 cache: false 的 loader */);
      await Future<void>.delayed(const Duration(milliseconds: 200));
      await tester.pump();
    });
    
  2. 资源读取是真异步 I/O,pumpAndSettle 不保证它完成。要么注入假 loader(推荐),要么 runAsync + 显式 pump。

9.5 主题:ThemeData、种子色、亮暗切换

dartlib/main.dart源文件
// examples/ch09-navigation/lib/main.dart
MaterialApp(
  theme: lightTheme(),
  darkTheme: darkTheme(),
  themeMode: _mode,        // ThemeMode.light / dark / system
)
dartlib/src/theme.dart源文件
// examples/ch09-navigation/lib/src/theme.dart
ThemeData lightTheme() {
  final ColorScheme scheme = ColorScheme.fromSeed(seedColor: const Color(0xFF1565C0));
  return ThemeData(
    useMaterial3: true,
    colorScheme: scheme,
    extensions: const <ThemeExtension<dynamic>>[
      BrandColors(banner: Color(0xFFE3F2FD), onBanner: Color(0xFF0D47A1)),
    ],
  );
}
概念 作用 C/Go 类比
ThemeData 一整套主题配置(颜色、字体、组件默认样式) 全局样式结构体
ColorScheme.fromSeed 从一个种子色生成协调的 Material 3 配色 设计系统生成器
themeMode 亮/暗/跟随系统 —
ThemeExtension 给主题加自定义字段 需要自己写结构体 + 传递
Theme.of(context) 沿树向上取最近的主题 全局变量(但作用域可控)

ThemeMode.system 会跟随操作系统的深色模式——桌面端用户很在意这个,生产应用应该提供,示例为了可测只做了手动切换。

ThemeExtension:给主题加槽位

dart
@immutable
class BrandColors extends ThemeExtension<BrandColors> {
  const BrandColors({required this.banner, required this.onBanner});
  final Color banner;
  final Color onBanner;

  @override
  BrandColors copyWith({Color? banner, Color? onBanner}) => ...;

  @override
  BrandColors lerp(ThemeExtension<BrandColors>? other, double t) {
    if (other is! BrandColors) return this;
    return BrandColors(
      banner: Color.lerp(banner, other.banner, t)!,
      onBanner: Color.lerp(onBanner, other.onBanner, t)!,
    );
  }
}

lerp 是主题切换时做颜色插值的,必须实现——否则切换瞬间是硬跳变。取用:

dart
extension BrandColorsX on BuildContext {
  BrandColors get brand => Theme.of(this).extension<BrandColors>()!;
}

// 用法
Container(color: context.brand.banner, child: Text(..., style: TextStyle(color: context.brand.onBanner)))

别混淆两种"扩展":ch08 的 extension 是给类型加方法(编译期);ThemeExtension 是给主题加数据(运行期沿树查找)。它们名字像,机制完全不同。

亮暗切换的状态放哪

示例把 ThemeMode 放在根 StatefulWidget 里,用回调往下传:

dart
class _NavigationAppState extends State<NavigationApp> {
  ThemeMode _mode = ThemeMode.light;
  void _toggleMode() => setState(() => _mode = ...);
  ...
}

这只适合"一个开关"的场景。跨多页共享主题/语言/用户状态时,应该用 ch11 的 Riverpod——同一个模式(状态在顶层、通过 Provider 向下取),但不用一层层传回调。

9.6 运行与验证

bash
cd examples/ch09-navigation
flutter pub get && flutter analyze && flutter test
flutter run -d macos

本次真实验证:

text
No issues found! (ran in 1.6s)
00:01 +14: All tests passed!

✓ Built build/macos/Build/Products/Debug/ch09_navigation.app
flutter: The Dart VM service is listening on http://127.0.0.1:60353/...

附:C/Go 代码对照:路由分发表

go
// Go:用 mux 做"路径 → 处理函数"的分发,参数自己从 URL 里切
mux := http.NewServeMux()
mux.HandleFunc("/", home)
mux.HandleFunc("/about", about)
mux.HandleFunc("/bookmark/", func(w http.ResponseWriter, r *http.Request) {
    id := strings.TrimPrefix(r.URL.Path, "/bookmark/")
    detail(w, r, id)
})
http.ListenAndServe(":8080", mux)
dart
// Flutter / go_router:路径参数由路由系统解析并做类型转换
GoRoute(
  path: '/',
  builder: (context, state) => const HomePage(),
  routes: [
    GoRoute(path: 'about', builder: (context, state) => const AboutPage()),
    GoRoute(
      path: 'bookmark/:id',
      builder: (context, state) => DetailPage(
        id: int.tryParse(state.pathParameters['id'] ?? '') ?? -1,
      ),
    ),
  ],
)

Go 的 mux 是"请求进来才分发",Flutter 的路由是"页面栈 + 声明式路径";state.pathParameters 相当于已经切好的 URL 参数,但仍要自己做类型转换与校验(tryParse)。

9.7 本章小结 + C/Go 对照清单

主题 C / Go Flutter 陷阱
页面切换 开窗口/切 View Navigator.push 忘记 await 返回值
返回结果 回调/信号 pop(result) + await push<T> 类型不匹配 → 运行时断言
具名路由 手工查表 routes / onGenerateRoute arguments 是 Object?
拦截返回 窗口关闭事件 PopScope 顺序:解除拦截 → 等帧 → pop
静态资源 打包进二进制/安装目录 pubspec.yaml + rootBundle 不能用 File 读 assets
主题 全局样式表 ThemeData + Theme.of 漏了 lerp → 切换跳变
自定义主题槽 自己的样式结构体 ThemeExtension 未注册时 ! 会崩

给 C/Go 老兵的三句话:

  1. 路由就是栈 + 返回值;push<T> 与 pop(v) 的类型必须一致(编译期检查)。
  2. PopScope 的三步顺序(解除拦截 → endOfFrame → pop)不能换,否则死循环。
  3. assets 是"打包资源",只能通过 rootBundle 读;把传输和解析分开,测试会好写十倍。

下一章是重头戏:FFI。用 dart:ffi 调用 C、Rust、Go 写的动态库,覆盖数值、字符串往返、回调,并解释 .so/.dylib/.dll 的差异。