flutter-dev

Flutter 开发指南

使用 Flutter 3 和 Dart 构建跨平台应用的实用指南。重点介绍经过验证的模式、状态管理和性能优化。

快速参考

Widget 模式

用途	组件
状态管理（简单）	StateProvider + ConsumerWidget
状态管理（复杂）	NotifierProvider / Bloc
异步数据	FutureProvider / AsyncNotifierProvider
实时流	StreamProvider
导航	GoRouter + context.go/push
响应式布局	LayoutBuilder + 断点
列表显示	ListView.builder
复杂滚动	CustomScrollView + Slivers
Hooks	HookWidget + useState/useEffect
表单	Form + TextFormField + 验证

性能模式

用途	解决方案
防止重建	const 构造函数
选择性更新	ref.watch(provider.select(...))
隔离重绘	RepaintBoundary
懒加载列表	ListView.builder
密集计算	compute() isolate
图像缓存	cached_network_image

核心原则

Widget 优化

• 尽可能使用 const 构造函数
• 将静态 Widget 提取到单独的 const 类中
• 为列表项使用 Key（ValueKey、ObjectKey）
• 状态管理优先使用 ConsumerWidget，而非 StatefulWidget

状态管理

• 使用 Riverpod 进行依赖注入和简单状态管理
• 使用 Bloc/Cubit 实现事件驱动的工作流和复杂逻辑
• 切勿直接修改状态（应创建新实例）
• 使用 select() 尽量减少重建

布局

• 以 8 pt 为间距增量（8、16、24、32、48）
• 响应式断点：移动端（<650）、平板（650-1100）、桌面端（>1100）
• 使用灵活布局适配所有屏幕尺寸
• 遵循 Material 3 / Cupertino 设计指南

性能

• 优化前使用 DevTools 进行性能分析
• 60 fps 的目标帧耗时为 <16 ms
• 使用 RepaintBoundary 处理复杂动画
• 使用 compute() 将繁重任务移出主线程

检查清单

Widget 最佳实践

• 所有静态 Widget 均使用 const 构造函数
• 为列表项设置适当的 Key
• 状态相关的 Widget 使用 ConsumerWidget
• 不在 build() 方法中构建 Widget
• 将可复用的 Widget 提取到单独文件中

状态管理

• 状态对象不可变
• 使用 select() 实现细粒度重建
• 正确限定 provider 的作用域
• 释放控制器和订阅
• 处理加载和错误状态

导航

• 使用带类型路由的 GoRouter
• 通过 redirect 实现身份验证守卫
• 支持深层链接
• 在路由间保留状态

性能

• 在 profile 模式下测试（flutter run --profile）
• 帧渲染耗时 <16 ms
• 无不必要的重建（使用 DevTools 检查）
• 缓存并调整图像尺寸
• 在 isolates 中执行密集计算

测试

• 为 UI 组件编写 Widget 测试
• 为业务逻辑编写单元测试
• 为用户流程编写集成测试
• 使用 blocTest() 编写 Bloc 测试

参考资料

主题	参考资料
Widget 模式、const 优化、响应式布局	Widget 模式
Riverpod providers、notifiers、异步状态	Riverpod 状态管理
Bloc、Cubit、事件驱动状态	Bloc 状态管理
GoRouter 设置、路由、深度链接	GoRouter 导航
基于功能的结构、依赖项	项目结构
性能分析、const 优化、DevTools	性能优化
Widget 测试、集成测试、模拟	测试策略
iOS/Android/Web 专属实现	平台集成
隐式/显式动画、Hero、转场	动画
Dio、拦截器、错误处理、缓存	网络
表单验证、FormField、输入格式化器	表单
i18n、flutter_localizations、intl	本地化

---

Flutter、Dart、Material Design 和 Cupertino 分别是 Google LLC 和 Apple Inc. 的商标。Riverpod、Bloc 和 GoRouter 是由各自维护者提供的开源软件包。