企业官网建设流程全解析

这个月带项目，组里一个新来的同学在做消息流页面，写了几百行重复代码后跑来问我：能不能把卡片模板抽出去。我说可以，用@Builder。他改完后又问：那@LocalBuilder呢？这俩名字这么像，到底该用哪个。我当时第一反应是"都可以吧"，可一较真就发现：真要在复杂页面里做状态精准刷新，区别还是挺大的。这篇文章我就把自己研究、实测的结果完整摊开讲，包含完整示例代码和三次踩坑记录，希望能帮到正在学鸿蒙ArkUI、特别是搞不清@Builder和@LocalBuilder到底差在哪的开发者。

1. 为什么开发者会重复写几百行UI：轻量级UI元素要解决的核心矛盾

1.1 自定义组件不是万能的：每个@Component都有"重量"

很多刚上手ArkUI的朋友，遇到一段UI要复用，第一反应是抽自定义组件：加一个@Component，把@State、@Prop、@Link全配好，然后到处ChildComponent()。这个思路没错，但很多人忽略了——自定义组件是一个独立的struct实例，它有自己完整的生命周期，有自己的状态管理上下文，创建和销毁都要经过一套相对完整的流程。

这意味着什么？如果你只是想让两三个Row加Text的节点片段在不同位置重复出现，硬套自定义组件，等于为了搬一块小石头开了一辆卡车。页面上的组件实例数量一多，父子关系就变深，排查问题的时候一层一层往上点属性面板，非常痛苦。

我最早接触这套框架时也犯过这个毛病。一个设置页里每个设置项都是一个图标加一行文字加一个开关，我每写一个设置项就抽一个自定义组件，最后页面挂了十几个组件实例，滑动时明显感觉帧率不稳。后来才意识到：这类"片段级"的UI复用，真正合适的是@Builder这类轻量级UI元素机制。

1.2 最原始的"复用"是复制粘贴，它的代价你想象不到

在没有@Builder之前，最常见的复用手段就是复制粘贴。今天要加一个卡片，Column套Row再套两个Text，粘贴五次，每个地方微调一下字段。看起来没问题，可产品第二天说"卡片圆角改成8"，你就要去五处改样式；再隔两天说"卡片整体加一个左边距"，你又要五处都动。这种维护成本随着页面规模增长是爆炸式的。

复制粘贴还有一个隐蔽缺点：手滑漏改一处，视觉差异只出现在一个入口，线上反馈前你根本发现不了。我见过一次紧急事故，就是漏改了一处角落里的卡片颜色，深色模式下那个入口几乎不可见。所以"把UI片段提取成可复用函数"不是优化，而是刚需。

1.3@Builder的定位：比自定义组件轻，比普通函数强

@Builder装饰的函数，在外观上就像一个普通函数，但它返回的是UI结构。它和普通函数最大的区别在于：@Builder内部写的组件是可以被ArkUI状态管理机制识别的。也就是说，你在里面引用的this属性、传入的对象参数，在状态变化时能够触发对应节点的更新。

它和自定义组件也有明显区别：@Builder不会创建一个新的组件实例，不会引入额外的组件层级，系统只是把你声明的那棵节点树"内联"到调用位置。这也就是它被叫做"轻量级UI元素"的原因：保留了UI复用的便利，去掉了组件的重量级生命周期成本。

简单记忆：普通函数返回不了可被状态驱动刷新的组件树；自定义组件有点重；@Builder是两者之间的中间态。

那@LocalBuilder呢？它是后出现的、更强调"局部性"的变体。下一节我会先把@Builder的基础用法讲透，再对比它。

2.@Builder的基本形态：全局、局部、带参、不带参的完整写法

2.1 最朴素的形态：无参的@Builder

无参写法最好理解，在组件内部声明一个@Builder方法，在build()里直接调用，代码长这样：

@Entry @Component struct Index { @State title: string = 'Hello ArkUI'; @Builder CommonHeader() { Row() { Text(this.title) .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor('#182431') Blank() Text('详情') .fontSize(14) .fontColor('#007DFF') } .width('100%') .padding(12) .backgroundColor(Color.White) } build() { Column() { this.CommonHeader() // 这里可以再调用一次 this.CommonHeader() } } }

注意几个细节：

• 在自定义组件内部声明的@Builder方法，内部可以通过this直接访问当前组件实例的@State等属性。
• 调用时用的是this.CommonHeader()，不加this会直接报找不到函数。
• 无参@Builder虽然简单，但它和组件状态绑定得很紧：只要this.title变了，build重新执行时，两处插入点都会刷新。

无参写法的局限也很明显：如果同一段UI结构需要在五个地方出现，但每个地方文案不同、颜色不同，你就只能复制五个@Builder方法，或者用参数来解决。

2.2 带参的@Builder：值传递和引用传递是最大的坑

带参写法有两种让人容易懵的情况：参数是普通数据类型，还是对象字面量？这决定了它是"值传递"还是"引用传递"。

先看最直接的做法，给@Builder方法声明参数：

@Entry @Component struct Index { @Builder ItemCard(title: string, desc: string) { Column() { Text(title).fontSize(16).fontWeight(FontWeight.Medium) Text(desc).fontSize(13).fontColor('#858D99') } .padding(16) .backgroundColor('#FFFFFF') .borderRadius(12) .width('100%') } build() { Column({ space: 12 }) { this.ItemCard('项目A', '这是一个示例描述') this.ItemCard('项目B', '这是另一个示例描述') } .padding(16) } }

这种写法对纯展示场景是够用的。但要小心：如果你把一个@State值单独传给@Builder方法，它走的是值传递。什么意思？@Builder内部拿到的只是传入那一刻的值的快照，你在@Builder方法的参数上做任何修改，都不会反向同步回外面的状态。

如果你希望@Builder方法内的修改能"碰到"外面的数据，就需要以对象字面量的方式传参。比如：

@Builder ItemCard(config: { title: string, desc: string }) { Column() { Text(config.title) Text(config.desc) } } // 调用时 this.ItemCard({ title: this.item.title, desc: this.item.desc })

以对象字面量传入时，框架会把它识别成引用传递，@Builder内部对config.title的修改，可以影响到原对象（前提是原对象的属性具备被观察的能力，比如它是@State修饰对象的属性）。

这里我建议：只要你的@Builder方法内部有输入框、开关这类交互组件，需要回写数据的，一律用对象字面量方式传参。只传单个字符串、数字，回写时会发现数据"怎么改都改不出去"，排查半天才发现是传参方式的问题。

2.3 全局@Builder和局部@Builder：作用域决定了风格

全局@Builder很好识别：把修饰的函数放在组件外部，甚至可以单独放到一个.ts/.ets文件里导出。写法如下：

@Builder export function GlobalCard(title: string) { Text(title) .fontSize(16) .padding(12) } @Entry @Component struct Index { build() { Column() { GlobalCard('从全局定义的') } } }

全局@Builder的好处是跨页面、跨组件复用，跟组件实例完全解耦。坏处也很明显：它无法直接访问某个组件的this，所有数据都得靠参数传。一旦遇到复杂对象，传参方式又回到上面说的引用、值传递那一堆规则，维护上稍不留神就会出问题。

而局部@Builder（定义在组件struct内部的@Builder方法）可以直接用this拿状态，不需要层层传参。它对"组件内部的小片段复用"更友好，但因为依赖this，你不能把它导出或者放到组件外部去。

我在实际项目里的分法是：

3.@LocalBuilder的诞生逻辑：什么是"局部"UI构建，它为什么更精准

3.1 官方为什么要多做这样一个装饰器

我第一次看到@LocalBuilder时第一反应是：这不就是局部@Builder吗？后来仔细对比才知道，它们名字相似，定位并不完全相同。

@LocalBuilder更强调"这个UI片段只服务于所在的组件"，它必须定义在组件struct内部，也不能像局部@Builder方法那样在组件内部声明后还能被外部某些机制间接引用。它从设计上就锁死了作用域，逼迫你把"局部复用"这件事做得更纯粹。

为什么需要这样做？核心原因是状态刷新粒度的控制。@Builder方法毕竟还是一个"Themed by component build"的普通方法，在某些场景下，组件内部任意@State变化，都会导致整个build方法重新执行，你精心抽出来的那一小块UI片段即使没用到这个状态，也可能跟着重新渲染。而@LocalBuilder在实现层做了更细粒度的依赖追踪：它内部到底用了哪些状态，只有这些状态变化时它才会重新执行。

说人话就是：@Builder像是一整套户型图里的一个房间，客厅一改，这个房间可能也得跟着重画一遍；@LocalBuilder则给这个房间装了独立的感应器，只有房间里东西变了它才重画。

3.2 与组件生命周期的绑定：@LocalBuilder的this指向更"纯粹"

@LocalBuilder定义在自定义组件内部，它访问的this就是当前组件实例，这一点和局部@Builder没有区别。但有一个细微差别值得注意：局部@Builder方法如果你在某些回调场景下把它作为参数传出去，this可能会受到调用方上下文的影响，导致状态读取不对；@LocalBuilder则因为它只属于当前struct，语法上就不允许把它抽出去单独用，从根上杜绝了"传出去之后this丢没丢"这类问题。

所以在写复杂组件时，我倾向于把"和当前组件强相关的UI片段"都用@LocalBuilder声明。这样别人看代码时也能一眼判断：凡是@LocalBuilder，它一定只跟这个组件内部状态绑定，别想着跨组件复用。

3.3 一个示例：最简单的@LocalBuilder长什么样

@Entry @Component struct Index { @State title: string = '初始标题'; @LocalBuilder HeaderView() { Row() { Text(this.title) .fontSize(20) .fontWeight(FontWeight.Bold) Blank() Text('编辑') .fontColor('#007DFF') } .width('100%') .padding(16) } build() { Column() { this.HeaderView() Button('修改标题') .onClick(() => { this.title = '新标题' }) } } }

这段代码乍一看和局部@Builder写法非常像，所以很多教程会直接说"用@LocalBuilder代替局部@Builder就行"。但从实际表现看，在频繁更新@State的页面里，@LocalBuilder会比普通局部@Builder更不容易触发整棵树的多余刷新。这个差异在小页面里几乎感知不到，一旦列表里用，体感差异会非常明显。

4. 实例演示：同一个消息列表，分别用@Builder和@LocalBuilder实现

4.1 场景设计

为了让差异看得见，我设计了一个消息列表页：每条消息是同一个卡片模板，包含昵称、预览文字、时间、一个"点赞"按钮。需求是：点赞后按钮颜色和数字要变，同时其他消息卡片不能重新渲染。这个场景最能暴露两种写法的差异。

先给基础数据模型：

class MessageModel { id: number = 0 name: string = '' content: string = '' time: string = '' liked: boolean = false likeCount: number = 0 }

4.2 用@Builder实现：代码能跑，但刷新范围偏大

@Entry @Component struct BuilderDemo { @State messages: MessageModel[] = []; aboutToAppear(): void { // 模拟加载数据 for (let i = 0; i < 20; i++) { let item = new MessageModel() item.id = i item.name = `用户${i}` item.content = `第${i}条消息的预览内容` item.time = '10:0' + (i % 10) item.liked = i % 3 === 0 item.likeCount = i * 2 this.messages.push(item) } } @Builder MessageCard(msg: { item: MessageModel }) { Row() { Column() .width(40) .height(40) .borderRadius(20) .backgroundColor('#3D5AFE') Column({ space: 4 }) { Text(msg.item.name) .fontSize(15) .fontWeight(FontWeight.Medium) Text(msg.item.content) .fontSize(13) .fontColor('#858D99') .maxLines(1) .textOverflow({ overflow: TextOverflow.Ellipsis }) } .alignItems(HorizontalAlign.Start) .layoutWeight(1) .padding({ left: 8 }) Column({ space: 2 }) { Text(msg.item.liked ? '已赞' : '点赞') .fontSize(12) .fontColor(msg.item.liked ? '#FF6D00' : '#007DFF') Text(`${msg.item.likeCount}`) .fontSize(12) .fontColor('#182431') } .onClick(() => { msg.item.liked = !msg.item.liked msg.item.likeCount += msg.item.liked ? 1 : -1 }) } .width('100%') .padding(12) .backgroundColor(Color.White) .borderRadius(12) .margin({ bottom: 8 }) } build() { Column() { List({ space: 8 }) { ForEach(this.messages, (item: MessageModel) => { ListItem() { this.MessageCard({ item: item }) } }, (item: MessageModel) => `${item.id}`) } .width('100%') .layoutWeight(1) } .padding(16) .backgroundColor('#F1F3F5') } }

4.3 用@LocalBuilder实现：代码结构几乎一样，刷新行为不同

把上面的@Builder方法改成@LocalBuilder，其他代码不用动：

@LocalBuilder MessageCard(msg: { item: MessageModel }) { // 内部结构和上一版完全一致 Row() { // ... } }

区别在于：@Builder版本的卡片内部使用了msg.item.liked和msg.item.likeCount，理论上它也做了依赖收集，但整棵build()里如果有其他@State变化，还是会连带触发更多节点重新求值。@LocalBuilder版本在数据模型上，对这些@State数组项的属性变化的追踪粒度更细，页面里其他未涉及点赞的状态变化，不会让已经渲染好的20张卡片重新build。

4.4 实测观察到的三个现象

我分别跑了一下两个版本，记录到这些差异：

需要说明：上面表格里"全局状态"是我额外加的一个@State timer: number，用setInterval每秒更新一次，模拟"列表页上方某个实时数据区域"对列表的干扰。在这种干扰下，两个版本的差距就显现出来了。

提示：如果你只做简单的设置页、静态展示页，直接用@Builder完全没问题，没必要为了"局部"两个字强行切换。差异主要体现在高频状态更新场景。

5. 三次踩坑记录：传参失效、状态不同步、生命周期错乱的完整排查链路

5.1 踩坑一：@Builder里改了入参对象，页面却不刷新

现象：我抽了一个卡片模板，点击卡片上的"关注"按钮，@Builder方法内部修改了传入对象里的isFollowed字段，控制台打印数据显示字段确实改了，但UI上的按钮文字始终不变化。

排查过程：一开始我怀疑是@State没设对，检查了对象属性确实用@State修饰；接着怀疑是对象不是@Observed，看了一眼，也不是。最后对照文档才发现问题在传参方式：我在调用时写的是this.FollowCard(item.isFollowed)——传了一个布尔值！@Builder按值传递，函数内部拿到的isFollowed只是一个副本，改的是副本，原状态对象的属性压根没动。

修复方案是把调用改成传整个对象：

this.FollowCard({ isFollowed: item.isFollowed })

如果再配合@Observed和@ObjectLink，交互后的UI联动才完整。这个坑我印象极深，后来凡是看到@Builder里"改了没反应"，第一反应先看传参形态，百分之八十是这里出问题。

5.2 踩坑二：@Builder方法内访问this，在某些回调场景下取不到值

现象：一个普通局部@Builder方法，里面有一个TextInput的onChange回调，我在回调里打印this.currentInput，第一次触发正常，第二次触发就变成undefined。

排查过程：我以为是状态被重置了，反复检查@State声明没问题。后来在onChange回调里把this对象整体打印出来，发现它在一个回调绑定过程中指向了错误上下文，访问不到组件实例的属性。

为什么会出现这个情况？局部@Builder方法虽然定义在组件内部，但当你把它作为一个方法引用交给某个事件回调去间接调用时，this的绑定关系可能因调用链路由问题而丢失。这不是每次必现，但只要出现一次，问题的隐蔽性极高。

修复方案：在@Builder内部需要访问组件状态时，不要依赖隐式的this，先把要用的状态在方法开头提取成局部变量（比如const current = this.currentInput），或者直接用箭头函数包裹确保this捕获正确。如果是@LocalBuilder，这个坑会少很多，因为它的使用范围被限定在当前组件里，编译器提示也更严格。

5.3 踩坑三：全局@Builder和局部刷新混用时的"明暗交替"问题

现象：列表页的卡片用了全局@Builder，卡片内部按钮点击后状态更新，偶发出现"一帧亮一帧暗"的闪烁。字面描述可能夸张，但视觉上确实能看到按钮文字颜色先变、过一帧又变回来。

排查过程：闪烁的本质是某个状态在两个不同的构建源之间产生了重复渲染，先被@Builder引用的旧值覆盖，又被新值纠正。我把全局@Builder改成局部@Builder后，闪烁消失；之后又把卡片改成@LocalBuilder，刷新表现更稳定。

我推测的原因是：全局@Builder在设计上更偏向"静态的、由调用方传入数据的展示片段"，它对于需要频繁响应组件内部交互、回写状态的场景，响应链路比局部构建更绕。所以我的经验是：交互密集、状态回写频繁的UI片段，优先用@LocalBuilder；纯静态、低频率更新的公共样式片段，用全局@Builder没问题。

6. 日常开发选型建议：到底什么时候用哪个

6.1 一条简单的决策规则

我给自己定的规则是这样的：

• 这个UI片段是否只在这个组件里出现？是 → 用@LocalBuilder。
• 是否需要在片段里频繁读写组件状态？是 → 用@LocalBuilder。
• 是否需要跨多个页面复用？是 → 全局@Builder，且尽量只做纯展示。
• 片段内部是否有独立的交互生命周期（比如自己管理定时器、请求数据）？是 → 别用@Builder，直接用@Component自定义组件。

这套规则执行一段时间后，我页面里因为UI复用引发的刷新问题明显变少。

6.2 混用时的三条规范性建议

先看这条建议：一个组件内部，尽量统一风格，不要一个页面里一半用@Builder一半用@LocalBuilder。混用不是不行，但别人接手你的代码时，会搞不清"这个片段为什么用这个不用那个"，维护成本会增加不少。我现在看到代码里两种都有的情况，会优先花一点时间统一掉。

再看第二条：@LocalBuilder不要试图突破它的局部性去搞全局复用。如果你发现一段@LocalBuilder代码被复制到三个组件里，说明它其实应该上移为全局@Builder或自定义组件，别因为懒而复制三份。

第三条：无论是@Builder还是@LocalBuilder，命名都要像普通方法一样清晰。我见过有人把所有@Builder方法统一叫contentView，调试时一锅粥。合理的写法是GreetingCard、FooterBar这种能直接看出UI形态的名字，最好会议讨论中提到的UI模块名保持一致。

6.3 几个已经验证过的性能优化习惯

我实测下来，对列表性能最友好的是"@LocalBuilder+ForEach+ 数据模型对象传参"组合。再配合@Observed装饰数据模型类，点击后只有对应的那个列表项里的节点会刷新，这种精准度已经接近自定义组件，但代码量又比自定义组件少很多。

另外一个习惯是：不要在@Builder方法里做复杂计算或调用同步耗时函数。它本质是UI构建过程的一部分，每次刷新都会重新执行，如果里面有耗时逻辑，列表滚动时会直接卡顿。计算逻辑放到@State的getter里，或用@Computed一类的缓存能力，效果会明显更好。

最后，如果要写单元测试或者被同事提问"这两个装饰器的区别"，我一般会用一句话总结：@Builder提供了轻量级的UI复用，@LocalBuilder在轻量级复用的基础上，把作用域和状态刷新粒度都收得更紧。前者是你想复用一段UI时的默认选择，后者是你在高频动态页面里还想保持性能时的进阶选择。

最后再分享一个小技巧：如果你在@LocalBuilder里发现某个局部状态变化后，UI没有按预期刷新，先检查这个状态是不是被声明成了局部普通变量，而不是@State。我踩过好多次，原因都是图省事把@State写成了普通属性，局部构建函数是不会追踪普通变量的。先把状态修饰符改对，大部分刷新问题立刻消失。