HaierEnergy · Flutter 学习文档
基于 HaierEnergy（海尔新能源 App，Flutter）真实项目代码梳理的体系化学习教程。
适合谁
前端（React / Vue）转 Flutter 的初学者。每个 Flutter / Dart 知识点都先给一个前端类比，再落到本项目真实代码。
项目背景
| 项 | 值 |
|---|---|
| 包名 | com.haier.energy.platform |
| Dart import 前缀 | package:haierenergy/... |
| Flutter SDK | >=3.4.3 <4.0.0 |
| 规模 | lib/ 449 个 Dart 文件 |
| 来源 | 由 uni-app 老项目迁移而来 |
| 技术栈 | Riverpod 2.6 + GoRouter 14 + Freezed 2.5 + Retrofit 4 + Dio 5 |
文档清单与阅读顺序
序号 NN 全局递增，按序号读即可。
| 序号 | 类别 | 标题 |
|---|---|---|
| 00 | 01-入门导览 | 学习路线图 ← 先读这篇 |
| 01 | 02-Dart基础 | Dart 语言基础 |
| 02 | 03-Flutter基础 | Flutter 核心基础 |
| 03 | 03-Flutter基础 | Flutter 渲染原理与生命周期 |
| 04 | 03-Flutter基础 | Flutter 布局与滚动进阶 |
| 05 | 03-Flutter基础 | Flutter 交互与动画 |
| 06 | 02-Dart基础 | Dart 异步并发与进阶语法 |
| 07 | 04-项目架构 | 项目架构总览 |
| 08 | 04-项目架构 | 状态管理 Riverpod |
| 09 | 04-项目架构 | 数据层链路 |
| 10 | 05-项目实战 | 页面开发实战 |
| 11 | 04-项目架构 | 组件与主题 |
| 12 | 05-项目实战 | 分页与列表 |
| 13 | 05-项目实战 | 路由与导航 |
| 14 | 06-平台能力 | 国际化 |
| 15 | 06-平台能力 | 权限与设备能力 |
| 16 | 07-工程化 | 工程化与调试 |
| 17 | 07-工程化 | 常见陷阱与速查表 |
| 18 | 06-平台能力 | 本地存储与持久化 |
| 19 | 07-工程化 | 测试实战：单元·Widget·集成 |
| 20 | 07-工程化 | 异常捕获与错误监控 |
序号 06 虽属「02-Dart基础」，但阅读顺序排在 03~05 之后—— 事件循环、Isolate、Stream 需要先理解 Flutter 单线程渲染模型才好消化。 详见
00-学习路线图的说明。
三条常用捷径
| 你的情况 | 读哪几篇 |
|---|---|
| 急着改 bug（第一天就要动代码） | 02 → 07 → 17 |
| 只想能写页面 | 01 → 02 → 08 → 10 → 11 |
| 只要接接口 | 01 → 07 → 09 |
每章结构
- 前端概念对照 —— 开篇一张表，把新知识挂到已有认知上
- 本项目真实代码 —— 标注
文件:行号+ 关键片段，可跳转核对 - 动手练习 —— 可运行的最小 Demo
- 自检清单 —— 「学完你应该能做到什么」
文档可信度约定
- 每段代码都从 HaierEnergy 当前代码核实后写入，标注
文件:行号 - 不粘贴大段代码（只给 10~20 行关键片段），避免代码改动后文档腐烂
- 该项目
docs/下另有 15 篇既有文档，其中docs/README.md有三处已过时（包名、i18n 入口、学习路径目录）。冲突时以本系列为准，详见00-学习路线图的「现有文档地图」
配套练习场
HaierEnergy 项目内 lib/main_playground.dart 是专为本文档新建的空白练习场（不属于业务代码，可随时删除）：
bash
fvm flutter run -t lib/main_playground.dart03~06 章的通用知识 Demo 粘进去即可运行。其余章节的练习走 test/ 下的 widget test。