目录

XComponentNode

The XComponentNode module provides APIs for the XComponentNode, which represents an XComponent in the component tree. You can write EGL/OpenGL ES and media data and display it on the XComponent, whose render type can be dynamically modified. It is suitable for scenarios where native self-rendering content needs to be embedded in the ArkUI component tree.

  • The APIs of this module are supported since API version 11 and deprecated since API version 12. You are advised to use the APIs of the typeNode module in the XComponent type instead.

  • The APIs of this module can be used only in the stage model.

  • 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(deprecated)

[h2]constructor(deprecated)

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

Constructor used to create an XComponentNode.

This API is supported since API version 11 and deprecated since API version 12. You are advised to use createNode instead.

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 Rendering options of an XComponentNode, used to set node rendering related parameters such as the ideal size (selfIdealSize).
id string Yes Unique ID of the XComponent. The value can contain a maximum of 128 characters. If the length exceeds the limit, the API fails to create the component. For details, see XComponent.
type XComponentType Yes Type of the XComponent, specified using the XComponentType enumeration. For details, see XComponent.
libraryName string No Name of the dynamic library compiled and output at the native layer. If this parameter is not passed, the native dynamic library is not loaded by default. For details, see XComponent.

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

[h2]onCreate(deprecated)

onCreate(event?: Object): void

Called when the XComponentNode loading is complete.

This API is supported since API version 11 and deprecated since API version 12. You are advised to use onLoad instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
event Object No Event parameter of the XComponent instance, used to obtain the context of the XComponent instance. The APIs mounted on the context are defined by you at the C++ layer, and you can call the APIs registered at the native layer through this context.

[h2]onDestroy(deprecated)

onDestroy(): void

Called when the XComponentNode is destroyed.

This API is supported since API version 11 and deprecated since API version 12. You are advised to use onDestroy instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

[h2]changeRenderType(deprecated)

changeRenderType(type: NodeRenderType): boolean

Dynamically changes the render type of the XComponentNode. The render policy can be switched dynamically at runtime, which is suitable for scenarios where different render types are selected based on content rendering requirements. For example, the DISPLAY type can be used when direct EGL/OpenGL ES drawing on the component is required; the TEXTURE type can be used when the rendered content needs to participate in composition as a texture (such as implementing semi-transparent overlay effects or off-screen rendering).

This API is supported since API version 11 and deprecated since API version 12. You are advised to use appendChild instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
type NodeRenderType Yes Target render type to change, specified using the NodeRenderType enumeration.

Return value

Type Description
boolean Whether the render type is changed successfully. The value true indicates that the render type is changed successfully, and false indicates the opposite.

Example

import { NodeController, FrameNode, XComponentNode, NodeRenderType, XComponentType, 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%')
  }
}