在组件树中,当一个自定义节点被同时挂载到多个父节点下,会导致UI渲染异常(如UI不显示、白块等)。该问题可通过以下方式确认:
在使用NodeController对Web组件等复杂节点进行上下树操作时,如果节点迁移过程中调用了reuse()方法,会触发自定义组件的aboutToReuse回调,导致不必要的重建和更新,从而出现卡顿现象。典型的问题伪代码如下:
interface EventParams {
NAME: string;
VALUE: string;
FROM: string;
}
export class CashierNodeController extends NodeController {
/** 内部 BuilderNode,持有组件 */
private builderNode: BuilderNode<[Object]> | null = null
/** 当前 URL */
private url: string = ''
/** 来源 */
private from: string | undefined = undefined
/** 是否已初始化数据 */
private hasData: boolean = false
private eventParams: EventParams = {
NAME: '',
VALUE: '',
FROM: ''
};
/**
* 设置收银台数据(URL + from)
* 在 openVipMultiKuflix 时调用
*/
setData(url: string, from: string | undefined): void {
this.url = url
this.from = from
this.hasData = true
// 如果BuilderNode已存在,直接更新
if (this.builderNode) {
const params = this.buildParams()
this.builderNode.update(params)
}
}
/**
* 构建参数 Map
*/
private buildParams(): Map<string, string> {
const params: Map<string, string> = new Map()
params.set(this.eventParams.NAME, 'vip_weex_url')
params.set(this.eventParams.VALUE, this.url)
if (this.from) {
params.set(this.eventParams.FROM, this.from)
}
return params
}
/**
* NodeController 必须实现的方法
* 首次调用时 build() 创建,后续 FrameNode 重新附着到新 NodeContainer 时
* 调用 reuse() 跳过组件 aboutToDisappear/aboutToAppear 重建
*/
makeNode(uiContext: UIContext): FrameNode | null {
if (!this.hasData) {
return null
}
if (!this.builderNode) {
// 首次创建
this.builderNode = new BuilderNode(uiContext)
const params = this.buildParams()
this.builderNode.build(wrapBuilder(MultiScreenCashierViewBuilder), params)
} else {
// 重新附着到新NodeContainer(横竖屏切换):reuse跳过组件重建
const params = this.buildParams()
this.builderNode.reuse(params)
}
return this.builderNode.getFrameNode()
}
/**
* 获取当前 URL
*/
getUrl(): string {
return this.url
}
/**
* 获取当前 from
*/
getFrom(): string | undefined {
return this.from
}
/**
* NodeContainer 移除时回调
* 不销毁 BuilderNode,因为 FrameNode 需要被另一个 NodeContainer 接管
*/
aboutToDisappear(): void {
// 子母屏↔半屏切换时NodeContainer会被移除,但FrameNode不应销毁
// 此处不做dispose,由外部显式调用dispose()来释放
}
/**
* 释放资源
*/
dispose(): void {
this.builderNode?.dispose()
this.builderNode = null
this.hasData = false
}
}
@Builder
function MultiScreenCashierViewBuilder(args_0: Object): void {
} 上述代码中,makeNode()方法在BuilderNode已存在时调用了reuse(),这会在节点迁移时触发aboutToReuse回调,导致组件重建和卡顿。
节点双挂问题的原因在于单个自定义节点(如BuilderNode)实例被多个NodeController引用并同时尝试挂载到不同的NodeContainer。这违反了每个节点只能有一个父节点的原则。
在实际开发中,开发者希望复用BuilderNode实例以提升性能,但存在下面问题:
因此,更符合实际需求的解决方案是实现同一个BuilderNode实例在不同NodeContainer间的迁移,而非同时挂载。以下方案通过自定义NodeController实现节点挂载前的父节点状态检查,确保同一时间节点仅挂载到一个NodeContainer。整体的实现思路如下:
以下是示例代码:
步骤一:创建自定义NodeController。
import { BuilderNode, NodeController } from '@kit.ArkUI';
// 用于控制和反馈对应的NodeContainer上的节点的行为,需要与NodeContainer一起使用
export class MyNodeController extends NodeController {
private builderNode: BuilderNode<[string]> | null | undefined = null;
private rootNode: FrameNode | null = null;
constructor(builderNode: BuilderNode<[string]> | undefined | null) {
super();
this.builderNode = builderNode;
}
makeNode(): FrameNode | null {
// 返回要挂载到NodeContainer的根节点
return this.rootNode;
}
// 挂载Content
attachContent(): void {
if (this.builderNode) {
let frameNode: FrameNode | null = this.builderNode.getFrameNode();
// 关键检查:确保节点未被挂载到其他父节点
if (frameNode?.getParent() != null) {
return; // 节点已有父节点,跳过
}
this.rootNode = this.builderNode.getFrameNode();
}
}
// 卸载Content
detachContent(): void {
this.rootNode = null; // 清空根节点引用
}
} 步骤二:定义可复用的UI构建器。
// @Builder中为动态组件的具体组件内容
// 这里只为举例说明,UI组件描述比较简单,实际应用场景中,这里是比较复杂的UI组件描述,如Web组件等
@Builder
function ContentBuilder(data: string) {
Column() {
Text(data).fontSize(24);
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.backgroundColor(Color.Blue);
}
// 包装Builder函数以供BuilderNode使用
let wrap = wrapBuilder<[string]>(ContentBuilder); 步骤三:在入口组件实现节点的迁移。
@Entry
@Component
struct Index {
// 单例BuilderNode,可被多个NodeController共享
private builderNode: BuilderNode<[string]> | null | undefined = new BuilderNode(this.getUIContext());
// 两个NodeController共享同一BuilderNode实例
private nodeController1: MyNodeController = new MyNodeController(this.builderNode);
private nodeController2: MyNodeController = new MyNodeController(this.builderNode);
aboutToAppear(): void {
// 初始化BuilderNode内容
this.builderNode?.build(wrap, 'This is a Text');
}
// 本例两个不同的NodeContainer只一个组件内,只为举例演示直观
// 实际应用场景中,NodeContainer通常在不同的页面,甚至不同的窗口中
build() {
Column({ space: 20 }) {
// 第一个NodeContainer区域
Column({ space: 20 }) {
Button('Attach Content')
.onClick(() => {
this.nodeController1.attachContent();
this.nodeController1.rebuild(); // 触发界面更新
});
Button('Detach Content')
.onClick(() => {
this.nodeController1.detachContent();
this.nodeController1.rebuild();
});
NodeContainer(this.nodeController1)
.height('50%')
.width('50%')
.borderWidth(1);
Text('我是NodeContainer1');
}
.height('50%');
Divider();
// 第二个NodeContainer区域
Column({ space: 20 }) {
Button('Attach Content')
.onClick(() => {
this.nodeController2.attachContent();
this.nodeController2.rebuild();
});
Button('Detach Content')
.onClick(() => {
this.nodeController2.detachContent();
this.nodeController2.rebuild();
});
NodeContainer(this.nodeController2)
.height('50%')
.width('50%')
.borderWidth(1);
Text('我是NodeContainer2');
}
.height('50%');
}
.height('100%');
}
} 在Web组件等复杂节点场景中,节点迁移时还需注意避免调用reuse()方法。当FrameNode从一个NodeContainer转移到另一个时,makeNode会被再次调用,此时节点已经存在,只需直接返回getFrameNode()即可。调用reuse()会触发自定义组件的aboutToReuse回调,导致不必要的重建和更新,这是卡顿的主要原因。
一个BuilderNode的FrameNode同一时间只能挂在一个NodeContainer下,如果旧的NodeContainer还未卸载就挂到新的,会出现双挂异常。要实现Web组件节点不做重建切换不同容器,可以先从旧容器卸载(调用rebuild()使makeNode返回null),再挂载到新容器(调用rebuild()使makeNode返回FrameNode)。
以下是Web组件节点在不同容器间无重建切换的示例代码:
步骤一:创建Web组件的NodeController。
import { BuilderNode, FrameNode, NodeController, UIContext } from '@kit.ArkUI'
import { webview } from '@kit.ArkWeb'
export class WebData {
url: string = ''
controller: webview.WebviewController = new webview.WebviewController()
constructor(url: string, controller: webview.WebviewController) {
this.url = url
this.controller = controller
}
}
@Builder
function WebBuilder(data: WebData) {
Column() {
Web({ src: data.url, controller: data.controller })
.width('100%')
.height('100%')
// 以下安全配置仅用于演示,生产环境须收紧:
// - mixedMode建议设为MixedMode.None或MixedMode.Compatibility
// - fileAccess建议关闭
.domStorageAccess(true)
.javaScriptAccess(true)
.fileAccess(true)
.imageAccess(true)
.onlineImageAccess(true)
.mixedMode(MixedMode.All)
}
.width('100%')
.height('100%')
}
let webBuilderWrapper = wrapBuilder<[WebData]>(WebBuilder)
export class WebNodeController extends NodeController {
private sharedBuilderNode: BuilderNode<[WebData]> | null = null
private activeNode: FrameNode | null = null
constructor(builderNode: BuilderNode<[WebData]>, mounted: boolean) {
super()
this.sharedBuilderNode = builderNode
if (mounted) {
this.activeNode = builderNode.getFrameNode()
}
}
makeNode(uiContext: UIContext): FrameNode | null {
return this.activeNode
}
mount(): void {
if (this.sharedBuilderNode === null) {
return
}
const frameNode = this.sharedBuilderNode.getFrameNode()
// 关键检查:确保节点未被挂载到其他父节点
if (frameNode?.getParent() != null) {
return
}
this.activeNode = frameNode
this.rebuild()
}
unmount(): void {
this.activeNode = null
this.rebuild()
}
}
export function createSharedBuilderNode(url: string, uiContext: UIContext): BuilderNode<[WebData]> {
let controller: webview.WebviewController = new webview.WebviewController()
let builderNode: BuilderNode<[WebData]> = new BuilderNode(uiContext)
builderNode.build(webBuilderWrapper, new WebData(url, controller))
return builderNode
} 步骤二:在入口组件中实现Web组件的容器切换。
// WebNodeController、createSharedBuilderNode、WebData定义在步骤一中
// 实际项目中请根据文件存放位置调整import路径
import { WebNodeController, createSharedBuilderNode, WebData } from '../common/WebNodeController'
import { BuilderNode, UIContext } from '@kit.ArkUI'
@Entry
@Component
struct Index {
@State activeTab: string = 'A'
private sharedBuilderNode: BuilderNode<[WebData]> | null = null
private controllerA: WebNodeController | null = null
private controllerB: WebNodeController | null = null
aboutToAppear(): void {
let uiContext: UIContext = this.getUIContext()
this.sharedBuilderNode = createSharedBuilderNode('https://www.example.com', uiContext)
this.controllerA = new WebNodeController(this.sharedBuilderNode, true)
this.controllerB = new WebNodeController(this.sharedBuilderNode, false)
}
switchTo(tab: string): void {
if (this.activeTab === tab) {
return
}
let oldController: WebNodeController | null = this.activeTab === 'A' ? this.controllerA : this.controllerB
let newController: WebNodeController | null = tab === 'A' ? this.controllerA : this.controllerB
oldController?.unmount()
newController?.mount()
this.activeTab = tab
}
build() {
Column() {
Text('Web NodeController 容器切换 Demo')
.fontSize(20)
.fontWeight(FontWeight.Bold)
.margin({ bottom: 16 })
Row({ space: 12 }) {
Button('容器 A')
.onClick(() => this.switchTo('A'))
.backgroundColor(this.activeTab === 'A' ? '#317AF7' : '#CCCCCC')
Button('容器 B')
.onClick(() => this.switchTo('B'))
.backgroundColor(this.activeTab === 'B' ? '#317AF7' : '#CCCCCC')
}
.margin({ bottom: 16 })
Stack() {
if (this.controllerA) {
NodeContainer(this.controllerA)
.width('100%')
.height(300)
.borderWidth(2)
.borderColor('#317AF7')
.borderRadius(8)
.visibility(this.activeTab === 'A' ? Visibility.Visible : Visibility.None)
}
if (this.controllerB) {
NodeContainer(this.controllerB)
.width('100%')
.height(300)
.borderWidth(2)
.borderColor('#FF6B6B')
.borderRadius(8)
.visibility(this.activeTab === 'B' ? Visibility.Visible : Visibility.None)
}
}
.width('100%')
.height(300)
.margin({ bottom: 12 })
}
.width('100%')
.height('100%')
.padding(16)
}
} switchTo()方法先调用旧容器的unmount()卸载节点,再调用新容器的mount()挂载节点,实现Web组件节点在不同容器间的无重建切换。