鸿蒙 ArkUI 入门阶段复盘：知识体系脑图 + 高频踩坑 + 精进路线

这是我鸿蒙自学路线的第一阶段复盘，覆盖 Day27 ~ Day31 共 5 天的内容：状态管理 V2 → 布局体系 → Grid 与后台任务 → ArkWeb 与服务卡片 → 登录列表实战，并额外独立完成了一个 Huawei_Shop 华为商城综合作业。

本文按「目标完成度 → 知识体系 → 难点攻克 → 高频问题 → 项目成果 → 薄弱点 → 下阶段规划」七部分系统梳理，适合正在学 ArkUI 的同学收藏对照复盘。

---

一、阶段目标完成情况

天数	学习主题	计划目标	完成度	交付物
Day27	状态管理 V2	跑通 13 个装饰器 Demo	✅ 100%	Demo1~13 + 会员等级积分作业页
Day28	布局体系	8 个布局知识点 + 电商首页	✅ 100%	Demo1~8 + 仿京东首页
Day29	Grid + 后台任务	响应式网格 + 两种后台任务	✅ 95%	demo1~5（短时任务需真机验证）
Day30	ArkWeb + 卡片	三种 Web 通信 + 服务卡片	✅ 90%	3 个通信 Demo + 2×2/2×4/4×4 卡片
Day31	登录 + 列表	登录校验跳转 + 账本流水	✅ 100%	随手记登录页 + 20 条流水列表
加餐	综合实战	独立复刻商城作业	✅ 100%	Huawei_Shop 完整工程

二、核心知识体系梳理

这一阶段的内容可以归纳成 五大主干，建议对照下图建立整体认知：

下面是脑图对应的缩进结构，也可以直接导入 XMind：

ArkUI 第一阶段（Day27-31）
├── 1. 状态管理 V2
│   ├── 组件内：@Local / @Param / @Event
│   ├── 深度观测：@ObservedV2 + @Trace
│   ├── 派生与监听：@Computed / @Monitor
│   ├── 跨层级：@Provider / @Consumer
│   └── 全局/持久化：AppStorageV2（内存）/ PersistenceV2（落盘）
├── 2. 布局能力
│   ├── 弹性：flexGrow / flexShrink / layoutWeight / Flex(wrap)
│   ├── 对齐与比例：justifyContent / aspectRatio
│   ├── 网格：Grid / GridItem / GridRow / GridCol（断点 sm/md/lg）
│   ├── 响应式：windowSizeChange + px2vp / displayPriority
│   └── UI 复用：@Builder + 条件渲染
├── 3. 后台任务
│   ├── 短时任务 requestSuspendDelay（≤3 分钟/次）
│   └── 延迟任务 workScheduler（条件触发，需 ExtensionAbility）
├── 4. ArkWeb 与卡片
│   ├── 加载：loadUrl / loadData
│   ├── 通信：runJavaScript（原生→H5）/ javaScriptProxy（H5→原生）/ WebMessagePort（双向）
│   └── 服务卡片：FormExtensionAbility + 2×2/2×4/4×4
└── 5. 页面与数据
    ├── 路由：router.pushUrl / back / clear + params 传参
    ├── 表单：TextInput + onChange + promptAction Toast 校验
    ├── 列表：List + ForEach + 键生成器
    └── 分层：model（User/Record/Goods）+ Repo + Mock 数据

主干 1：状态管理 V2（本阶段最烧脑的部分）

装饰器	作用方向	一句话记忆
@Local	组件内部	V2 版的"私有状态"，替代 @State
@Param	父 → 子	单向输入，子组件不能随意改
@Event	子 → 父	子组件回调通知父组件
@ObservedV2 + @Trace	对象层面	嵌套对象深层属性变化也能被观测
@Computed	派生	依赖变化自动重算，类似计算属性
@Monitor	监听	能拿到变化前后的值（before / now）
@Provider/@Consumer	跨层级	祖先与后代直接共享，不用逐层透传
AppStorageV2	全局	内存单例，杀进程即失效
PersistenceV2	全局	自动落盘，重启不丢

主干 2：布局选型决策

• 线性排列 → Row/Column/Flex；需要自动换行 → Flex({ wrap: FlexWrap.Wrap })
• 均分/占比 → .layoutWeight(n)（最常用）、flexGrow/flexShrink
• 固定宽高比（如商品图 1:1）→ .aspectRatio()
• 规整网格 → Grid；整页响应式栅格 → GridRow/GridCol
• UI 片段复用 / 条件切换横竖向 → @Builder

---

三、重点难点攻克记录

难点 1：V1 和 V2 到底怎么选

两套体系不能混用：V1 是 @Component + @State + @Prop + @Link，V2 是 @ComponentV2 + @Local + @Param + @Event。V2 的观测粒度更细，配合 @ObservedV2/@Trace 能精确追踪嵌套对象的某个属性。

攻克方式：我把同一个"改嵌套对象属性"的需求分别用 V1（Demo8）和 V2（Demo3）各写一遍对比，结论是——新项目直接全量 V2，只有维护老代码时才需要读 V1。

难点 2：AppStorageV2 与 PersistenceV2 的坑

对比项	AppStorageV2	PersistenceV2
存储位置	内存	磁盘（自动持久化）
生命周期	进程结束即清空	重启应用仍在
适用数据	全局临时状态（当前用户、主题）	用户偏好、草稿

限制要记牢：不支持 Map/Set、单 key ≤ 8K、异步写入在极端退出时可能丢失最后一次修改。重要数据仍需走数据库/Preferences 兜底。

难点 3：短时任务 vs 延迟任务

对比项	短时任务（Day29 demo4）	延迟任务（Day29 demo5）
API	requestSuspendDelay	workScheduler.startWork
时机	申请即执行	网络/充电/电量等条件满足后系统调度
时长	单次 3 分钟，每日 10 分钟	单次最多 20 分钟
实现	Ability 内直接调	必须写 ExtensionAbility
用户感知	有通知栏提示	无感知

难点 4：ArkWeb 三种通信方式怎么选

方式	方向	特点	我的选型场景
runJavaScript	原生 → H5	Promise 异步，必须等 onPageEnd	改 H5 样式、取 DOM 值
javaScriptProxy	H5 → 原生	把 ArkTS 对象注入 H5 的 window	H5 按钮调原生能力
WebMessagePort	双向	端口对通信，官方推荐	商城 H5 与原生高频交互

难点 5：路由传字符串 vs 传对象

Day31 传的是字符串 params: { username: user.name }；到了 Huawei_Shop 升级为传整个对象 params: { user: userInfo }，目标页需要在 aboutToAppear() 里取参并用可选链防空：

aboutToAppear() {
  const params = router.getParams() as PageParams
  if (params?.user) {
    this.user = new User(params.user.name, params.user.phone, params.user.gender)
  }
}

踩过一次 undefined 白屏后，我养成了接收端永远写 interface + 可选链的习惯。

---

四、高频问题汇总（本阶段真实踩坑）

#	问题现象	根因	解决方案
1	@ComponentV2 中 @State 标红	V1/V2 装饰器混用	换 @Local
2	跳转后标题出现 undefined	误把类名 User 当值传入	改传 user.name，接收端 interface 断言
3	ForEach 控制台告警、刷新异常	缺键生成器	补第三参，用唯一 id 生成 key
4	$r('app.color.xxx') 找不到资源	颜色未注册	在 color.json 先声明
5	media 图片不显示	未放入目录/命名不规范/未重编译	规范命名放入 media/ 后重新 Build
6	新页面打开白屏	忘记注册路由	main_pages.json 的 src 中登记页面
7	内容超出屏幕不滚动	直接堆 Column	外层套 Scroll
8	ForEach 分类标签 key 重复	数据源有重复文本	key 用 ${item}_${index} 保证唯一
9	Web 调 JS 拿不到结果	页面未加载完就调用	在 onPageEnd 回调后再执行
10	延迟任务不触发	没满足调度条件 / 缺 ExtensionAbility 注册	检查网络充电条件与 module.json5 配置

---

五、实操项目练习成果

1. Day27 会员等级 + 积分签到页（状态管理综合作业）

综合运用 @Computed（等级自动判定）、@Monitor（积分变化打点）、AppStorageV2（全局用户信息）。

2. Day28 仿京东电商首页

@Builder 拆顶栏/导航/商品三区，Flex(wrap) 做频道入口，aspectRatio 固定商品图比例。

3. Day30 华为商城商品列表 + 服务卡片

ArkWeb 加载商城 H5 作业页，并用 Form Kit 实现 2×2 / 2×4 / 4×4 三种尺寸桌面卡片。

4. Day31「随手记」账本

登录 → 20 条收支流水列表，支出红色 -、收入绿色 +，图标区分类型。

5. Huawei_Shop 华为商城（独立加餐实战）

不看教程独立复刻：手机号登录（13888888888 / 123456）→ 携带 User 对象跳转 → 商城首页（账号信息卡 + Flex 换行分类标签 + 20 条热门商品单列），完整走通 DevEco 工程的搭建、资源配置与路由注册。

---

六、自身薄弱点分析（对自己诚实）

1. 后台任务与卡片仍停留在"跑通 Demo"层面：真机上的保活策略、卡片刷新时机（定时/定点/下次亮屏）没有系统验证，条件调度边界模糊。
2. 状态管理"会用但选型犹豫"：写新页面时常纠结该用 @Local 还是 AppStorageV2，缺少"数据作用域"先行的设计习惯。
3. 工程化能力薄弱：目前数据全靠 Mock，没接触过首选项 Preferences、关系型数据库、HTTP 真实接口与异常处理。
4. 调试效率低：遇到白屏多靠"肉眼读代码"，对 HiLog 日志、Inspector 布局检查工具使用不熟。
5. UI 还原度一般：颜色、间距多靠感觉调，尚未形成设计稿（vp/fp 单位、栅格规范）驱动开发的习惯。

---

七、下一阶段精进规划（Day32+）

第 1 步：数据与网络（1 周）

• Preferences 轻量存储落地（记住登录态）
• @ohos.net.http 封装统一请求层（拦截、loading、错误兜底）
• 把账本 / 商城的 Mock 数据替换为真实接口

第 2 步：能力扩展（1 周）

• 通知与后台任务真机专项验证
• 服务卡片增加动态刷新与点击跳转
• ArkWeb 项目实战：H5 商城与原生完整交互闭环

第 3 步：工程化与质量（持续）

• 引入 HiLog 统一日志、TS 严格类型（interface 全覆盖）
• 学习 MVVM 分层：UI / ViewModel / Repository / Service
• 每个项目补齐 README 与运行截图，沉淀可复用脚手架
  

---

写在最后

这 5 天最大的体会：ArkUI 的学习曲线是"概念密集但反馈极快"——状态管理和布局的概念一天能塞进来七八个，但每一个都能在 Previewer/模拟器里立刻看到效果。坚持"当天知识点必须当天用作业消化"，知识才不会停留在抄 Demo。

复盘不是终点，是为了让下一轮学习不欠债。如果这篇复盘对你有帮助，欢迎 点赞 ⭐ 收藏关注，下阶段我会继续更新「鸿蒙数据持久化 + 网络请求」系列，我们一起从入门走向能独立做产品 💪

---

系列导航：Day27 状态管理 ｜ Day28 布局实战 ｜ Day29 Grid 与后台任务 ｜ Day30 ArkWeb 与卡片 ｜ Day31 登录与列表 ｜ 加餐：华为商城实战