Flutter 路由与导航、资源与主题
第 9 章 · Flutter 路由与导航、资源与主题
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() |
交给路由自己决定 |
直接构造路由
// 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>才通过。
具名路由 + 强类型参数
Navigator.of(context).pushNamed<String>(
detailRoute,
arguments: const DetailArgs(title: '具名路由 + 参数'),
);
arguments 的类型是 Object?——丢掉了类型安全。所以要在 onGenerateRoute 里立刻转回来:
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 让你在出栈前插手:
PopScope<void>(
canPop: !_dirty, // 有未保存内容就不许直接 pop
onPopInvokedWithResult: _onPopInvoked, // 被拦下时调用(didPop == false)
child: Scaffold(...),
)
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,弹第二次确认框——死循环。
两个实测出来的坑
-
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); // 但还在详情页 -
测试里模拟"系统返回"要用
maybePop(),不要直接route.didPop()——后者绕过PopScope的popDisposition检查,测不到拦截逻辑。
桌面端的行为差异:macOS/Windows/Linux 上"返回"来自 AppBar 的返回箭头、Alt+←(或 Cmd+[)、以及自定义快捷键;Android 上是系统返回键/手势;iOS 是滑动返回。PopScope 对所有来源都生效。
9.4 资源(assets):打包进安装包的文件
声明
# examples/ch09-navigation/pubspec.yaml
flutter:
uses-material-design: true
assets:
- assets/data/profile.json
整个目录也可以:- assets/images/(注意结尾的 /)。
读取
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)。
分层:传输与解析分开
示例把"读"和"解析"拆成两层:
// 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),
);
}
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(网络)会把这条原则执行得更彻底。
测试资源的两个坑
-
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(); }); -
资源读取是真异步 I/O,
pumpAndSettle不保证它完成。要么注入假 loader(推荐),要么runAsync+ 显式 pump。
9.5 主题:ThemeData、种子色、亮暗切换
// examples/ch09-navigation/lib/main.dart
MaterialApp(
theme: lightTheme(),
darkTheme: darkTheme(),
themeMode: _mode, // ThemeMode.light / dark / system
)
// 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:给主题加槽位
@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 是主题切换时做颜色插值的,必须实现——否则切换瞬间是硬跳变。取用:
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 里,用回调往下传:
class _NavigationAppState extends State<NavigationApp> {
ThemeMode _mode = ThemeMode.light;
void _toggleMode() => setState(() => _mode = ...);
...
}
这只适合"一个开关"的场景。跨多页共享主题/语言/用户状态时,应该用 ch11 的 Riverpod——同一个模式(状态在顶层、通过 Provider 向下取),但不用一层层传回调。
9.6 运行与验证
cd examples/ch09-navigation
flutter pub get && flutter analyze && flutter test
flutter run -d macos
本次真实验证:
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:用 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)
// 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 老兵的三句话:
- 路由就是栈 + 返回值;
push<T>与pop(v)的类型必须一致(编译期检查)。 PopScope的三步顺序(解除拦截 →endOfFrame→ pop)不能换,否则死循环。- assets 是"打包资源",只能通过
rootBundle读;把传输和解析分开,测试会好写十倍。
下一章是重头戏:FFI。用 dart:ffi 调用 C、Rust、Go 写的动态库,覆盖数值、字符串往返、回调,并解释 .so/.dylib/.dll 的差异。