企业官网建设流程全解析

问题是怎么露出来的

中式美食首页有一组菜谱卡片，卡片里有封面、菜名、评分、收藏按钮和跳转详情。最早我把卡片拆成@Builder，是为了让列表页看起来干净一点：列表只负责循环，卡片负责展示。

这个方向没问题，问题出在参数边界没有拆清楚。页面刷新、筛选、排序以后，卡片显示的是新数据，但是点击事件里拿到的还是旧对象。表现出来就是几种很烦人的问题：

这种问题不一定每次复现，所以更容易被忽略。它不是 ArkUI 不能用，也不是@Builder有问题，而是我把“展示数据”和“业务身份”混在一起传了。

当时的写法哪里不稳

先看一段容易出问题的写法。为了省事，卡片拿到的是整个recipe对象，事件里也直接用这个对象。

为什么这个写法在中式美食里容易出问题，原因很简单：菜谱列表不是一组固定不动的静态数据。搜索会换结果，分类会换结果，收藏会局部改状态，推荐排序还会把同一批菜重新排一遍。这个时候如果事件回调依赖旧对象或者旧下标，坏处就是排查时看不到明显报错，但业务身份已经悄悄错了。用户看到的是当前卡片，代码处理的却可能是刷新前那一道菜。

@BuilderfunctionRecipeCard(recipe:RecipeItem){Column(){Image(recipe.cover).width('100%').height(128)Text(recipe.name).fontSize(16).fontWeight(FontWeight.Medium)Row(){Text(recipe.score.toFixed(1))Button(recipe.favorite?'已收藏':'收藏').onClick(()=>{this.toggleFavorite(recipe)})}}.onClick(()=>{this.openRecipeDetail(recipe)})}

这段代码在静态列表里看不出问题。真正麻烦的是列表会变：搜索会过滤，分类会切换，排序会重排，收藏后还会局部刷新。recipe是一个对象，闭包里抓到的对象不一定还能代表当前这张卡片。

再加上如果列表里用了不稳定的 key，比如直接用 index：

LazyForEach(this.recipeDataSource,(item:RecipeItem,index:number)=>{RecipeCard(item)},(item:RecipeItem,index:number)=>`${index}`)

列表一重排，index 还是 0、1、2，但是 0 位置上的菜已经不是刚才那道菜了。UI 复用了，事件闭包也容易跟着混乱。最后看到的现象就是“点 A，处理到 B”。

我先把卡片参数分成两类

后面我没有继续在卡片里补判断，而是先把参数重新分了一下。卡片真正需要的东西，其实分成两类：

这样拆完以后，@Builder就不再拿整个对象去做业务判断。它只负责把当前数据显示出来，然后把稳定的recipeId往外传。

改完后的 Builder 写法

我现在会给卡片定义一个更窄的参数结构。它可以包含展示字段，但事件里只使用recipeId。

typeRecipeCardView={recipeId:stringname:stringcover:stringscore:numberfavorite:booleancookingMinutes:number}typeRecipeCardAction={onOpen:(recipeId:string)=>voidonFavorite:(recipeId:string)=>voidonAddToShoppingList:(recipeId:string)=>void}

卡片本身只做展示和事件转发：

@BuilderfunctionRecipeCardViewBuilder(item:RecipeCardView,action:RecipeCardAction){Column(){Image(item.cover).width('100%').height(128).objectFit(ImageFit.Cover)Text(item.name).fontSize(16).fontWeight(FontWeight.Medium).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})Row(){Text(`${item.score.toFixed(1)}分`).fontSize(12)Blank()Button(item.favorite?'已收藏':'收藏').onClick((event:ClickEvent)=>{event.stopPropagation()action.onFavorite(item.recipeId)})}Button('加入购物清单').onClick((event:ClickEvent)=>{event.stopPropagation()action.onAddToShoppingList(item.recipeId)})}.onClick(()=>{action.onOpen(item.recipeId)})}

这里有两个点很关键。

第一，卡片不直接调用仓库，也不直接改recipe.favorite。它只说“哪个 recipeId 被点了”。真正要不要收藏、怎么写 Preferences、要不要同步 RDB，都在父组件或 repository 里处理。

第二，按钮内部用了event.stopPropagation()。不然点收藏时外层卡片的onClick也会触发，用户本来只是收藏，结果页面还跳到详情。这个问题在移动端很常见，尤其卡片里按钮很多的时候。

LazyForEach 的 key 必须跟业务身份一致

卡片参数改了以后，列表 key 也要一起改。如果这里还用 index，前面的改动只能解决一半。

LazyForEach(this.recipeDataSource,(item:RecipeCardView)=>{RecipeCardViewBuilder(item,{onOpen:(recipeId:string)=>this.openRecipeDetail(recipeId),onFavorite:(recipeId:string)=>this.toggleFavorite(recipeId),onAddToShoppingList:(recipeId:string)=>this.addToShoppingList(recipeId)})},(item:RecipeCardView)=>item.recipeId)

recipeId是菜谱身份，搜索、筛选、排序以后也不会变。这样 ArkUI 复用列表项时，能知道哪一项才是同一项，不会只按位置去理解。

中式美食这里尤其要注意，因为首页推荐、分类页、搜索结果页都可能复用同一张菜谱卡片。如果每个页面都自己随手写一个 key，后面排查会很痛苦。

父组件统一处理业务动作

父组件拿到recipeId后，再去仓库里取最新数据。这样即使列表刚刷新过，事件处理也不会依赖闭包里的旧对象。

privateopenRecipeDetail(recipeId:string):void{constrecipe=this.recipeRepository.findById(recipeId)if(!recipe){promptAction.showToast({message:'这道菜刚刚更新了，请重新打开'})return}this.navPathStack.pushPath({name:'RecipeDetailPage',param:{recipeId}})}

收藏也是同样的思路：

privateasynctoggleFavorite(recipeId:string):Promise<void>{constcurrent=this.recipeRepository.findById(recipeId)if(!current){return}constnextFavorite=!current.favoriteawaitthis.favoriteRepository.setFavorite(recipeId,nextFavorite)this.recipeDataSource.updateOne(recipeId,{favorite:nextFavorite})}

这里我不让卡片自己决定收藏状态怎么落库。卡片只负责触发动作，父组件负责拿最新数据，repository 负责写入。这样问题发生时也好查：是事件传错了，还是仓库写错了，还是 dataSource 没刷新。

DataSource 也不要按下标更新

如果toggleFavorite最后还是按 index 更新，问题还会回来。所以数据源也要按recipeId找项。

classRecipeCardDataSourceimplementsIDataSource{privateitems:RecipeCardView[]=[]privatelisteners:DataChangeListener[]=[]updateOne(recipeId:string,patch:Partial<RecipeCardView>):void{constindex=this.items.findIndex(item=>item.recipeId===recipeId)if(index<0){return}this.items[index]={...this.items[index],...patch}this.listeners.forEach(listener=>{listener.onDataChange(index)})}totalCount():number{returnthis.items.length}getData(index:number):RecipeCardView{returnthis.items[index]}registerDataChangeListener(listener:DataChangeListener):void{this.listeners.push(listener)}unregisterDataChangeListener(listener:DataChangeListener):void{this.listeners=this.listeners.filter(item=>item!==listener)}}

这段代码解决的是“知道哪一项变了”的问题。只要业务身份稳定，局部刷新就有依据。否则列表一重排，按下标更新很容易把状态贴到另一张卡片上。

我怎么验证这次没有串线

这类问题不能只点一次卡片就算通过。我会按中式美食的真实使用链路测：

我还会临时加一段日志，只在调试阶段用，确认事件传出来的recipeId和当前卡片展示的是同一个。

privatedebugCardAction(action:string,recipeId:string):void{constitem=this.recipeRepository.findById(recipeId)console.info(`[RecipeCard]${action}`,{recipeId,name:item?.name??'missing'})}

如果日志里出现missing，说明事件传出来的身份已经不可靠；如果 name 和页面看到的菜名对不上，基本就是 key、闭包或者 dataSource 更新顺序出了问题。

后面我会怎么避免

现在我写中式美食这种卡片组件，会先定三条规则。

第一，@Builder里不要直接藏业务逻辑。它可以显示 UI，可以把点击事件抛出去，但不要自己决定数据怎么写。

第二，事件参数优先传稳定 ID，不传整对象。对象适合展示，ID 适合做业务动作。搜索、排序、分页以后，旧对象最容易误导人。

第三，列表 key、事件参数、仓库查询都使用同一个业务身份。中式美食这里就是recipeId。只要这条线统一，卡片复用、局部刷新、收藏状态同步都会稳很多。

这次问题给我的提醒是：ArkUI @Builder 拆组件时，不要只看代码有没有变短。真正要盯的是边界有没有变清楚。卡片负责展示，父组件负责动作，repository 负责数据，这三层分清以后，页面才不容易出现“看着是这道菜，点出去是另一道菜”的问题。