flutter架构项目基础

2026-09-04 15:22:20 +08:00
parent 70967229d0
commit 0c5aee59c0
265 changed files with 35484 additions and 0 deletions
@@ -0,0 +1,114 @@
+# docs/demos —— Demo 学习文档索引
+
+> 本目录为 `lib/pages/demo/` 下 **29 个独立功能模块**逐一配套的学习文档，
+> 面向 Flutter 初学者：讲清**实现用法和思想**（为什么这么写），并标注踩坑记录。
+
+**配套文档**：项目整体架构（含 Riverpod / Isar 新手教程）见 [../exam_architecture.md](../exam_architecture.md)，
+本目录是"每个功能怎么实现"的细节版，两者配合阅读效果最佳。
+
+---
+
+## 一、分类索引（29 个）
+
+### 🧱 基础布局（13）
+| Demo 文件 | 一句话 | 文档 |
+|---|---|---|
+| align_demo.dart | 对齐与约束：一行代码把一个组件摆到任意位置 | [align_demo.md](align_demo.md) |
+| wrap_demo.dart | 流式布局：小标签自动换行，放不下就换一排 | [wrap_demo.md](wrap_demo.md) |
+| stack_demo.dart | 层叠布局：角标、遮罩、悬浮按钮全靠它 | [stack_demo.md](stack_demo.md) |
+| grid_demo.dart | 网格布局：GridView 三列宫格（九宫格） | [grid_demo.md](grid_demo.md) |
+| list_demo.dart | 长列表：ListView.builder 懒加载 + 下拉刷新 | [list_demo.md](list_demo.md) |
+| sliver_demo.dart | 可折叠顶栏：SliverAppBar 收起展开 + 吸顶 | [sliver_demo.md](sliver_demo.md) |
+| responsive_demo.dart | 响应式：一个页面同时适配手机/平板/桌面 | [responsive_demo.md](responsive_demo.md) |
+| text_demo.dart | 文本组件：样式、行高、溢出省略号 | [text_demo.md](text_demo.md) |
+| input_demo.dart | 输入框：TextField 全家桶 + 键盘类型 | [input_demo.md](input_demo.md) |
+| form_demo.dart | 表单校验：GlobalKey + validator 规则 | [form_demo.md](form_demo.md) |
+| theme_demo.dart | 主题：多品牌换肤、全局样式统一管理 | [theme_demo.md](theme_demo.md) |
+| seed_palette_demo.dart | 种子色：ColorScheme.fromSeed 一键生成配色 | [seed_palette_demo.md](seed_palette_demo.md) |
+| animation_demo.dart | 动画：隐式/显式/路由转场/Hero/CustomPaint | [animation_demo.md](animation_demo.md) |
+
+### 🌐 网络（3）
+| Demo 文件 | 一句话 | 文档 |
+|---|---|---|
+| dio_demo.dart | 请求封装：DioClient + ApiException 统一错误 | [dio_demo.md](dio_demo.md) |
+| dio_pro_demo.dart | 进阶：拦截器/重试/CancelToken/Web 兼容 | [dio_pro_demo.md](dio_pro_demo.md) |
+| oss_upload_demo.dart | 阿里云 OSS 直传：STS 临时凭证 + V4 签名 | [oss_upload_demo.md](oss_upload_demo.md) |
+
+### 💾 存储（2）
+| Demo 文件 | 一句话 | 文档 |
+|---|---|---|
+| isar_watch_demo.dart | 本地库 + 响应式：Isar 增删改查 + watch 自动刷新 | [isar_watch_demo.md](isar_watch_demo.md) |
+| wrong_flow_demo.dart | 完整业务链路：接口 + 本地 + watch 三层协作 | [wrong_flow_demo.md](wrong_flow_demo.md) |
+
+### 🧭 路由（4）
+| Demo 文件 | 一句话 | 文档 |
+|---|---|---|
+| router_demo.dart | 应用入口：路由表注册 + 首页组装 | [router_demo.md](router_demo.md) |
+| router_home_page.dart | 三种跳转姿势：push 传参 / await 返回值 / pushNamed | [router_home_page.md](router_home_page.md) |
+| detail_page.dart | 参数接收：构造传参 vs 命名路由 arguments | [detail_page.md](detail_page.md) |
+| picker_page.dart | 选择器页：pop 带值返回（选性别） | [picker_page.md](picker_page.md) |
+
+### 🧩 组件封装（6）
+| Demo 文件 | 一句话 | 文档 |
+|---|---|---|
+| note_picker_demo.dart | 多图选择页：加号格 + 缩略图 + 删除角标 | [note_picker_demo.md](note_picker_demo.md) |
+| image_demo.dart | 图片四来源 + BoxFit + 错误兜底 | [image_demo.md](image_demo.md) |
+| audio_player_demo.dart | 音频控制条组件（HTTP Range 验收） | [audio_player_demo.md](audio_player_demo.md) |
+| rich_text_demo.dart | HTML 富文本渲染 + 字号/深色注入 | [rich_text_demo.md](rich_text_demo.md) |
+| smooth_sheet_demo.dart | 常驻多停靠底部面板（非模态） | [smooth_sheet_demo.md](smooth_sheet_demo.md) |
+| share_demo.dart | 分享五场景：文本/图片/海报截图/存相册 | [share_demo.md](share_demo.md) |
+
+### 🎓 考试（1）
+| Demo 文件 | 一句话 | 文档 |
+|---|---|---|
+| exam_demo.dart | 试卷练习入口：大数据滑动验证（关联主架构） | [exam_demo.md](exam_demo.md) |
+
+---
+
+## 二、推荐学习路径（按顺序）
+
+```
+阶段 1  布局基础（约 1 周）
+        align → wrap → stack → grid → list → sliver → responsive
+
+阶段 2  文本与输入
+        text → input → form
+
+阶段 3  主题与动画
+        seed_palette → theme → animation
+
+阶段 4  路由导航
+        router → router_home_page → detail_page → picker_page
+
+阶段 5  数据层
+        isar_watch → wrong_flow
+
+阶段 6  网络层
+        dio → dio_pro → oss_upload
+
+阶段 7  组件封装（进阶）
+        image → audio_player → rich_text → smooth_sheet → note_picker → share
+
+阶段 8  综合实战
+        exam_demo → ../exam_architecture.md（完整架构）
+```
+
+> 建议：前 4 个阶段每天 1~2 个 demo，把每份文档"关键代码剖析"手敲一遍；
+> 阶段 5 之后开始读 [../exam_architecture.md](../exam_architecture.md)（Riverpod/Isar 前置知识）。
+
+---
+
+## 三、文档公约
+
+每份文档统一六章结构，方便快速定位：
+
+| 章节 | 内容 |
+|---|---|
+| 一、这个 Demo 解决什么问题 | 业务场景 + 对照 Vue 类比 |
+| 二、怎么运行 / 演示内容 | runApp 命令 + 演示点 |
+| 三、核心知识点（新手向） | 速查表 + 代码块 + 为什么这么写 |
+| 四、关键代码剖析 | 核心代码逐行解释 |
+| 五、踩坑记录 | 编号列表，每条 = 一个真实教训 |
+| 六、扩展思考 | 关联其他文档 + 真实项目落地建议 |
+
+文档之间用相对链接互引（如 `[list_demo.md](list_demo.md)`），GitHub / IDE 均可直接跳转。