name: flutter-dev
description: |-
    Flutter跨平台开发指南，涵盖 widget 模式、Riverpod/Bloc 状态管理、GoRouter 导航、性能优化及平台特定实现。包含 const 优化、响应式布局、测试策略和 DevTools 性能分析。
    使用场景：构建 Flutter 应用、实现状态管理（Riverpod/Bloc）、设置 GoRouter 导航、创建自定义 widget、优化性能、编写 widget 测试、跨平台开发。
license: MIT
metadata:
    version: "1.0.0"
    category: mobile
    sources:
        - flutter-expert by Jeff Smolinski (https://github.com/Jeffallan/claude-skills) — Flutter expert skill framework
        - Flutter Documentation
        - Riverpod Documentation
        - Bloc Library Documentation

Flutter 开发指南

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

快速参考

Widget 模式

性能模式

核心原则

Widget 优化

• 尽可能使用 const 构造函数
• 将静态 widget 提取到独立的 const 类中
• 对列表项使用 Key（ValueKey、ObjectKey）
• 对于状态相关 widget，优先使用 ConsumerWidget 而非 StatefulWidget

状态管理

• Riverpod 用于依赖注入和简单状态
• Bloc/Cubit 用于事件驱动的工作流和复杂逻辑
• 绝不直接修改状态（始终创建新实例）
• 使用 select() 最小化重建

布局

• 8pt 增量间距（8、16、24、32、48）
• 响应式断点：手机（<650）、平板（650-1100）、桌面（>1100）
• 通过灵活布局支持所有屏幕尺寸
• 遵循 Material 3 / Cupertino 设计指南

性能

• 优化前先使用 DevTools 进行性能分析
• 以 <16ms 帧时间为目标以实现 60fps
• 对复杂动画使用 RepaintBoundary
• 使用 compute() 卸载繁重任务

检查清单

Widget 最佳实践

• [ ] 所有静态 widget 使用 const 构造函数
• [ ] 列表项使用正确的 Key
• [ ] 状态相关 widget 使用 ConsumerWidget
• [ ] 不在 build() 方法内部构建 widget
• [ ] 将可复用 widget 提取到独立文件

状态管理

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

导航

• [ ] 使用 GoRouter 并配合类型化路由
• [ ] 通过重定向实现身份验证守卫
• [ ] 支持深度链接
• [ ] 跨路由保持状态

性能

• [ ] 使用 profile 模式测试（flutter run --profile）
• [ ] 帧渲染时间 <16ms
• [ ] 无不必要的重建（通过 DevTools 检查）
• [ ] 图片已缓存并调整大小
• [ ] 大量计算在隔离中执行

测试

• [ ] UI 组件的 widget 测试
• [ ] 业务逻辑的单元测试
• [ ] 用户流程的集成测试
• [ ] 使用 blocTest() 进行 Bloc 测试

参考资料

---

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