harmony 鸿蒙XComponentNode

2025-06-12
浏览 (3)

XComponentNode

The XComponentNode module provides APIs for the XComponentNode, which represent an XComponent in the component tree. You can write EGL/OpenGL ES and media data and display it on the XComponent, whose rendering type can be dynamically modified.

NOTE

The APIs of this module are deprecated since API version 12. You are advised to use XComponent type node for implementation instead.

The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.

XComponentNode is not available in DevEco Studio Previewer.

Modules to Import

import { XComponentNode } from "@kit.ArkUI";

XComponentNode

constructor

constructor(uiContext: UIContext, options: RenderOptions, id: string, type: XComponentType, libraryName?: string)

A constructor used to create an XComponentNode.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
uiContext	UIContext	Yes	UI context. For details about how to obtain it, see Obtaining UI Context.
options	RenderOptions	Yes	Parameters for creating an XComponentNode.
id	string	Yes	Unique ID of the XComponent. The value can contain a maximum of 128 characters. For details, see XComponent.
type	XComponentType	Yes	Type of the XComponent. For details, see XComponent.
libraryName	string	No	Name of the dynamic library generated during compilation at the native layer. For details, see XComponent.

NOTE

You need to explicitly specify selfIdealSize in RenderOptions. Otherwise, the XComponentNode’s content size is empty, resulting in no content being displayed.

onCreate

onCreate(event?: Object): void

Called when the XComponentNode loading is complete.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
event	Object	No	Context of the XComponent object. The APIs contained in the context are defined by you at the C++ layer.

onDestroy

onDestroy(): void

Called when the XComponentNode is destroyed.

System capability: SystemCapability.ArkUI.ArkUI.Full

changeRenderType

changeRenderType(type: NodeRenderType): boolean

Changes the rendering type of the XComponentNode.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	NodeRenderType	Yes	Target rendering type.

Return value

Type	Description
boolean	Whether the rendering type is changed successfully.

Example

import { NodeController, FrameNode, XComponentNode, NodeRenderType, UIContext} from '@kit.ArkUI'

class XComponentNodeController extends NodeController {
  private xComponentNode: MyXComponentNode|null = null;
  private soName: string = "tetrahedron_napi" // This .so file is written and generated by you using the Node-API.

  constructor() {
    super();
  }

  makeNode(context: UIContext): FrameNode|null {
    this.xComponentNode = new MyXComponentNode(context, {
      selfIdealSize: { width: 200, height: 200 }
    }, "xComponentId", XComponentType.SURFACE, this.soName);
    return this.xComponentNode;
  }

  changeRenderType(renderType: NodeRenderType): void {
    if (this.xComponentNode) {
      this.xComponentNode.changeRenderType(renderType);
    }
  }
}

class MyXComponentNode extends XComponentNode {
  onCreate(event: Object) {
    // do something when XComponentNode has created
  }

  onDestroy() {
    // do something when XComponentNode is destroying
  }
}

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        NodeContainer(new XComponentNodeController())
      }
      .width('100%')
      .height('100%')
    }
    .height('100%')
  }
}

XComponentNodeSample