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