1# BuilderNode
2
3## 概述
4
5[BuilderNode](../reference/apis-arkui/js-apis-arkui-builderNode.md)提供能够挂载原生组件的能力，支持通过无状态的UI方法[全局自定义构建函数](../quick-start/arkts-builder.md#全局自定义构建函数)@Builder生成组件树，并通过[getFrameNode](../reference/apis-arkui/js-apis-arkui-builderNode.md#getframenode)获取组件树的根[FrameNode](../reference/apis-arkui/js-apis-arkui-frameNode.md)节点。该节点可以通过[NodeController](../reference/apis-arkui/js-apis-arkui-nodeController.md)直接返回，挂载在[NodeContainer](../reference/apis-arkui/arkui-ts/ts-basic-components-nodecontainer.md)节点下，也可以在FrameNode树结构和[RenderNode](../reference/apis-arkui/js-apis-arkui-renderNode.md)树结构嵌入声明式的组件结构，实现混合显示的能力。同时BuilderNode可以提供纹理导出的功能，导出的纹理用于在[XComponent](../reference/apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)中进行同层渲染显示。
6
7BuilderNode创建的ArkTS原生控件树支持与自定义节点(例如：FrameNode、RenderNode)进行关联使用，实现了原生组件与自定义节点的混合显示。对于使用自定义节点的能力进行对接的三方框架，BuilderNode为其提供了嵌入原生组件的能力。
8
9BuilderNode提供了组件预创建的能力，能够自定义原生组件的创建开始的时间，在后续的业务中动态挂载显示。对于一些在创建初始化耗时较长的声明式组件，比如[Web](../reference/apis-arkweb/ts-basic-components-web.md)、[XComponent](../reference/apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)等，预创建可以有效减少组件初始化的耗时。
10
11![zh-cn_image_builder-node](figures/builder-node.png)
12
13BuilderNode仅可作为叶子节点进行使用。如有更新需要，建议通过BuilderNode中的Update方式触发更新，不建议通过BuilderNode中获取的RenderNode对节点进行修改操作。
14
15> **说明：**
16> 
17> - BuilderNode只支持一个由[wrapBuilder](../quick-start/arkts-wrapBuilder.md)包装的[全局自定义构建函数](../quick-start/arkts-builder.md#全局自定义构建函数)@Builder。
18> 
19> - 一个新建的BuildNode在[build](../reference/apis-arkui/js-apis-arkui-builderNode.md#build)之后才能通过[getFrameNode](../reference/apis-arkui/js-apis-arkui-builderNode.md#getframenode)获取到一个指向根节点的FrameNode对象，否则返回null。
20> 
21> - 如果传入的Builder的根节点为语法节点（if/else/foreach/...），需要额外生成一个FrameNode，在节点树中的显示为“BuilderProxyNode”。
22> 
23> - 如果BuilderNode通过getFrameNode将节点挂载在另一个FrameNode上，或者将其作为子节点挂载在NodeContainer节点上。则节点中使用父组件的布局约束进行布局。
24> 
25> - 如果BuilderNode的FrameNode通过[getRenderNode](../reference/apis-arkui/js-apis-arkui-frameNode.md#getrendernode)形式将自己的节点挂载在RenderNode节点上，由于其FrameNode未上树，其大小默认为0，需要通过构造函数中的[selfIdeaSize](../reference/apis-arkui/js-apis-arkui-builderNode.md#renderoptions)显式指定布局约束大小，才能正常显示。
26> 
27> - BuilderNode的预加载并不会减少组件的创建时间。Web组件创建的时候需要在内核中加载资源，预创建不能减少Web组件的创建的时间，但是可以让内核进行预加载，减少正式使用时候内核的加载耗时。
28
29## 创建BuilderNode对象
30
31BuilderNode对象为一个模板类，需要在创建的时候指定类型。该类型需要与后续build方法中传入的[WrappedBuilder](../quick-start/arkts-wrapBuilder.md#wrapbuilder封装全局builder)的类型保持一致，否则会存在编译告警导致编译失败。
32
33## 创建原生组件树
34
35通过BuilderNode的build可以实现原生组件树的创建。依照传入的WrappedBuilder对象创建组件树，并持有组件树的根节点。
36
37> **说明：**
38>
39> 无状态的UI方法全局@Builder最多拥有一个根节点。
40>
41> build方法中对应的@Builder支持一个参数作为入参。
42>
43> build中对于@Builder嵌套@Builder进行使用的场景，需要保证嵌套的参数与build的中提供的入参一致。
44> 
45> 对于@Builder嵌套@Builder进行使用的场景，如果入参类型不一致，则要求增加[BuilderOptions](../reference/apis-arkui/js-apis-arkui-builderNode.md#buildoptions12)字段作为[build](../reference/apis-arkui/js-apis-arkui-builderNode.md#build12)的入参。
46> 
47> 需要操作BuilderNode中的对象时，需要保证其引用不被回收。当BuilderNode对象被虚拟机回收之后，它的FrameNode、RenderNode对象也会与后端节点解引用。即从BuilderNode中获取的FrameNode对象不对应任何一个节点。
48
49创建离线节点以及原生组件树，结合FrameNode进行使用。
50
51BuilderNode的根节点直接作为[NodeController](../reference/apis-arkui/js-apis-arkui-nodeController.md)的[makeNode](../reference/apis-arkui/js-apis-arkui-nodeController.md#makenode)返回值。
52
53```ts
54import { BuilderNode, FrameNode, NodeController, UIContext } from '@kit.ArkUI';
55
56class Params {
57  text: string = "";
58
59  constructor(text: string) {
60    this.text = text;
61  }
62}
63
64@Builder
65function buildText(params: Params) {
66  Column() {
67    Text(params.text)
68      .fontSize(50)
69      .fontWeight(FontWeight.Bold)
70      .margin({ bottom: 36 })
71  }
72}
73
74class TextNodeController extends NodeController {
75  private textNode: BuilderNode<[Params]> | null = null;
76  private message: string = "DEFAULT";
77
78  constructor(message: string) {
79    super();
80    this.message = message;
81  }
82
83  makeNode(context: UIContext): FrameNode | null {
84    this.textNode = new BuilderNode(context);
85    this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message))
86    return this.textNode.getFrameNode();
87  }
88}
89
90@Entry
91@Component
92struct Index {
93  @State message: string = "hello";
94
95  build() {
96    Row() {
97      Column() {
98        NodeContainer(new TextNodeController(this.message))
99          .width('100%')
100          .height(100)
101          .backgroundColor('#FFF0F0F0')
102      }
103      .width('100%')
104      .height('100%')
105    }
106    .height('100%')
107  }
108}
109```
110
111将BuilderNode与RenderNode进行结合使用。
112
113BuilderNode的RenderNode挂载其它RenderNode下时，需要明确定义[selfIdeaSize](../reference/apis-arkui/js-apis-arkui-builderNode.md#renderoptions)的大小作为BuilderNode的布局约束。不推荐通过该方式挂载节点。
114
115```ts
116import { NodeController, BuilderNode, FrameNode, UIContext, RenderNode } from "@kit.ArkUI";
117
118class Params {
119  text: string = "";
120
121  constructor(text: string) {
122    this.text = text;
123  }
124}
125
126@Builder
127function buildText(params: Params) {
128  Column() {
129    Text(params.text)
130      .fontSize(50)
131      .fontWeight(FontWeight.Bold)
132      .margin({ bottom: 36 })
133  }
134}
135
136class TextNodeController extends NodeController {
137  private rootNode: FrameNode | null = null;
138  private textNode: BuilderNode<[Params]> | null = null;
139  private message: string = "DEFAULT";
140
141  constructor(message: string) {
142    super();
143    this.message = message;
144  }
145
146  makeNode(context: UIContext): FrameNode | null {
147    this.rootNode = new FrameNode(context);
148    let renderNode = new RenderNode();
149    renderNode.clipToFrame = false;
150    this.textNode = new BuilderNode(context, { selfIdealSize: { width: 150, height: 150 } });
151    this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message));
152    const textRenderNode = this.textNode?.getFrameNode()?.getRenderNode();
153
154    const rootRenderNode = this.rootNode.getRenderNode();
155    if (rootRenderNode !== null) {
156      rootRenderNode.appendChild(renderNode);
157      renderNode.appendChild(textRenderNode);
158    }
159
160    return this.rootNode;
161  }
162}
163
164@Entry
165@Component
166struct Index {
167  @State message: string = "hello";
168
169  build() {
170    Row() {
171      Column() {
172        NodeContainer(new TextNodeController(this.message))
173          .width('100%')
174          .height(100)
175          .backgroundColor('#FFF0F0F0')
176      }
177      .width('100%')
178      .height('100%')
179    }
180    .height('100%')
181  }
182}
183```
184
185## 更新原生组件树
186
187通过BuilderNode对象的build创建原生组件树。依照传入的WrappedBuilder对象创建组件树，并持有组件树的根节点。
188
189自定义组件的更新遵循[状态管理](../quick-start/arkts-state-management-overview.md)的更新机制。WrappedBuilder中直接使用的自定义组件其父组件为BuilderNode对象。因此，更新子组件即WrappedBuilder中定义的自定义组件，需要遵循状态管理的定义将相关的状态变量定义为[\@Prop](../quick-start/arkts-prop.md)或者[\@ObjectLink](../quick-start/arkts-observed-and-objectlink.md)。装饰器的选择请参照状态管理的装饰器规格结合应用开发需求进行选择。
190
191
192使用update更新BuilderNode中的节点。
193
194使用[updateConfiguration](../reference/apis-arkui/js-apis-arkui-builderNode.md#updateconfiguration12)触发BuilderNode中节点的全量更新。
195
196更新BuilderNode中的节点。
197
198```ts
199import { NodeController, BuilderNode, FrameNode, UIContext } from "@kit.ArkUI";
200
201class Params {
202  text: string = "";
203  constructor(text: string) {
204    this.text = text;
205  }
206}
207
208// 自定义组件
209@Component
210struct TextBuilder {
211  // 作为自定义组件中需要更新的属性，数据类型为基础属性，定义为@Prop
212  @Prop message: string = "TextBuilder";
213
214  build() {
215    Row() {
216      Column() {
217        Text(this.message)
218          .fontSize(50)
219          .fontWeight(FontWeight.Bold)
220          .margin({ bottom: 36 })
221          .backgroundColor(Color.Gray)
222      }
223    }
224  }
225}
226
227@Builder
228function buildText(params: Params) {
229  Column() {
230    Text(params.text)
231      .fontSize(50)
232      .fontWeight(FontWeight.Bold)
233      .margin({ bottom: 36 })
234    TextBuilder({ message: params.text }) // 自定义组件
235  }
236}
237
238class TextNodeController extends NodeController {
239  private textNode: BuilderNode<[Params]> | null = null;
240  private message: string = "";
241
242  constructor(message: string) {
243    super()
244    this.message = message
245  }
246
247  makeNode(context: UIContext): FrameNode | null {
248    this.textNode = new BuilderNode(context);
249    this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message))
250    return this.textNode.getFrameNode();
251  }
252
253  update(message: string) {
254    if (this.textNode !== null) {
255      // 调用update进行更新。
256      this.textNode.update(new Params(message));
257    }
258  }
259}
260
261@Entry
262@Component
263struct Index {
264  @State message: string = "hello";
265  private textNodeController: TextNodeController = new TextNodeController(this.message);
266  private count = 0;
267
268  build() {
269    Row() {
270      Column() {
271        NodeContainer(this.textNodeController)
272          .width('100%')
273          .height(200)
274          .backgroundColor('#FFF0F0F0')
275        Button('Update')
276          .onClick(() => {
277            this.count += 1;
278            const message = "Update " + this.count.toString();
279            this.textNodeController.update(message);
280          })
281      }
282      .width('100%')
283      .height('100%')
284    }
285    .height('100%')
286  }
287}
288```
289
290## 解除实体节点引用关系
291
292由于BuilderNode对应的是后端的实体节点，正常的内存释放依赖前端对象的回收。如果期望直接释放后端的节点对象，则可以通过调用[dispose](../reference/apis-arkui/js-apis-arkui-builderNode.md#dispose12)与实体节点解除引用关系，此时持有的前端BuilderNode对象不再影响实体节点的生命周期。
293
294> **说明：**
295>
296> 当BuilderNode对象调用dispose之后，不仅BuilderNode对象与后端实体节点解除引用关系，BuilderNode中的FrameNode与RenderNode也会同步和实体节点解除引用关系。
297
298## 注入触摸事件
299
300BuilderNode中提供了[postTouchEvent](../reference/apis-arkui/js-apis-arkui-builderNode.md#posttouchevent)，可以通过该接口向BuilderNode中绑定的组件注入[触摸事件](../reference/apis-arkui/arkui-ts/ts-universal-events-touch.md#触摸事件)，实现事件的模拟转发。
301
302通过postTouchEvent向BuilderNode对应的节点树中注入触摸事件。
303
304向BuilderNode中的Column组件转发另一个Column的接收事件，即点击下方的Column组件，上方的Colum组件也会收到同样的触摸事件。当Button中的事件被成功识别的时候，返回值为true。
305
306```ts
307import { NodeController, BuilderNode, FrameNode, UIContext } from '@kit.ArkUI';
308
309class Params {
310  text: string = "this is a text";
311}
312
313@Builder
314function ButtonBuilder(params: Params) {
315  Column() {
316    Button(`button ` + params.text)
317      .borderWidth(2)
318      .backgroundColor(Color.Orange)
319      .width("100%")
320      .height("100%")
321      .gesture(
322        TapGesture()
323          .onAction((event: GestureEvent) => {
324            console.log("TapGesture");
325          })
326      )
327  }
328  .width(500)
329  .height(300)
330  .backgroundColor(Color.Gray)
331}
332
333class MyNodeController extends NodeController {
334  private rootNode: BuilderNode<[Params]> | null = null;
335  private wrapBuilder: WrappedBuilder<[Params]> = wrapBuilder(ButtonBuilder);
336
337  makeNode(uiContext: UIContext): FrameNode | null {
338    this.rootNode = new BuilderNode(uiContext);
339    this.rootNode.build(this.wrapBuilder, { text: "this is a string" })
340    return this.rootNode.getFrameNode();
341  }
342
343  postTouchEvent(touchEvent: TouchEvent): void {
344    if (this.rootNode == null) {
345      return;
346    }
347    let result = this.rootNode.postTouchEvent(touchEvent);
348    console.log("result " + result);
349  }
350}
351
352@Entry
353@Component
354struct MyComponent {
355  private nodeController: MyNodeController = new MyNodeController();
356
357  build() {
358    Column() {
359      NodeContainer(this.nodeController)
360        .height(300)
361        .width(500)
362      Column()
363        .width(500)
364        .height(300)
365        .backgroundColor(Color.Pink)
366        .onTouch((event) => {
367          if (event != undefined) {
368            this.nodeController.postTouchEvent(event);
369          }
370        })
371    }
372  }
373}
374```
375
376