moai-lang-flutter

快速参考（30 秒）

Flutter/Dart 开发专家——Dart 3.5+、Flutter 3.24+，采用现代模式。

自动触发：Flutter 项目（.dart 文件、pubspec.yaml）、跨平台应用、Widget 开发

核心能力：

• Dart 3.5：模式、记录、密封类、扩展类型
• Flutter 3.24：Widget 树、Material 3、自适应布局
• Riverpod：使用代码生成的状态管理
• go_router：声明式导航和深层链接
• 平台通道：原生 iOS/Android 集成
• 测试：flutter_test、widget_test、integration_test

实施指南（5 分钟）

Dart 3.5 语言特性

使用密封类进行模式匹配：定义一个带泛型类型参数 T 的密封类 Result。创建子类 Success（包含 data 字段）和 Failure（包含错误字符串）。使用 switch 表达式对密封类型进行模式匹配。模式使用冒号语法提取命名字段。使用 when 关键字添加守卫子句，根据字段值进行条件匹配。

记录与解构：使用带命名字段的括号定义记录类型别名。创建函数，以含有位置元素的记录元组形式返回多个值。使用赋值左侧的括号进行解构。在 for 循环中，直接使用冒号语法解构命名记录字段。

扩展类型：使用 type 关键字定义扩展类型，并在括号内包装基础类型。添加用于验证逻辑的工厂构造函数。为底层值定义计算属性的 getter。

Riverpod 状态管理

Provider 定义：导入 riverpod_annotation，并添加生成文件的 part 指令。为函数添加 @riverpod 注解以创建简单的 provider。通过 ref.read 读取其他 provider，并返回仓库实例。通过返回 Future 类型创建异步 provider。对于有状态的 provider，创建继承生成的下划线类的类，重写 build 方法设置初始状态，并添加使用 AsyncValue.guard 修改状态的方法。

Widget 集成：创建 ConsumerWidget 子类。在 build 方法中，将 WidgetRef 作为第二个参数接收。使用 ref.watch 监听 provider 值。使用 when 方法处理 AsyncValue，并提供 data、loading 和 error 回调。使用 ref.invalidate 刷新数据。在 StatefulWidget 中使用 ref.listen 执行显示 snackbar 等副作用。

使用 Riverpod 的 StatefulWidget：继承 ConsumerStatefulWidget 和 ConsumerState。在 initState 中初始化 TextEditingController，并在 dispose 中释放。在 build 中使用 ref.listen 执行副作用。检查 isLoading 状态，在异步操作期间禁用按钮。使用 ref.read 和 notifier getter 访问通知器方法。

go_router 导航

路由器配置：创建带有 initialLocation 的 GoRouter 实例。定义 routes 数组，其中包含带有 path、name 和 builder 的 GoRoute 对象。在 routes 数组中嵌套路由。使用 ShellRoute 创建持久化导航壳。使用 NoTransitionPage 创建 pageBuilder，以实现标签页导航。实现 redirect 回调，检查身份验证状态，并返回重定向路径；若允许导航，则返回 null。定义 errorBuilder 处理错误。

导航方法：使用 context.go 根据路径进行声明式导航。使用 context.canPop 检查后再调用 context.pop。

平台通道

Dart 实现：定义一个类，使用通道名称字符串定义 MethodChannel 和 EventChannel 常量。创建异步方法，通过 invokeMethod 调用通道上的方法，并捕获 PlatformException。对于流式数据，调用 EventChannel 上的 receiveBroadcastStream，并将事件映射为类型化对象。使用 setMethodCallHandler 设置方法调用处理器，以接收来自原生代码的调用。

Widget 模式

自适应布局：创建一个 StatelessWidget，并为 child、destinations、selectedIndex 和 onDestinationSelected 回调设置必需参数。在 build 中，使用 MediaQuery.sizeOf 获取宽度。根据宽度断点使用条件返回。宽度低于 600 像素时，返回一个在 bottomNavigationBar 中包含 NavigationBar 的 Scaffold。宽度低于 840 像素时，返回一个包含 Row 的 Scaffold，其中 Row 包含 NavigationRail 和扩展的 child。宽度高于 840 像素时，返回一个包含 Row 的 Scaffold，其中 Row 包含 NavigationDrawer 和扩展的 child。

测试

Widget 测试示例：在 test 主函数中，使用 mock providers 的 overrides 创建 ProviderContainer。使用 tester.pumpWidget，并以 UncontrolledProviderScope 包裹包含待测 widget 的 MaterialApp。使用 find.byType 断言初始加载状态。调用 tester.pumpAndSettle，等待异步操作完成。使用 find.text 断言最终状态。

如需全面了解测试模式，请参阅 examples.md。

高级模式

全面涵盖以下内容：

• 适用于所有平台的自适应和响应式 UI
• 动画模式（隐式、显式、hero、交错、物理）
• 专家级 widget 开发与优化
• 使用 Riverpod 实现整洁架构
• 使用 Isolates 执行计算密集型操作
• 自定义渲染对象和绘制
• FFI 和特定平台的插件
• 性能优化和分析

请参阅：reference/adaptive.md，了解响应式布局；reference/animations.md，了解动画模式；reference/expert.md，了解专家级开发

Context7 库映射

Flutter/Dart 核心：

• /flutter/flutter - Flutter 框架
• /dart-lang/sdk - Dart SDK

状态管理：

• /rrousselGit/riverpod - Riverpod 状态管理
• /felangel/bloc - BLoC 模式

导航和存储：

• /flutter/packages - go_router 和官方软件包
• /cfug/dio - HTTP 客户端
• /isar/isar - NoSQL 数据库

搭配使用效果良好

• moai-lang-swift - 用于平台通道的 iOS 原生集成
• moai-lang-kotlin - 用于平台通道的 Android 原生集成
• moai-domain-backend - API 集成和后端通信
• moai-quality-security - 移动安全最佳实践
• moai-essentials-debug - Flutter 调试和 DevTools