针对ComponentV2 ,Builder , wrapperBuilder,命名式Node 区分
1.针对ComponentV2 ,Builder , wrapperBuilder区别:
| ComponentV2 | Builder | wrapBuilder | |
|---|---|---|---|
| 本质 | 自定义组件(声明式) | 轻量 UI 构建函数 | Builder 的包装器( |
| 类比 | 一个完整的"页面零件" | 一个"UI 模板片段" | 把模板片段装进"盒子"里传递 |
| 有无自己的状态 | 有(@Local、@Param等) | 无(依赖外部传入) | 无 |
| 有无生命周期 | 有(aboutToAppear等) | 无 | 无 |
@ComponentV2 — 独立的渲染单元;
拥有独立的渲染作用域 框架追踪其 build() 中用到的所有 @Trace/@Local 属性 状态变化 → 精准触发该组件的 build() 重执行 在组件树中是一个独立节点
@ComponentV2
struct MyComponent {
@Local count: number = 0 // 自己管理状态
build() {
Text(`${this.count}`)
.onClick(() => { this.count++ }) // 状态变化 → 自动触发 build() 重执行
}
}
@Builder — 内联渲染片段
不是独立组件,是一段可复用的 UI 描述 分为全局 Builder(函数)和组件内 Builder(方法) 渲染时"嵌入"到调用方的组件树中 没有自己的依赖追踪能力,依赖调用方的渲染上下文
@Builder
function myBuilder($$: ParamsModel) {
Text($$.params) // 直接渲染,没有自己的状态管理
}
wrapBuilder-- 需要结合Builder 使用;主要应用是针对动态配置的场景下使用;
针对状态变化触发;如果不是添加到 BuilderNode 中,同时使用指针的方式传递引用对象;非int,float 这些常量;可以实现状态改变;
针对使用选择情况:ai 查找
需要 UI 复用? ├── 需要独立状态/生命周期? │ └── ✅ @ComponentV2 ├── 不需要独立状态,代码在当前组件内? │ └── ✅ @Builder(组件内方法) ├── 不需要独立状态,需要跨文件/跨组件复用? │ └── ✅ @Builder(全局函数) └── 需要把 Builder 存起来/传递/动态渲染? └── ✅ wrapBuilder
2.针对Builder , wrapperBuilder 在状态交互逻辑下;
//model
@ObservedV2
export class ParamsModel {
@Trace
params?: string;
}
//添加组件实现;
@Local model: ParamsModel = new ParamsModel()
aboutToAppear(): void {
this.model.params = '10'
}
Column() {
//结论 通过 wrapBuilder+builder 传递数据是可以实现 状态改变的;
new WrapBuilder().getWrapBuilder().builder(this.model)
}
//模拟的获取 wrapBuilder,一般情况下是封装一个 map 集合,实现动态的控制;
class WrapBuilder {
getWrapBuilder() {
return wrapBuilder(wrapperBuilder)
}
}
//builder 封装
@Builder
function wrapBuilder($$: ParamsModel) {
Text($$.params)
.fontSize(25)
.fontColor('#333')
.onClick(() => {
$$.params = '22' + Math.random()
})
}
常见的使用 wrapBuilder 的方式如下:
Let factoryMap: Map<string, WrappedBuilder<[]>> = new Map) :|
factoryMap.set( 'Radio', wrapBuilder (radioItem));
factoryMap. set('Checkbox', wrapBuilder (checkboxItem));
export i factoryMap 3;
通过后台数据动态的控制展示的布局情况;来实现动态控制;
//错误方式:
@Builder
verifyValueChange(params: ParamsModel) {
Text(" 针对 对象更新 " + params.params)
.fontSize(25)
.fontColor(Color.Orange)
.onClick(() => {
params.params = '66' + Math.random()
})
}
原因:@Builder 在 @ComponentV2 中的参数是"按值传递"语义: params 虽然指向同一个对象引用,但 Builder** 不具备独立的依赖追踪能力** 在 Builder 内部通过参数访问 params.params,框架不会将其收集为父组件的渲染依赖 onClick 修改 params.params 后,框架不知道该重新渲染哪里;
对比为什么 wrapBuilder().builder() 能生效?
原因:wrapBuilder + .builder() 的调用方式会在当前组件的渲染上下文中直接展开,等同于在 build() 中内联渲染,框架能正确追踪到 this.model.params 的依赖。 而 this.verifyValueChange(this.model) 虽然也在 build() 中调用,但 @Builder 方法的参数变量 params 是一个局部变量,框架的依赖收集器可能无法将其与 this.model 的 Proxy 追踪关联起来。
简单来说:直接@Builder传递对象属于值传递; wrapBuilder().builder()属于对象传递;
同理针对在自定义组件的时候使用@BuilderParams 时;想要实现状态控制也要使用$$作为参数传递;
3.为啥使用命名式 Node 无法实现状态交互;
代码如下:
class MyNodeController extends NodeController {
private builderNode: BuilderNode<[ParamsModel]> | null = null
private wrapBuilder: WrappedBuilder<[ParamsModel]> = wrapBuilder(nodeBuilder)
private params: ParamsModel = new ParamsModel()
makeNode(uiContext: UIContext): FrameNode | null {
this.builderNode = new BuilderNode<[ParamsModel]>(uiContext)
this.builderNode.build(this.wrapBuilder, this.params)
return this.builderNode.getFrameNode()
}
updateData($$: ParamsModel) {
this.params = $$
this.builderNode?.update($$)
}
}
//node
@Builder
function nodeBuilder($$: ParamsModel) {
Text($$.params)
.fontSize(25)
.fontColor(Color.Red)
.onClick(() => {
$$.params = '44' + Math.random()
})
}
**原因:**BuilderNode 是"命令式 API",完全脱离了框架的"声明式渲染管线"。其实就是为了在多Node 的情况下;为了提升性能;避免全部节点刷新的情况下才使用BuilderNode,主要就是为了脱离渲染管控;
┌─────────── 声明式体系(自动响应) ───────────┐ │ │ │ @ComponentV2 → build() → 组件树 │ │ ↑ │ │ @Trace 变化 → 框架自动触发 build() 重执行 │ │ │ │ 包括:@Local、@Param、@BuilderParam │ │ wrapBuilder().builder() │ └──────────────────────────────────────────────┘
┌─────────── 命令式体系(手动控制) ───────────┐ │ │ │ BuilderNode → .build() → FrameNode │ │ ↑ │ │ 没有自动触发机制,必须手动 .update() │ │ │ │ 包括:NodeController、BuilderNode │ └──────────────────────────────────────────────┘
- BuilderNode 不在组件树中
// 声明式组件 — 在组件树中,有"身份" @ComponentV2 struct Child { @Param model: ParamsModel // 框架知道:Child 依赖 model build() { ... } // 框架知道:变化时重执行这个 }
// BuilderNode — 不在组件树中,没有"身份" let node = new BuilderNode(uiContext) node.build(wrapBuilder(fn), params)
// 框架视角:这是一次性命令,执行完就结束了 // 没有人"订阅"params 的变化
状态改变三要素
| 要素 | 声明式组件 | BuilderNode |
|---|---|---|
| ① 谁订阅了数据 | 组件(通过 @Param/@Local | 无人订阅 ❌ |
| ② 谁通知变化 | 框架(@Trace setter) | 框架发出了通知,但没人听 |
| ③ 谁执行刷新? | 组件的 build() | 无人执行 ❌ |
BuilderNode 的 .build() 只执行一次,之后: 没有组件声明"我依赖这个数据" 没有 build() 等着被重新调用 框架发了通知,但没有收件人
为什么设计成这样? BuilderNode 的定位就是命令式、精确控制的场景:
| 场景 | 为什么用 BuilderNod |
|---|---|
| 动态挂载/卸载节点 | 需要手动控制生命周期 |
| 跨组件树传递节点 | 节点不属于任何组件的 build() |
| 性能优化(懒创建) | 不想自动重渲染,手动控制时 |
| 离屏渲染 | 在组件树外创建内容 |
4.如何实现@Builder跟谁状态值的改变进行改变;
方式一:
使用内部的@Builder,不通过传参的方式传递值,而是直接绑定;如下:
//错误方式
@Builder
BuilderText($$: ParamsModel) {
Text($$.params)
.fontSize(25)
.fontColor(Color.Blue)
.onClick(() => {
$$.params = '33' + Math.random()
})
}
//正确方式:
@Builder
BuilderText() {
Text(this.model.params)
.fontSize(25)
.fontColor(Color.Blue)
.onClick(() => {
this.model.params = '33' + Math.random()
})
}
通过直接和状态值进行绑定关联;在状态更改的时候实现刷新;
方式二:
使用 wrapBuilder+Builder 的方式;如下:
wrapBuilder(wrapBuilder).builder(this.model)
@Builder
function wrapBuilder($$: ParamsModel) {
Text($$.params)
.fontSize(25)
.fontColor('#333')
.onClick(() => {
$$.params = '22' + Math.random()
})
}
这样也能实现在状态值改变时;实现内容的刷新效果;
方式三:
使用子组件+BuilderParam+Builder 的方式:代码如下:
@ComponentV2
export struct BuilderParamsTest {
@Param model: ParamsModel = new ParamsModel()
@BuilderParam params: ($$: ParamsModel) => void = this.defaultText
build() {
Column() {
this.params(this.model)
}
}
@Builder
defaultText($$: ParamsModel) {
Text($$.params)
.fontSize(25)
.fontColor('#333')
.onClick(() => {
})
}
}
//使用方式
BuilderParamsTest({
model: this.model, params: ($$: ParamsModel) => {
this.BuilderText($$)
}
})
//builder
@Builder
BuilderText($$: ParamsModel) {
Text($$.params)
.fontSize(25)
.fontColor(Color.Blue)
.onClick(() => {
$$.params = '33' + Math.random()
})
}
为啥直接使用@Builder不能实现刷新;使用子组件+@BuilderParams+@Builder 可以实现刷新:
**原因:**子组件能刷新,不是因为 @BuilderParam 有监听能力,而是因为 @Param 向框架"正式注册"了对这个对象的依赖。框架知道:"@Trace 变了 → 通知这个子组件 → 子组件 build() 重执行 → @BuilderParam 被重新调用"。 直接调用 @Builder 时,数据只是通过函数参数"悄悄"传入,框架没有建立这种正式的订阅关系。
针对@Builder 直接使用
┌─ 父组件 build() 的依赖追踪范围 ─────────────────┐ │ │ │ this.model.params → ✅ 直接追踪到 │ │ this.model → ✅ 追踪到(传递引用) │ │ │ │ verifyValueChange(this.model) │ │ │ │ │ └── 内部 $$.params → ⚠️ 在函数作用域内 │ │ 框架可能追踪不到 │ └─────────────────────────────────────────────────┘
使用子组件+ @ParamsBuilder+Builder
┌─ 子组件 build() 的依赖追踪范围 ─────────────────┐ │ │ │ @Param model → 框架已知:子组件绑定了这个对象 │ │ │ │ this.content(this.model) │ │ │ ↑ │ │ │ 通过 this 访问 → ✅ 框架追踪到了 │ │ │ │ │ └── Builder 内部用 this.model 的值渲染 │ │ │ │ 关键:this.model 作为 @Param 本身就被框架 │ │ 标记为"子组件的响应式数据源" │ └─────────────────────────────────────────────────┘
简单来说:其实就是子组件中@Param 绑定了父容器的@local 值;在父容器发生改变时;框架会追踪,并实现渲染;如果将@Param 改成@Local 就无法监听父容器改变,以及触发后续的渲染;