鸿蒙5.0开发进阶：ArkTS API UI界面（ArkUI）-BuilderNode

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

BuilderNode

提供能够挂载原生组件的自定义节点BuilderNode。BuilderNode仅可作为叶子节点使用。

说明

本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

当前不支持在预览器中使用BuilderNode。

导入模块

import { BuilderNode, RenderOptions, NodeRenderType } from "@kit.ArkUI";

NodeRenderType

节点渲染类型枚举。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
RENDER_TYPE_DISPLAY	0	表示该节点将被显示到屏幕上。
RENDER_TYPE_TEXTURE	1	表示该节点将被导出为纹理。

说明

RENDER_TYPE_TEXTURE类型目前仅在BuilderNode持有组件树的根节点为自定义组件时以及XComponentNode中设置生效。

在BuilderNode的情况下，目前在作为根节点的自定义组件中支持纹理导出的有以下组件：Badge、Blank、Button、CanvasGradient、CanvasPattern、CanvasRenderingContext2D、Canvas、CheckboxGroup、Checkbox、Circle、ColumnSplit、Column、ContainerSpan、Counter、DataPanel、Divider、Ellipse、Flex、Gauge、Hyperlink、ImageBitmap、ImageData、Image、Line、LoadingProgress、Marquee、Matrix2D、OffscreenCanvasRenderingContext2D、OffscreenCanvas、Path2D、Path、PatternLock、Polygon、Polyline、Progress、QRCode、Radio、Rating、Rect、RelativeContainer、RowSplit、Row、Shape、Slider、Span、Stack、TextArea、TextClock、TextInput、TextTimer、Text、Toggle、Video（不支持原生的全屏模式）、Web、XComponent。

从API version 12开始，新增以下组件支持纹理导出：DatePicker、ForEach、Grid、IfElse、LazyForEach、List、Scroll、Swiper、TimePicker、@Component修饰的自定义组件、NodeContainer以及NodeContainer下挂载的FrameNode和RenderNode。

RenderOptions

创建BuilderNode时的可选参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
selfIdealSize	Size	否	节点的理想大小。
type	NodeRenderType	否	节点的渲染类型。
surfaceId	string	否	纹理接收方的surfaceId。纹理接收方一般为OH_NativeImage。

BuilderNode

class BuilderNode<Args extends Object[]>

BuilderNode支持通过无状态的UI方法@Builder生成组件树，并持有组件树的根节点。不支持定义为状态变量。BuilderNode中持有的FrameNode仅用于将该BuilderNode作为子节点挂载到其他FrameNode上。对BuilderNode持有的FrameNode进行属性设置与子节点操作可能会产生未定义行为，因此不建议通过BuilderNode的getFrameNode方法和FrameNode的