写这段代码前我主要对照了这几个官方章节https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-custom-components-freezehttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-v1-v2-migration-inner-componenthttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-provider-and-consumerhttps://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-user-defined-arktsnode-buildernodehttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-computed这一篇只围绕一个问题讲问题怎么发生、原因在哪里、解决时怎么取舍以及改完以后怎么验证。下面的代码和表格都服务于这个排查链路不做参数表搬运。很多 Builder 问题不是“不会抽组件”而是抽完以后参数不刷新。比如卡片右侧操作区复用了一个构建函数父组件的选中数量变了按钮文案没跟着变或者弹窗按钮组里想改父组件状态最后写成在 Builder 里直接改入参。代码能过一部分场景但边界一复杂就会乱。官方文档里对 Builder 参数传递规则讲得很细尤其是按值、按引用、按回调以及 API version 20 开始配合UIUtils.makeBinding()支持刷新和写回。我的理解很简单Builder 负责 UI 结构复用状态读写路径必须另外讲清楚。先判断这段 Builder 要不要参与刷新场景推荐方式原因纯展示标题、图标普通参数不需要写回读取父组件最新状态Binding 读回调状态变化后 Builder 内部能刷新在 Builder 内修改父状态MutableBinding 或事件必须有明确写回路径多个复杂对象一起传拆组件更稳Builder 参数规则会变难读不要为了少写一个组件把所有逻辑塞进 Builder。只要里面开始有状态、事件、异步结果就要重新评估是不是该拆成自定义组件。案例一卡片操作区只读父组件状态旧写法可能这样BuilderfunctionactionArea(count:number){Row(){Text(已选${count}项)Button(继续添加)}}如果count是普通值很多时候它更像一次快照。父组件后面改了状态Builder 里的显示不一定按你预期刷新。更清楚的写法是把读取路径作为回调传进去。import{Binding,UIUtils}fromkit.ArkUIBuilderfunctionactionArea(count:Bindingnumber){Row({space:8}){Text(已选${count.value}项)Button(继续添加)}}ComponentV2struct ShoppingCardHost{LocalcheckedCount:number0build(){Column(){actionArea(UIUtils.makeBindingnumber(()this.checkedCount))Button(勾选一个).onClick((){this.checkedCount1})}}}这个写法的好处是读路径很清楚Builder 内部读count.value父组件状态变化后它能拿到新值。案例二弹窗按钮组需要写回父状态如果 Builder 里要改父组件状态只给读回调就不够了。比如弹窗按钮组里有“全选/清空”它要回写checkedCount。import{MutableBinding,UIUtils}fromkit.ArkUIBuilderfunctiondialogActions(count:MutableBindingnumber,total:Bindingnumber){Row({space:8}){Button(全选).onClick((){count.valuetotal.value})Button(清空).onClick((){count.value0})}}父组件传参时要同时给读和写。ComponentV2struct ShoppingDialogHost{LocalcheckedCount:number0LocaltotalCount:number8build(){Column(){Text(当前已选${this.checkedCount})dialogActions(UIUtils.makeBindingnumber(()this.checkedCount,(value:number){this.checkedCountvalue}),UIUtils.makeBindingnumber(()this.totalCount))}}}这里最重要的是写回路径显式存在。不要在 Builder 里直接改普通对象参数也不要假装它一定会同步回父组件。和拆组件相比哪种更好方案适合不适合Builder 普通参数静态结构复用复杂状态交互Builder makeBinding少量读写状态多字段复杂业务自定义组件有生命周期、本地状态、复杂事件只是两行静态 UI我的选择很保守Builder 里只放轻量 UI一旦出现多个状态字段、异步结果、生命周期、错误态就拆组件。这样后面排查刷新问题会简单很多。本地验证方式Demo 做两件事。第一按钮点击后父组件checkedCount改变Builder 内文案同步变化第二Builder 内点击“清空”父组件状态也变成 0。classBuilderBindingProbe{checkedCount:number0totalCount:number8selectAll():void{this.checkedCountthis.totalCount}clear():void{this.checkedCount0}}如果只读能刷新、写回能改变父组件就说明读写路径是闭合的。否则就不要把问题归到 ArkUI 刷新慢要先回到参数传递方式重新拆。我给这个 Demo 留了三个检查点检查点怎么看通过标准初始渲染页面第一次打开Builder 里显示 0不显示脏数据父组件更新点一次“勾选一个”父组件和 Builder 内部都变成 1Builder 写回点“清空”或“全选”父组件状态被同步改掉下一次刷新仍一致这个验证看起来简单但能挡住很多误判。因为 Builder 出问题时开发者最容易只盯着 UI看到页面没有变化就猜是不是装饰器没生效看到局部变化了又猜是不是缓存。实际排查时应该先看读写链路是不是闭合再看 Builder 的刷新范围。第三个容易踩的坑把对象当成可随便改的状态上面两个案例只处理数字真实页面里还会传对象。对象更容易误导人因为你能写出item.checked true代码也像是在改状态但 UI 刷不刷新、父组件认不认这次变化要看这个对象本身是不是被状态系统追踪以及这次修改有没有触发到正确的刷新路径。classFoodRowState{id:stringname:stringchecked:booleanfalse}BuilderfunctionrowAction(item:FoodRowState){Row(){Text(item.name)Button(item.checked?取消:选中).onClick((){// 这个写法最危险看起来改了字段但外层不一定知道这次变化。item.checked!item.checked})}}这种写法我一般不会放进公共复用 Builder。原因不是它一定不能跑而是边界太隐蔽。今天列表短、组件层级浅看起来没问题后面加筛选、分页、缓存、局部刷新以后就可能出现“当前行变了底部统计没变”或者“统计变了列表行没变”。更稳的做法是把“改哪一条”的动作交回父组件让父组件统一更新状态。BuilderfunctionrowAction(item:FoodRowState,onToggle:(id:string)void){Row(){Text(item.name)Button(item.checked?取消:选中).onClick((){onToggle(item.id)})}}ComponentV2struct FoodListHost{Localfoods:FoodRowState[][]toggleFood(id:string):void{this.foodsthis.foods.map((item:FoodRowState){if(item.id!id){returnitem}constnextnewFoodRowState()next.iditem.id next.nameitem.name next.checked!item.checkedreturnnext})}build(){Column(){ForEach(this.foods,(item:FoodRowState){rowAction(item,(id:string)this.toggleFood(id))},(item:FoodRowState)item.id)}}}这个版本虽然多写了几行但好处很明显Builder 只负责展示和抛事件父组件负责状态更新。后面要接本地数据库、Preferences、筛选统计或者撤销操作都能从父组件这一层继续扩展不会把状态散落在多个 Builder 里。为什么不是所有地方都上 makeBindingUIUtils.makeBinding()很适合处理少量状态的读写但它不是把所有参数都变“高级”的工具。我的判断方式是判断问题答案是“是”时更建议Builder 里只是展示标题、图标、颜色吗是普通参数Builder 里需要读父组件最新值吗是BindingBuilder 里需要主动改父组件状态吗是MutableBinding 或事件Builder 里已经有加载、错误、空态、埋点吗是拆自定义组件这个状态要被多个页面共享吗是不放在 Builder回到页面状态或数据层我不建议为了追新 API把所有参数都包成 Binding。那样短期看起来统一长期会让阅读成本变高。一个 Builder 里同时出现五六个 Binding后面排查时反而不知道谁负责读、谁负责写、谁负责触发刷新。本地验证补一组边界案例除了按钮点击我还会补一组“筛选后再操作”的验证。因为很多列表问题不是第一屏暴露的而是在筛选、排序、分页以后才出现。classBuilderBindingListProbe{foods:FoodRowState[][]keyword:stringgetvisibleFoods():FoodRowState[]{returnthis.foods.filter((item:FoodRowState)item.name.includes(this.keyword))}toggleFood(id:string):void{this.foodsthis.foods.map((item:FoodRowState){if(item.id!id){returnitem}constnextnewFoodRowState()next.iditem.id next.nameitem.name next.checked!item.checkedreturnnext})}selectedCount():number{returnthis.foods.filter((item:FoodRowState)item.checked).length}}这组验证要看三件事操作期望结果如果失败通常说明搜索后勾选一条当前行和底部统计一起变行状态和统计来源不一致清空搜索词刚才勾选的行仍然保留状态只是改了临时列表没改源数据连续切换筛选勾选数量稳定key 或状态归属有问题这也是我更偏向“事件回父组件”的原因。列表一旦有筛选和排序状态必须落在源数据上不能只落在 Builder 或当前可见行里。版本和适配上要注意什么这篇文章用的是 HarmonyOS NEXT / ArkUI V2 的写法思路。官方资料里提到UIUtils.makeBinding()是 API version 20 相关能力所以项目里要先确认目标 SDK。如果项目还要兼容更低版本就不要直接把它写成唯一方案可以保留事件回调方案作为稳定兜底。我的落地顺序是先用普通事件回调把功能跑通只有少量读写状态时再考虑 Binding / MutableBinding版本不满足时继续用事件回调复杂状态超过两个以上就拆自定义组件写完后用“初始渲染、父组件更新、Builder 写回、筛选后操作”四组动作验证。这样写的好处是不会把文章写成 API 展示也不会让项目为了使用新能力反而变难维护。以后怎么避免以后写 Builder 前先问这段 UI 是静态复用还是要参与状态读写静态复用直接传普通参数读父状态用 Binding要写回就用 MutableBinding 或事件复杂了就拆自定义组件。我会把这个判断沉到代码评审里只要 Builder 里出现对象字段修改、异步结果处理、多个状态写回、跨页面共享状态就先暂停不直接继续堆 Builder。先把状态归属、写回路径和验证步骤列出来再决定用普通参数、Binding、事件回调还是拆组件。这样后面即使换页面、换数据源、换系统版本也不容易把刷新问题重新带回来。我会留下的排查清单这类问题以后不要只靠肉眼看页面是否正常。第一步先把状态来源写清楚它来自页面自己、父组件输入、跨层共享还是异步任务返回。第二步把触发动作写清楚用户点击、数据刷新、页面切换、组件重新激活分别会改哪些字段。第三步看刷新范围当前可见 UI 是否刷新不可见组件是否被带着刷新派生计算是否重复执行。第四步再看副作用请求、数据库写入、日志统计和缓存更新有没有被误放到 UI 派生逻辑里。我更建议把这些检查沉到项目代码评审里。以后遇到类似问题先按“复现动作、状态归属、解决方案、验证结果、如何避免”五项过一遍如果其中一项说不清楚就不要急着把新 API 写进正文或提交到项目里。这样文章能解释清楚代码也能经得起下一次改需求。还有一个实际取舍如果 Demo 写完以后发现解释全靠口头补充说明这个方案还没有封装好。能抽成一个小工具、一个组件、一个 controller 或一条项目规则才说明它不是临时补丁。文章里也应该把这个取舍讲出来让读者知道什么时候照着用什么时候应该换方案。最后再补一次边界验证改动前后都要保留最小复现步骤方便后面版本升级时重新跑一遍。
写这段代码前我主要对照了这几个官方章节https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-custom-components-freezehttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-v1-v2-migration-inner-componenthttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-provider-and-consumerhttps://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-user-defined-arktsnode-buildernodehttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-computed这一篇只围绕一个问题讲问题怎么发生、原因在哪里、解决时怎么取舍以及改完以后怎么验证。下面的代码和表格都服务于这个排查链路不做参数表搬运。很多 Builder 问题不是“不会抽组件”而是抽完以后参数不刷新。比如卡片右侧操作区复用了一个构建函数父组件的选中数量变了按钮文案没跟着变或者弹窗按钮组里想改父组件状态最后写成在 Builder 里直接改入参。代码能过一部分场景但边界一复杂就会乱。官方文档里对 Builder 参数传递规则讲得很细尤其是按值、按引用、按回调以及 API version 20 开始配合UIUtils.makeBinding()支持刷新和写回。我的理解很简单Builder 负责 UI 结构复用状态读写路径必须另外讲清楚。先判断这段 Builder 要不要参与刷新场景推荐方式原因纯展示标题、图标普通参数不需要写回读取父组件最新状态Binding 读回调状态变化后 Builder 内部能刷新在 Builder 内修改父状态MutableBinding 或事件必须有明确写回路径多个复杂对象一起传拆组件更稳Builder 参数规则会变难读不要为了少写一个组件把所有逻辑塞进 Builder。只要里面开始有状态、事件、异步结果就要重新评估是不是该拆成自定义组件。案例一卡片操作区只读父组件状态旧写法可能这样BuilderfunctionactionArea(count:number){Row(){Text(已选${count}项)Button(继续添加)}}如果count是普通值很多时候它更像一次快照。父组件后面改了状态Builder 里的显示不一定按你预期刷新。更清楚的写法是把读取路径作为回调传进去。import{Binding,UIUtils}fromkit.ArkUIBuilderfunctionactionArea(count:Bindingnumber){Row({space:8}){Text(已选${count.value}项)Button(继续添加)}}ComponentV2struct ShoppingCardHost{LocalcheckedCount:number0build(){Column(){actionArea(UIUtils.makeBindingnumber(()this.checkedCount))Button(勾选一个).onClick((){this.checkedCount1})}}}这个写法的好处是读路径很清楚Builder 内部读count.value父组件状态变化后它能拿到新值。案例二弹窗按钮组需要写回父状态如果 Builder 里要改父组件状态只给读回调就不够了。比如弹窗按钮组里有“全选/清空”它要回写checkedCount。import{MutableBinding,UIUtils}fromkit.ArkUIBuilderfunctiondialogActions(count:MutableBindingnumber,total:Bindingnumber){Row({space:8}){Button(全选).onClick((){count.valuetotal.value})Button(清空).onClick((){count.value0})}}父组件传参时要同时给读和写。ComponentV2struct ShoppingDialogHost{LocalcheckedCount:number0LocaltotalCount:number8build(){Column(){Text(当前已选${this.checkedCount})dialogActions(UIUtils.makeBindingnumber(()this.checkedCount,(value:number){this.checkedCountvalue}),UIUtils.makeBindingnumber(()this.totalCount))}}}这里最重要的是写回路径显式存在。不要在 Builder 里直接改普通对象参数也不要假装它一定会同步回父组件。和拆组件相比哪种更好方案适合不适合Builder 普通参数静态结构复用复杂状态交互Builder makeBinding少量读写状态多字段复杂业务自定义组件有生命周期、本地状态、复杂事件只是两行静态 UI我的选择很保守Builder 里只放轻量 UI一旦出现多个状态字段、异步结果、生命周期、错误态就拆组件。这样后面排查刷新问题会简单很多。本地验证方式Demo 做两件事。第一按钮点击后父组件checkedCount改变Builder 内文案同步变化第二Builder 内点击“清空”父组件状态也变成 0。classBuilderBindingProbe{checkedCount:number0totalCount:number8selectAll():void{this.checkedCountthis.totalCount}clear():void{this.checkedCount0}}如果只读能刷新、写回能改变父组件就说明读写路径是闭合的。否则就不要把问题归到 ArkUI 刷新慢要先回到参数传递方式重新拆。我给这个 Demo 留了三个检查点检查点怎么看通过标准初始渲染页面第一次打开Builder 里显示 0不显示脏数据父组件更新点一次“勾选一个”父组件和 Builder 内部都变成 1Builder 写回点“清空”或“全选”父组件状态被同步改掉下一次刷新仍一致这个验证看起来简单但能挡住很多误判。因为 Builder 出问题时开发者最容易只盯着 UI看到页面没有变化就猜是不是装饰器没生效看到局部变化了又猜是不是缓存。实际排查时应该先看读写链路是不是闭合再看 Builder 的刷新范围。第三个容易踩的坑把对象当成可随便改的状态上面两个案例只处理数字真实页面里还会传对象。对象更容易误导人因为你能写出item.checked true代码也像是在改状态但 UI 刷不刷新、父组件认不认这次变化要看这个对象本身是不是被状态系统追踪以及这次修改有没有触发到正确的刷新路径。classFoodRowState{id:stringname:stringchecked:booleanfalse}BuilderfunctionrowAction(item:FoodRowState){Row(){Text(item.name)Button(item.checked?取消:选中).onClick((){// 这个写法最危险看起来改了字段但外层不一定知道这次变化。item.checked!item.checked})}}这种写法我一般不会放进公共复用 Builder。原因不是它一定不能跑而是边界太隐蔽。今天列表短、组件层级浅看起来没问题后面加筛选、分页、缓存、局部刷新以后就可能出现“当前行变了底部统计没变”或者“统计变了列表行没变”。更稳的做法是把“改哪一条”的动作交回父组件让父组件统一更新状态。BuilderfunctionrowAction(item:FoodRowState,onToggle:(id:string)void){Row(){Text(item.name)Button(item.checked?取消:选中).onClick((){onToggle(item.id)})}}ComponentV2struct FoodListHost{Localfoods:FoodRowState[][]toggleFood(id:string):void{this.foodsthis.foods.map((item:FoodRowState){if(item.id!id){returnitem}constnextnewFoodRowState()next.iditem.id next.nameitem.name next.checked!item.checkedreturnnext})}build(){Column(){ForEach(this.foods,(item:FoodRowState){rowAction(item,(id:string)this.toggleFood(id))},(item:FoodRowState)item.id)}}}这个版本虽然多写了几行但好处很明显Builder 只负责展示和抛事件父组件负责状态更新。后面要接本地数据库、Preferences、筛选统计或者撤销操作都能从父组件这一层继续扩展不会把状态散落在多个 Builder 里。为什么不是所有地方都上 makeBindingUIUtils.makeBinding()很适合处理少量状态的读写但它不是把所有参数都变“高级”的工具。我的判断方式是判断问题答案是“是”时更建议Builder 里只是展示标题、图标、颜色吗是普通参数Builder 里需要读父组件最新值吗是BindingBuilder 里需要主动改父组件状态吗是MutableBinding 或事件Builder 里已经有加载、错误、空态、埋点吗是拆自定义组件这个状态要被多个页面共享吗是不放在 Builder回到页面状态或数据层我不建议为了追新 API把所有参数都包成 Binding。那样短期看起来统一长期会让阅读成本变高。一个 Builder 里同时出现五六个 Binding后面排查时反而不知道谁负责读、谁负责写、谁负责触发刷新。本地验证补一组边界案例除了按钮点击我还会补一组“筛选后再操作”的验证。因为很多列表问题不是第一屏暴露的而是在筛选、排序、分页以后才出现。classBuilderBindingListProbe{foods:FoodRowState[][]keyword:stringgetvisibleFoods():FoodRowState[]{returnthis.foods.filter((item:FoodRowState)item.name.includes(this.keyword))}toggleFood(id:string):void{this.foodsthis.foods.map((item:FoodRowState){if(item.id!id){returnitem}constnextnewFoodRowState()next.iditem.id next.nameitem.name next.checked!item.checkedreturnnext})}selectedCount():number{returnthis.foods.filter((item:FoodRowState)item.checked).length}}这组验证要看三件事操作期望结果如果失败通常说明搜索后勾选一条当前行和底部统计一起变行状态和统计来源不一致清空搜索词刚才勾选的行仍然保留状态只是改了临时列表没改源数据连续切换筛选勾选数量稳定key 或状态归属有问题这也是我更偏向“事件回父组件”的原因。列表一旦有筛选和排序状态必须落在源数据上不能只落在 Builder 或当前可见行里。版本和适配上要注意什么这篇文章用的是 HarmonyOS NEXT / ArkUI V2 的写法思路。官方资料里提到UIUtils.makeBinding()是 API version 20 相关能力所以项目里要先确认目标 SDK。如果项目还要兼容更低版本就不要直接把它写成唯一方案可以保留事件回调方案作为稳定兜底。我的落地顺序是先用普通事件回调把功能跑通只有少量读写状态时再考虑 Binding / MutableBinding版本不满足时继续用事件回调复杂状态超过两个以上就拆自定义组件写完后用“初始渲染、父组件更新、Builder 写回、筛选后操作”四组动作验证。这样写的好处是不会把文章写成 API 展示也不会让项目为了使用新能力反而变难维护。以后怎么避免以后写 Builder 前先问这段 UI 是静态复用还是要参与状态读写静态复用直接传普通参数读父状态用 Binding要写回就用 MutableBinding 或事件复杂了就拆自定义组件。我会把这个判断沉到代码评审里只要 Builder 里出现对象字段修改、异步结果处理、多个状态写回、跨页面共享状态就先暂停不直接继续堆 Builder。先把状态归属、写回路径和验证步骤列出来再决定用普通参数、Binding、事件回调还是拆组件。这样后面即使换页面、换数据源、换系统版本也不容易把刷新问题重新带回来。我会留下的排查清单这类问题以后不要只靠肉眼看页面是否正常。第一步先把状态来源写清楚它来自页面自己、父组件输入、跨层共享还是异步任务返回。第二步把触发动作写清楚用户点击、数据刷新、页面切换、组件重新激活分别会改哪些字段。第三步看刷新范围当前可见 UI 是否刷新不可见组件是否被带着刷新派生计算是否重复执行。第四步再看副作用请求、数据库写入、日志统计和缓存更新有没有被误放到 UI 派生逻辑里。我更建议把这些检查沉到项目代码评审里。以后遇到类似问题先按“复现动作、状态归属、解决方案、验证结果、如何避免”五项过一遍如果其中一项说不清楚就不要急着把新 API 写进正文或提交到项目里。这样文章能解释清楚代码也能经得起下一次改需求。还有一个实际取舍如果 Demo 写完以后发现解释全靠口头补充说明这个方案还没有封装好。能抽成一个小工具、一个组件、一个 controller 或一条项目规则才说明它不是临时补丁。文章里也应该把这个取舍讲出来让读者知道什么时候照着用什么时候应该换方案。最后再补一次边界验证改动前后都要保留最小复现步骤方便后面版本升级时重新跑一遍。
