ComponentV2 ,Builder , wrapperBuilder,命名式Node 使用状态时迷糊点

0 阅读3分钟

针对ComponentV2 ,Builder , wrapperBuilder,命名式Node 区分

1.针对ComponentV2 ,Builder , wrapperBuilder区别:

ComponentV2BuilderwrapBuilder
本质自定义组件(声明式)轻量 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 │ └──────────────────────────────────────────────┘

  1. 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 就无法监听父容器改变,以及触发后续的渲染;