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

jiao00001

268人浏览 · 2026-09-13 17:33:19

jiao00001 · 2026-09-13 17:33:19 发布

鸿蒙 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 配置