中级课程笔记做到第二篇这个系列已经慢慢形成一套自己的思考框架了。最近在梳理状态管理V2的时候我发现真正值得停下来琢磨的并不是那一堆看起来眼花缭乱的装饰器而是装饰器背后对“数据从哪里来、状态由谁维护、事件往哪里走”这三个问题的重新回答。尤其是Once和Event一个处理初始化时的数据快照一个处理子组件向父组件的事件上报结合起来之后很多以前需要靠约定和维护来约束的东西现在直接用框架语义就表达清楚了。这篇文章会把我在课程笔记里整理的思路、踩过的坑以及可以直接抄走的代码片段一并放出来目标读者是已经能熟练使用V1状态管理、正在往V2迁移的开发者也包括刚接触鸿蒙状态管理但想一步到位学V2的新人。1. 从 V1 到 V2升级到状态管理V2要改哪些认知1.1 V1时代最让人头疼的三个问题V1时代我们主要围绕State、Prop、Link、ObjectLink、Provide、Consume、Watch这些装饰器搭业务。单个页面里数据流还清晰一旦页面复杂起来比如列表页里套多个卡片组件、卡片里再套操作面板问题就出来了。第一个痛点是状态来源的语义不够清楚同样是子组件里的一个变量它到底是父组件传进来的受控数据还是子组件自己维护的局部状态从声明上很难一眼看出。第二个痛点是数组和对象深层修改的观察深度很脆弱ObjectLink要求类必须被Observed装饰列表里某一项的某个字段改变时偶尔会出现UI不刷新但数据已经变了的情况排查起来特别费劲。第三个痛点是事件传递没有一个规范的结构常见做法是父组件把一个箭头函数作为属性传给子组件子组件在自己的点击事件里调用。函数属性确实能跑但经过两三层传递之后代码的可读性明显下降组件接口上哪些是数据、哪些是回调靠命名区分时间一长团队内部就只能靠口头约定维持秩序。1.2 V2把“数据”和“事件”彻底分开定义V2的出发点就是把这些模糊地带变成显式约束。新装饰器体系里观察能力下沉到了类的属性层面ObservedV2和Trace负责让普通类具备可观察能力组件内的状态被拆得更细StateV2是组件私有状态Param表示外部传入参数Param前可以叠加Once让参数只在首次初始化时生效Event表示外部传入的事件回调Monitor负责监听状态变化并触发后续逻辑Provider和Consumer负责跨层级共享数据。这样拆完以后组件对外接口变成了两个非常标准的通道数据走Param事件走Event内部状态走StateV2状态变化后的副作用通过Monitor串联。从更高维度看V2实际上是把单向数据流从“概念倡导”变成了“结构保证”父组件的状态只能通过参数流到子组件子组件的反馈只能通过事件流回父组件绕不过去。1.3 我切换V2后的第一感受我在整理笔记时用一个小模拟项目把同样的购物车功能分别用V1和V2实现了一遍最直观的感受是V2的组件“接口感”更强了数据结构上会主动设计Param和Event两层组件对外暴露的配置项就像函数签名一样明确。另一个感受是排查问题的思路变清晰了V2的UI更新依赖是精确的不用再因为担心“不知道谁订阅了我”而被迫把状态放到全局可以放心使用容器内的局部状态。这里先不展开性能细节但可以确定的是V2不是V1的语法糖替换而是对“职责”的一次重新分配理解这一点后面看Once和Event才不会把它们当成两个孤立的装饰器。2. Once 装饰器怎么用一次性初始化的边界与实践2.1 Once到底管住了什么Once的定位一句话就能说清让一个参数只在首次初始化时生效之后父组件再怎么更新子组件里的这个参数也不会再被覆盖。它解决的核心矛盾是“外部参数”和“内部状态”的边界问题。在V2之前子组件里凡是父组件传进来的数据在父组件状态变化时都会触发子组件刷新这看起来自然但业务里有一种恰恰相反的需求就是“只在创建时接收一次之后我自己维护”。比如详情页的路由参数、列表项的初始快照、进入页面时从接口拿到的初始配置都属于这种情况。如果不加Once父组件随便一个无关状态变化都可能触发参数同步导致子组件被重渲染甚至内部已经修改过的状态被重置。这里我用一个最简单的例子说明。子组件接收一个initCount参数首次进来时是父组件给的值之后用户可以在子组件里对这个值做各种加减操作。如果不加Once父组件每次刷新都会把initCount重新同步过来用户刚改了一半的数字瞬间被覆盖加上Once只有第一次创建时会取父组件的值之后这个参数就跟父组件“断开了同步”。2.2 标准写法Once变量只当快照内部状态另立门户Once的正确使用姿势是把它当成“初始化快照”不要直接在业务里去改它。官方对Once变量的约束可以理解为初始化之后保持只读组件内部不要再给它赋值因为它的语义就是“一次性”。如果业务上确实需要基于这个初始值做后续修改那就复制一份到StateV2上后面所有操作都走本地状态。一个典型的完整写法是这样的ComponentV2 struct DetailCard { Param Once cardId: string ; StateV2 localInfo: CardInfo { id: , title: }; aboutToAppear(): void { // 把一次性参数转存到本地状态后续页面内部逻辑只操作 localInfo this.localInfo getCardFromId(this.cardId); } build() { Column() { Text(this.localInfo.title) .fontSize(20) .fontWeight(FontWeight.Bold) // 这里继续渲染卡片详情 } .padding(16) } }为什么一定要转存因为Once变量不可变如果直接在aboutToAppear里对this.cardId做修改等于违背了设计意图。转存到StateV2之后本地状态就能自由变更UI也会正常响应。这个习惯需要刻意养成凡看到Once第一反应是把值赋给一个可变状态而不是在后续代码里反复读它。2.3 适用场景与反面教材一并说清适合加Once的场景有这些详情页从列表进入时携带的ID页面生命周期内ID不会变组件初始化时需要读取父组件配置但配置变化不应重置组件内部操作进度进入页面时从接口或本地存储取到的初始展示数据上报、统计、埋点过程中需要固定的跟踪标识不适合加Once的场景同样重要。搜索弹窗里的输入框父组件的搜索关键词变化时需要实时同步到子组件就不能加Once。受控表单输入值、需要父组件随时重置的计时器参数也不能加。还有一类容易踩坑的情况父组件的某个值虽然不会主动变但它可能由异步接口返回第一次进入时父组件还没拿到数据默认值先传过去了等接口返回再更新。这个时候加Once就会导致子组件永远拿到默认值。解决办法是先等父组件数据就绪再创建子组件或者用if包裹组件实例保证组件创建时数据已经准备好。3. Event 装饰器怎么用子组件事件上报通道的完整拆解3.1 为什么V2要单独设计一个事件装饰器V1里子组件反馈给父组件通常是传一个函数属性比如onClick{() this.handleClick()}然后在子组件内部调用。这种写法本身没问题但问题在于它和普通数据属性没有结构性区别。组件接口里既有一堆Prop参数又有一堆函数类型参数阅读时只能靠命名习惯去猜哪些是数据、哪些是回调。Event把“事件”作为一种独立装饰器类型摆到接口层让组件与组件之间的协议变得非常明确凡是Event修饰的都是外部注入的处理函数凡是Param修饰的都是外部注入的数据。我们不再需要靠命名去区分类型系统本身就表明了角色这对多人协作和组件复用都很友好。3.2 Event的基本定义与调用方式Event的声明方式很直接和普通函数类型属性最大的区别是框架层面认可它是一个事件出口。我习惯在声明时给一个空函数作为默认值避免子组件拿到undefined之后调用报错。代码示例ComponentV2 struct ProductCard { Param name: string ; Param price: number 0; Event onAdd: () void () {}; build() { Column({ space: 8 }) { Text(this.name).fontSize(18) Text(¥${this.price}).fontSize(14).fontColor(#999999) Button(加入购物车) .onClick(() { // 子组件只负责把“加入购物车”这个动作抛出去 this.onAdd(); }) } .padding(12) .backgroundColor(#FFFFFF) .borderRadius(12) } }父组件传事件时和普通参数一样写在子组件构造参数里用箭头函数就能闭包捕获父组件的状态ProductCard({ name: 鸿蒙状态管理实战, price: 99, onAdd: () { this.badgeCount; } })这是一种很干净的合作关系子组件只管“什么时候触发事件”不关心事件之后父组件做了什么父组件只管“事件来了怎么处理”不关心子组件内部怎么呈现。3.3 事件携带参数与Monitor联动是高频组合Event当然可以携带参数。比如购物车移除商品时需要把商品ID传给父组件可以这样定义Event onRemove: (id: string) void () {};调用时this.onRemove(this.productId)。参数类型要写清楚这样组件接口一目了然父组件拿到事件时就能通过参数感知上下文。还有一个特别高频的组合子组件内部状态变化后自动通过Event通知外部。实现方式很典型子组件里先用StateV2保存状态再用Monitor监听这个状态在监听回调里调用Event。这里Monitor就相当于状态变化的触发器把“内部状态更新”和“外部事件上报”连起来。我完整写一个计数器组件ComponentV2 struct Counter { StateV2 count: number 0; Event onChange: (value: number) void () {}; Monitor(count) onCountChange() { // count 每次变化都会进入这里顺手把新值抛出去 this.onChange(this.count); } build() { Row({ space: 16 }) { Button(-).onClick(() { this.count--; }) Text(${this.count}).fontSize(24) Button().onClick(() { this.count; }) } } }这样父组件完全不用干预子组件的加减逻辑只通过onChange拿到最终数值。这个模式适合所有“子组件内部有复杂交互但父组件需要感知结果”的场景比如评分组件、步进器、日期选择面板。需要注意Monitor回调在状态变化后会触发如果回调里再改同一个状态容易造成循环所以Event上报时不要再顺手修改被监听的状态。4. 状态管理V2实战购物车角标与倒计时两个案例4.1 案例一购物车角标让数据控制权留在父组件购物车角标是一个很经典的“子组件触发、父组件更新”场景。商品卡片负责展示商品信息并处理点击反馈购物车角标数量必须由父组件维护否则多个商品卡片各自改一个全局变量会乱套。用Event来解决父组件持有真正的badgeCount状态子组件通过事件上报“加入购物车”动作。父组件代码Entry ComponentV2 struct CartPage { StateV2 badgeCount: number 0; build() { Column({ space: 16 }) { ProductCard({ name: 鸿蒙状态管理进阶, price: 99, onAdd: () { this.badgeCount; } }) Text(购物车角标数量${this.badgeCount}) .fontSize(16) } .padding(16) } }子组件代码ComponentV2 struct ProductCard { Param name: string ; Param price: number 0; Event onAdd: () void () {}; build() { Column({ space: 8 }) { Text(this.name).fontSize(18) Text(¥${this.price}).fontSize(14).fontColor(#999999) Button(加入购物车) .onClick(() { // 这里可以放心做动画、节流、埋点等内部逻辑 this.onAdd(); }) } .padding(12) } }这个例子里子组件不持有badgeCount也不关心角标怎么显示它只在合适的时机抛出一个“加入购物车”信号。父组件拿到信号后统一改自己的状态UI自动刷新。如果后面需求变成“同一个商品不能重复加入”那只需要在父组件的onAdd回调里做校验子组件完全不用动。4.2 案例二倒计时任务让父组件通过参数重置子组件倒计时场景比购物车角标更进一步它需要父组件修改一个参数来驱动子组件重置同时子组件结束时还要通知父组件。这里不适合用Once因为父组件的duration需要动态变化并同步给子组件所以用普通Param再配合Monitor监听参数变化来执行重置逻辑。父组件代码Entry ComponentV2 struct TimerPage { StateV2 duration: number 60; StateV2 finishedCount: number 0; build() { Column({ space: 16 }) { Row({ space: 12 }) { Button(时长-5) .onClick(() { if (this.duration 5) { this.duration this.duration - 5; } }) Button(时长5) .onClick(() { this.duration this.duration 5; }) } Text(当前倒计时时长${this.duration}s) CountdownTimer({ duration: this.duration, onFinished: () { this.finishedCount; } }) Text(完成次数${this.finishedCount}) } .padding(16) } }子组件代码ComponentV2 struct CountdownTimer { Param duration: number 60; StateV2 remaining: number 0; Event onFinished: () void () {}; private timerId: number -1; aboutToAppear(): void { this.remaining this.duration; this.startTimer(); } aboutToDisappear(): void { this.stopTimer(); } Monitor(duration) onDurationChange() { // 父组件改了时长子组件立刻重置计时 this.remaining this.duration; this.startTimer(); } startTimer() { this.stopTimer(); this.timerId setInterval(() { this.remaining--; if (this.remaining 0) { this.stopTimer(); this.onFinished(); } }, 1000); } stopTimer() { if (this.timerId ! -1) { clearInterval(this.timerId); this.timerId -1; } } build() { Text(${this.remaining}s) .fontSize(36) .fontWeight(FontWeight.Bold) } }这个案例里值得一提的点是父组件没有调用子组件的任何方法只是改了一个duration参数子组件就完成了重置子组件也没有直接操作父组件的状态只是抛出一个onFinished事件父组件自己累加完成次数。整个数据流是“参数往下流事件往上抛”逻辑边界非常清楚。4.3 案例三详情页初始化体现Once的收敛价值最后看一个Once配合实际页面的例子。列表页点击一项进入详情页详情页需要根据传入的ID加载数据但详情页内部可能还有收藏、点赞、编辑等交互状态。这个ID在整个详情页生命周期内都不应该变所以非常适合用Once。Entry ComponentV2 struct DetailPage { Param Once itemId: string ; StateV2 detailData: PageData | null null; aboutToAppear(): void { this.fetchDetail(this.itemId); } fetchDetail(id: string) { // 这里封装数据请求按 id 拉取详情数据 requestDetail(id).then((data) { this.detailData data; }); } build() { Column({ space: 12 }) { if (this.detailData) { Text(this.detailData.title).fontSize(22) Text(this.detailData.content).fontSize(16) } else { Text(加载中...) } } .padding(16) } }如果不加Once一旦父页面状态变化导致列表重渲染传给详情页的itemId虽然没变但子组件的Param同步机制会重新触发一次渲染甚至可能引发不必要的重新请求。加了Once之后itemId只在首次进入时生效后续父组件的刷新不会打断详情页自己的状态。5. 状态管理V2踩坑实录Once和Event的常见问题排查5.1 Once变量到底能不能在组件内部修改这个问题基本是新手必问。根据我在课程实验中的验证Once变量在初始化之后应该被视为只读组件内部直接给它赋值要么被编译器约束要么在行为上不生效。它的设计意图就是一次性快照不是在子组件里继续演变的动态数据。如果业务上必须改标准做法是转存到StateV2后续操作全部走本地状态。我在实际开发里也见过有人硬改Once变量最后状态确实没更新排查半天才发现是这里的问题。5.2 Event调用时提示undefined或没反应最常见的原因是声明时没有给默认空函数。如果代码写成Event onAdd?: () void;子组件内部调用时就会遇到undefined。正确写法是Event onAdd: () void () {};确保事件永远是一个可调用对象。还有一个隐藏问题事件回调里如果要使用父组件的状态尽量在父组件内部用箭头函数定义不要从外部模块传入一个已经“固化”的函数引用否则可能会捕获到旧值。简单来说onAdd: () { this.handleAdd(); }这种内联箭头函数是安全的因为它每次都会从父组件实例读取最新状态。5.3 Monitor监听Once变量为什么不触发这是一个概念混淆的典型坑。Once变量在初始化之后就不再变化Monitor自然也没有机会触发。如果发现需要监听一个“初始化后不该变”的变量大概率是这个变量根本不应该加Once。正确的拆法是真正需要初始快照的内容用Once接收并转存需要响应外部变化的内容用普通Param给Monitor去监听。一句话总结Monitor监听的是“会变的东西”不会变的东西就别惦记着监听。5.4 异步数据下Once默认值覆盖问题父组件的数据是异步拉取的第一次创建子组件时数据还没回来父组件把默认值传给了Once变量等接口返回后父组件更新了数据但Once已经完成初始化不会重新同步。这种情况不算框架的bug而是Once的语义本身就是“只认第一眼”。解决办法有两种一是等数据就绪再创建子组件比如用if (this.dataReady) { ChildView({ ... }) }包裹二是去掉Once改用普通Param配合Monitor做后续同步。具体用哪种取决于业务逻辑里“内部状态是否要随外部变化而重置”。如果是详情页这种固定ID场景推荐等数据就绪后再创建组件。5.5 V1和V2混用时的观察失效问题老项目迁移过程中经常出现V1和V2装饰器混用的情况。比如一个数据类用Observed装饰同时又被V2的组件用Monitor监听表现就会不稳定。原因在于两套观察体系在处理依赖和通知时机上不一致。我的建议是同一组件树内部尽量保持一致要么整棵子树都是V1要么都是V2桥梁位置放在页面入口或者单独的数据适配层不要在一个组件里一半V1一半V2。虽然V2已经考虑了一些兼容场景但混用带来的排查成本远高于它带来的便利。如果你正在做V2迁移建议先从最简单的Once入手感受一下“参数只启动一次”对页面稳定性的帮助再去碰Event那一层事件抽象。我个人的体会是把这两个装饰器用顺以后组件接口设计会自然往“数据参数化、事件回调化、内部状态私有化”的方向收敛代码评审时再也不需要反复解释“这个属性为什么传函数、那个属性为什么传数据”。状态管理V2的门槛不高但它要求开发者把组件之间的边界想得足够清楚这份收益会在后续维护中成倍兑现。
