115 lines
5.7 KiB
Markdown
115 lines
5.7 KiB
Markdown
# 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 均可直接跳转。
|