FrameNode

appendChild¹²⁺

appendChild(node: FrameNode): void

Appends a child node to the end of this FrameNode. If this FrameNode is not modifiable, an exception is thrown. When appendChild is called, typeNode validates the type or number of child nodes. If the validation fails, an exception is thrown. For specific limitations, see typeNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Child node to append. The target node must not be a declaratively created node, that is, a FrameNode that is not modifiable. Only declarative nodes obtained from a BuilderNode can be used as child nodes. If the child node does not meet the specifications, an exception is thrown. The FrameNode cannot have a parent node. Otherwise, an exception is thrown.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The FrameNode is not modifiable.
100025	The parameter is invalid. Details about the invalid parameter and the reason are included in the error message. For example: "The parameter 'node' is invalid: it cannot be adopted."

Example

insertChildAfter¹²⁺

insertChildAfter(child: FrameNode, sibling: FrameNode | null): void

Inserts a child node after the specified child node of this FrameNode. If this FrameNode is not modifiable, an exception is thrown.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
child	FrameNode	Yes	Child node to add. The target child node must not be a declaratively created node, that is, a FrameNode that is not modifiable. Only declarative nodes obtained from a BuilderNode can be used as child nodes. If the child node does not meet the specifications, an exception is thrown. The child node cannot have a parent node. Otherwise, an exception is thrown.
sibling	FrameNode \| null	Yes	Node after which the new child node will be inserted. If this parameter is left empty, the new node is inserted before the first subnode.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The FrameNode is not modifiable.
100025	The parameter is invalid. Details about the invalid parameter and the reason are included in the error message. For example: "The parameter 'child' is invalid: it cannot be adopted."

Example

removeChild¹²⁺

removeChild(node: FrameNode): void

Deletes the specified child node from this FrameNode. If this FrameNode is not modifiable, an exception is thrown.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Child node to delete.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The FrameNode is not modifiable.

Example

clearChildren¹²⁺

clearChildren(): void

Clears all child nodes of this FrameNode. If this FrameNode is not modifiable, an exception is thrown.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The FrameNode is not modifiable.

Example

getChild¹²⁺

getChild(index: number): FrameNode | null

Obtains the child node in the specified position of this node.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the child node to obtain. The value range of index is [0, +∞). If the current node has n child nodes, the valid value range of index is [0, n-1].

Return value

Type	Description
FrameNode \| null	Child node obtained. If the FrameNode does not contain the specified child node, null is returned.

Example

See Example of Node Operations in the LazyForEach Scenario.

getChild¹⁵⁺

getChild(index: number, expandMode?: ExpandMode): FrameNode | null

Obtains a child node at a specified index from this FrameNode, with optional support for specifying the expansion mode of the child node.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
index	number	Yes	Index of the child node to obtain. The value range of index is [0, +∞). If the current node has n child nodes, the valid value range of index is [0, n-1].
expandMode	ExpandMode	No	Expansion mode of the child node. Default value: ExpandMode.EXPAND.

Return value

Type	Description
FrameNode \| null	Child node obtained. If the FrameNode does not contain the specified child node, null is returned.

Example

getFirstChildIndexWithoutExpand¹⁵⁺

getFirstChildIndexWithoutExpand(): number

Obtains the sequence number of the first child node of this node that is in the main node tree. The child node sequence numbers are calculated based on all child nodes.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	Sequence number of the first child node of this node that is in the main node tree.

Example

See Example of Node Operations in the LazyForEach Scenario.

getLastChildIndexWithoutExpand¹⁵⁺

getLastChildIndexWithoutExpand(): number

Obtains the sequence number of the last child node of this node that is in the main node tree. The child node sequence numbers are calculated based on all child nodes.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	Sequence number of the last child node of this node that is in the main node tree.

Example

See Example of Node Operations in the LazyForEach Scenario.

getFirstChild¹²⁺

getFirstChild(): FrameNode | null

Obtains the first child node of this FrameNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
FrameNode \| null	First child node. If the FrameNode does not contain any child node, null is returned.

Example

getNextSibling¹²⁺

getNextSibling(): FrameNode | null

Obtains the next sibling node of this FrameNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
FrameNode \| null	Next sibling node of the current FrameNode. If the FrameNode does not have the next sibling node, null is returned.

Example

getPreviousSibling¹²⁺

getPreviousSibling(): FrameNode | null

Obtains the previous sibling node of this FrameNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
FrameNode \| null	Previous sibling node of the current FrameNode. If the FrameNode does not have the previous sibling node, null is returned.

Example

getParent¹²⁺

getParent(): FrameNode | null

Obtains the parent node of this FrameNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
FrameNode \| null	Parent node of the current FrameNode. If the FrameNode does not contain a parent node, null is returned.

Example

See Example of Node Operations and Example of Obtaining the Root Node.

getChildrenCount¹²⁺

getChildrenCount(): number

Obtains the number of child nodes of this FrameNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	Number of child nodes of the current FrameNode.

Example

getChildrenCount

getChildrenCount(countMode?: ChildrenCountMode): int

Obtains the number of child nodes of this FrameNode based on the specified counting mode.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
countMode	ChildrenCountMode	No	Mode of counting child nodes. The default value is ChildrenCountMode.ALL_EXPAND.

Return value

Type	Description
int	Number of child nodes of this FrameNode, which is returned based on the counting mode.

Example

import { NodeController, FrameNode, UIContext, BuilderNode, ExpandMode, ChildrenCountMode, LengthUnit } from '@kit.ArkUI';

const TEST_TAG: string = 'FrameNode '

// BasicDataSource implements the IDataSource API to manage listeners and notify LazyForEach of data updates.
class BasicDataSource implements IDataSource {
  private listeners: DataChangeListener[] = [];
  private originDataArray: string[] = [];

  public totalCount(): number {
    return 0;
  }

  public getData(index: number): string {
    return this.originDataArray[index];
  }

  // Called by the framework to register a listener with the LazyForEach data source.
  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      console.info('add listener');
      this.listeners.push(listener);
    }
  }

  // This method is called by the framework to remove the listener from the LazyForEach data source.
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener);
    if (pos >= 0) {
      console.info('remove listener');
      this.listeners.splice(pos, 1);
    }
  }

  // Notify LazyForEach that all child components need to be reloaded.
  notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded();
    })
  }

  // Notify LazyForEach that a child component needs to be added for the data item with the specified index.
  notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdd(index);
    })
  }

  // Notify LazyForEach that the data item with the specified index has changed and the child component needs to be rebuilt.
  notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChange(index);
    })
  }

  // Notify LazyForEach that the child component that matches the specified index needs to be deleted.
  notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDelete(index);
    })
  }

  // Notify LazyForEach that data needs to be swapped between the from and to positions.
  notifyDataMove(from: number, to: number): void {
    this.listeners.forEach(listener => {
      listener.onDataMove(from, to);
    })
  }

  notifyDatasetChange(operations: DataOperation[]): void {
    this.listeners.forEach(listener => {
      listener.onDatasetChange(operations);
    })
  }
}

// Manage the string array using the custom data management class.
class MyDataSource extends BasicDataSource {
  private dataArray: string[] = []

  public totalCount(): number {
    return this.dataArray.length;
  }

  public getData(index: number): string {
    return this.dataArray[index];
  }

  public addData(index: number, data: string): void {
    this.dataArray.splice(index, 0, data);
    this.notifyDataAdd(index);
  }

  public pushData(data: string): void {
    this.dataArray.push(data);
    this.notifyDataAdd(this.dataArray.length - 1);
  }
}

class Params {
  data: MyDataSource | null = null;
  scroller: Scroller | null = null;

  constructor(data: MyDataSource, scroller: Scroller) {
    this.data = data;
    this.scroller = scroller;
  }
}

@Builder
function buildData(params: Params) {
  List({ scroller: params.scroller }) {
    LazyForEach(params.data, (item: string) => {
      ListItem() {
        Column() {
          Text(item)
            .fontSize(20)
            .onAppear(() => {
              console.info(`${TEST_TAG} node appear: ${item}`)
            })
            .backgroundColor(Color.Pink)
            .margin({
              top: 30,
              bottom: 30,
              left: 10,
              right: 10
            })
        }
      }
      .id(item)
    }, (item: string) => item)
  }
  .cachedCount(5)
  .listDirection(Axis.Horizontal)
}

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  private rootNode: FrameNode | null = null;
  private uiContext: UIContext | null = null;
  private data: MyDataSource = new MyDataSource();
  private scroller: Scroller = new Scroller();

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    for (let i = 0; i <= 20; i++) {
      this.data.pushData(`N${i}`);
    }
    const params: Params = new Params(this.data, this.scroller);
    const dataNode: BuilderNode<[Params]> = new BuilderNode(uiContext);
    dataNode.build(wrapBuilder<[Params]>(buildData), params);
    this.rootNode = dataNode.getFrameNode();
    const scrollToIndexOptions: ScrollToIndexOptions = {
      extraOffset: {
        value: 20, unit: LengthUnit.VP
      }
    };
    this.scroller.scrollToIndex(6, true, ScrollAlign.START, scrollToIndexOptions);
    return this.rootNode;
  }

  getChildCountAllExpand() {
    const childCount = this.rootNode?.getChildrenCount(ChildrenCountMode.ALL_EXPAND);
    console.info(TEST_TAG + 'ALL_EXPAND, childCount=' + childCount);
  }

  getChildCountOnlyExpanded() {
    const childCount = this.rootNode?.getChildrenCount(ChildrenCountMode.ONLY_EXPANDED);
    console.info(TEST_TAG + 'ONLY_EXPANDED, childCount=' + childCount);
  }
  
  getChildCountAllNotExpand() {
    const childCount = this.rootNode?.getChildrenCount(ChildrenCountMode.ALL_NOT_EXPAND);
    console.info(TEST_TAG + 'ALL_NOT_EXPAND, childCount=' + childCount);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text('This is a NodeContainer.')
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button('getChildCount(ALL_EXPAND)')
          .width(300)
          .onClick(() => {
            this.myNodeController.getChildCountAllExpand();
          })
        Button('getChildCount(ONLY_EXPANDED)')
          .width(300)
          .onClick(() => {
            this.myNodeController.getChildCountOnlyExpanded();
          })
        Button('getChildCount(ALL_NOT_EXPAND)')
          .width(300)
          .onClick(() => {
            this.myNodeController.getChildCountAllNotExpand();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

moveTo¹⁸⁺

moveTo(targetParent: FrameNode, index?: number): void

Moves this FrameNode to a specified position within the target FrameNode. If this FrameNode is not modifiable, an exception is thrown. When targetParent is a typeNode, the API validates the type or number of child nodes. If the validation fails, an exception is thrown. For specific limitations, see typeNode.

NOTE

Currently, only the following types of TypedFrameNode are supported for the movement operations: Stack, XComponent. This API does not work for other node types.

This API only supports BuilderNode with root components of these types: Stack, XComponent, EmbeddedComponent. This API does not work for other component types.

Atomic service API: This API can be used in atomic services since API version 18.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
targetParent	FrameNode	Yes	Target parent node. The target parent node must not be a declaratively created node, that is, a FrameNode that is not modifiable. If it does not meet the specifications, an exception is thrown.
index	number	No	Index of the child node. The current FrameNode will be inserted before the child node at the specified sequence number in the target FrameNode. If the target FrameNode has n nodes, the value range for index is 0, n-1]. If the parameter is invalid or not specified, the current FrameNode will be added to the end of the target FrameNode. Default value: -1

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The FrameNode is not modifiable.
100027	The current node has been adopted.

Example

getPositionToWindow¹²⁺

getPositionToWindow(): Position

Obtains the position offset of this FrameNode relative to the window, in vp.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the window, in vp.

Example

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

const TEST_TAG: string = "FrameNode ";

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  private rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.rootNode.appendChild(this.frameNode);
    return this.rootNode;
  }

  getPositionToWindow() {
    // Obtain the offset of a FrameNode relative to the window.
    let positionToWindow = this.rootNode?.getPositionToWindow();
    console.info(`${TEST_TAG}${JSON.stringify(positionToWindow)}`);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text("This is a NodeContainer.")
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button("getPositionToWindow")
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToWindow();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

getPositionToParent¹²⁺

getPositionToParent(): Position

Obtains the position offset of this FrameNode relative to the parent component, in vp.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the parent component, in vp.

Example

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

const TEST_TAG: string = "FrameNode ";

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  private rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.rootNode.appendChild(this.frameNode);
    return this.rootNode;
  }

  getPositionToParent() {
    // Obtain the offset of FrameNode relative to its parent component.
    let positionToParent = this.rootNode?.getPositionToParent();
    console.info(`${TEST_TAG}${JSON.stringify(positionToParent)}`);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text("This is a NodeContainer.")
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button("getPositionToParent")
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToParent();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

getPositionToScreen¹²⁺

getPositionToScreen(): Position

Obtains the position offset of this FrameNode relative to the screen, in vp.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the screen, in vp.

Example

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

const TEST_TAG: string = "FrameNode ";

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  private rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.rootNode.appendChild(this.frameNode);
    return this.rootNode;
  }

  getPositionToScreen() {
    // Obtain the offset of a FrameNode relative to the screen.
    let positionToScreen = this.rootNode?.getPositionToScreen();
    console.info(`${TEST_TAG}${JSON.stringify(positionToScreen)}`);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text("This is a NodeContainer.")
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button("getPositionToScreen")
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToScreen();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

getGlobalPositionOnDisplay²⁰⁺

getGlobalPositionOnDisplay(): Position

Obtains the position offset of this FrameNode relative to the global display, in vp.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the global display, in vp.

Example

getPositionToParentWithTransform¹²⁺

getPositionToParentWithTransform(): Position

Obtains the position offset of a FrameNode relative to its drawing-enabled parent component, in vp. Drawing attributes include transform and translate. This API returns the upper left corner coordinates after component layout.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the parent component, in vp. If other drawing attributes (such as transform and translate) are set, the return value may slightly deviate due to the precision of floating point numbers.

Example

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

const TEST_TAG: string = "FrameNode ";

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  private rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.rootNode.appendChild(this.frameNode);
    return this.rootNode;
  }

  getPositionToParentWithTransform() {
    // Obtain the offset of the FrameNode relative to its drawing-enabled parent component.
    let positionToParentWithTransform = this.rootNode?.getPositionToParentWithTransform();
    console.info(`${TEST_TAG}${JSON.stringify(positionToParentWithTransform)}`);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text("This is a NodeContainer.")
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button("getPositionToParentWithTransform")
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToParentWithTransform();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

getPositionToWindowWithTransform¹²⁺

getPositionToWindowWithTransform(): Position

Obtains the position offset of a FrameNode relative to the drawing-enabled window, in vp. Drawing attributes include transform and translate. This API returns the upper left corner coordinates after component layout.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the window, in vp. If other drawing attributes (such as transform and translate) are set, the return value may slightly deviate due to the precision of floating point numbers.

Example

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

const TEST_TAG: string = "FrameNode ";

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  private rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.rootNode.appendChild(this.frameNode);
    return this.rootNode;
  }

  getPositionToWindowWithTransform() {
    // Obtain the offset of the FrameNode relative to the drawing-enabled window.
    let positionToWindowWithTransform = this.rootNode?.getPositionToWindowWithTransform();
    console.info(`${TEST_TAG}${JSON.stringify(positionToWindowWithTransform)}`);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text("This is a NodeContainer.")
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }
        Button("getPositionToWindowWithTransform")
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToWindowWithTransform();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

getPositionToScreenWithTransform¹²⁺

getPositionToScreenWithTransform(): Position

Obtains the position offset of a FrameNode relative to the drawing-enabled screen, in vp. Drawing attributes include transform and translate. This API returns the upper left corner coordinates after component layout.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the node relative to the screen, in vp. If other drawing attributes (such as transform and translate) are set, the return value may slightly deviate due to the precision of floating point numbers.

Example

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

const TEST_TAG: string = "FrameNode ";

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  private rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.rootNode.appendChild(this.frameNode);
    return this.rootNode;
  }

  getPositionToScreenWithTransform() {
    // Obtain the offset of the FrameNode relative to the drawing-enabled screen.
    let positionToScreenWithTransform = this.rootNode?.getPositionToScreenWithTransform();
    console.info(`${TEST_TAG}${JSON.stringify(positionToScreenWithTransform)}`);
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Text("This is a NodeContainer.")
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button("getPositionToScreenWithTransform")
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToScreenWithTransform();
          })
      }
      .width("100%")
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

getMeasuredSize¹²⁺

getMeasuredSize(): Size

Obtains the measured size of this FrameNode, in px.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Size	Measured size of the node, in px.

Example

getLayoutPosition¹²⁺

getLayoutPosition(): Position

Obtains the position offset of this FrameNode relative to the parent component after layout, in px. The offset is the result of the parent component's layout on this node; therefore, the offset attribute that takes effect after layout and the position attribute that does not participate in layout do not affect this offset value.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Position	Position offset of the current FrameNode relative to the parent component after layout, in px.

Example

getUserConfigBorderWidth¹²⁺

getUserConfigBorderWidth(): Edges<LengthMetrics>

Obtains the border width set by the user.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Edges<LengthMetrics>	Border width set by the user.

Example

getUserConfigPadding¹²⁺

getUserConfigPadding(): Edges<LengthMetrics>

Obtains the padding set by the user.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Edges<LengthMetrics>	Padding set by the user.

Example

getUserConfigMargin¹²⁺

getUserConfigMargin(): Edges<LengthMetrics>

Obtains the margin set by the user.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Edges<LengthMetrics>	Margin set by the user.

Example

getUserConfigSize¹²⁺

getUserConfigSize(): SizeT<LengthMetrics>

Obtains the width and height set by the user.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
SizeT<LengthMetrics>	Width and height set by the user.

Example

getId¹²⁺

getId(): string

Obtains the node ID set by the user, which is the same as the value of the component ID.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
string	Node ID set by the user, which is the same as the value of the component ID.

Example

getUniqueId¹²⁺

getUniqueId(): number

Obtains the system-assigned unique ID of the node.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	System-assigned unique ID of the node.

Example

getNodeType¹²⁺

getNodeType(): string

Obtains the type of the node. For built-in components, the node type corresponds to the component name. For example, the node type of the Button component is Button. For custom components that implement rendering, the node type is Common.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
string	Type of the node.

Example

getOpacity¹²⁺

getOpacity(): number

Obtains the opacity of the node. The minimum value is 0, and the maximum value is 1.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	Opacity of the node. Value range: [0, 1]. A larger value indicates lower opacity.

Example

isVisible¹²⁺

isVisible(): boolean

Obtains whether the node is visible.

NOTE

The visibility of a node is determined by the visibility attribute of the component.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	Whether the node is visible. The value true means that the node is visible, and false means the opposite.

Example

isClipToFrame¹²⁺

isClipToFrame(): boolean

Checks whether the node is clipped to the component area. This API returns true after the dispose API is called to release the reference to the FrameNode.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	Whether the node is clipped to the component area. The value true means that the node is clipped to the component area, and false means the opposite.

Example

isAttached¹²⁺

isAttached(): boolean

Obtains whether the node is mounted to the main node tree.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	Whether the node is mounted to the main node tree. The value true means that the node is mounted to the main node tree, and false means the opposite.

Example

isDisposed²⁰⁺

isDisposed(): boolean

Checks whether this FrameNode object has released its reference to its backend entity node. Frontend nodes maintain references to corresponding backend entity nodes. After a node calls the dispose API to release this reference, subsequent API calls may cause crashes or return default values. This API facilitates validation of node validity prior to operations, thereby mitigating risks in scenarios where calls after disposal are required.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	Whether the reference to the backend node is released. The value true means that the reference to backend node is released, and false means the opposite.

Example

See FrameNode Validity Check Example.

getInspectorInfo¹²⁺

getInspectorInfo(): Object

Obtains the structure information of the node, which is consistent with what is found in DevEco Studio's built-in ArkUI Inspector tool.

NOTE

The getInspectorInfo API is designed for debugging purposes to obtain information about all nodes. Frequent calls to this API may cause performance degradation.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Object	Structure information of the node.

The following example shows partial values from the query result of a Button node:

{
    "$type": "Button",
    "$ID": 44,
    "type": "build-in",
    "$rect": "[498.00, 468.00],[718.00,598.00]",
    "$debugLine": "",
    "$attrs": {
        "borderStyle": "BorderStyle.Solid",
        "borderColor": "#FF000000",
        "borderWidth": "0.00vp",
        "borderRadius": {
            "topLeft": "65.00px",
            "topRight": "65.00px",
            "bottomLeft": "65.00px",
            "bottomRight": "65.00px"
        },
        "border": "{\"style\":\"BorderStyle.Solid\",\"color\":\"#FF000000\",\"width\":\"0.00vp\",\"radius\":{\"topLeft\":\"65.00px\",\"topRight\":\"65.00px\",\"bottomLeft\":\"65.00px\",\"bottomRight\":\"65.00px\"},\"dashGap\":\"0.00vp\",\"dashWidth\":\"0.00vp\"}",
        "outlineStyle": "OutlineStyle.SOLID",
        "outlineColor": "#FF000000"
    }
}

Example

getCustomProperty¹²⁺

getCustomProperty(name: string): Object | undefined

Obtains the component's custom property by its name.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the custom property.

Return value

Type	Description
Object \| undefined	Value of the custom property.

Example

dispose¹²⁺

dispose(): void

Immediately releases the reference to the underlying FrameNode entity.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

NOTE

After the dispose API is called, the FrameNode object no longer corresponds to any entity FrameNode. In this case, attempts to call certain query APIs, such as getMeasuredSize and getLayoutPosition, will result in a JS crash in the application.

To check whether the current FrameNode object corresponds to an entity FrameNode, you can use getUniqueId API. A UniqueId value greater than 0 indicates that the object is associated with an entity FrameNode.

Example

import { NodeController, FrameNode, BuilderNode } from '@kit.ArkUI';

@Component
struct TestComponent {
  build() {
    Column() {
      Text('This is a BuilderNode.')
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .backgroundColor(Color.Gray)
  }

  aboutToAppear() {
    console.info('aboutToAppear');
  }

  aboutToDisappear() {
    console.info('aboutToDisappear');
  }
}

@Builder
function buildComponent() {
  TestComponent()
}

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  private rootNode: FrameNode | null = null;
  private builderNode: BuilderNode<[]> | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    this.builderNode = new BuilderNode(uiContext, { selfIdealSize: { width: 200, height: 100 } });
    this.builderNode.build(new WrappedBuilder(buildComponent));

    const rootRenderNode = this.rootNode.getRenderNode();
    if (rootRenderNode !== null) {
      rootRenderNode.size = { width: 200, height: 200 };
      rootRenderNode.backgroundColor = 0xffd5d5d5;
      rootRenderNode.appendChild(this.builderNode!.getFrameNode()!.getRenderNode());
    }

    return this.rootNode;
  }

  disposeFrameNode() {
    if (this.rootNode !== null && this.builderNode !== null) {
      // Remove all child nodes from rootNode before clearing the reference relationships.
      this.rootNode.removeChild(this.builderNode.getFrameNode());
      // Release the reference between builderNode and FrameNode.
      this.builderNode.dispose();
      // Release the reference between rootNode and FrameNode.
      this.rootNode.dispose();
    }
  }

  removeBuilderNode() {
    const rootRenderNode = this.rootNode!.getRenderNode();
    if (rootRenderNode !== null && this.builderNode !== null && this.builderNode.getFrameNode() !== null) {
      rootRenderNode.removeChild(this.builderNode!.getFrameNode()!.getRenderNode());
    }
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 4 }) {
      NodeContainer(this.myNodeController)
      Button('FrameNode dispose')
        .onClick(() => {
          this.myNodeController.disposeFrameNode();
        })
        .width('100%')
    }
  }
}

en-us_image_dispose

commonAttribute¹²⁺

get commonAttribute(): CommonAttribute

Obtains the CommonAttribute API associated with the FrameNode, which is used to configure universal attributes and universal events.

Note that only the attributes of a custom node can be modified.

NOTE

The visual representation of the FrameNode is similar to that of a Stack container that is aligned to the top start edge.

For details about the supported attributes, see attributeModifier Support for Attributes and Events.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
CommonAttribute	CommonAttribute API of the FrameNode, used to configure universal attributes and universal events.

Example

See Basic Event Example.

commonEvent¹²⁺

get commonEvent(): UICommonEvent

Obtains the UICommonEvent object held in this FrameNode to set basic events. The set basic events will compete with declaratively defined events for event handling without overriding them. If both event callbacks are registered, the declaratively defined event callback takes precedence.

In scenarios involving LazyForEach, where nodes may be destroyed and reconstructed, you need to reset or re-attach event listeners to the newly created nodes to ensure they respond to events correctly.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
UICommonEvent	UICommonEvent object, which is used to set basic events.

Example

See Basic Event Example and Example of Using Basic Events in the LazyForEach Scenario.

gestureEvent¹⁴⁺

get gestureEvent(): UIGestureEvent

Obtains the UIGestureEvent object held by this FrameNode, which is used to set gesture events bound to the component. Gesture events set using the gestureEvent API will not override gestures bound using the gesture binding API. If both APIs are used to set gestures, the gesture binding API takes precedence.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
UIGestureEvent	UIGestureEvent object, which is used to set the gestures bound to the component.

Example

For details, see Gesture Event Example.

onDraw¹²⁺

onDraw?(context: DrawContext): void

Implements custom drawing for the FrameNode. This API overrides the default drawing behavior and is invoked during FrameNode content rendering.

Note: The Canvas provided in the DrawContext parameter is a temporary command-recording canvas, not the actual rendering canvas of the node. For usage instructions, see Adjusting the Transformation Matrix of the Custom Drawing Canvas.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	DrawContext	Yes	Graphics drawing context. The self-drawing area cannot exceed the component's own size.

Example

onMeasure¹²⁺

onMeasure(constraint: LayoutConstraint): void

Called when this FrameNode needs to determine its size. This API provides custom measurement and overrides the default measurement method.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
constraint	LayoutConstraint	Yes	Layout constraints used by the component for measurement.

Example

onLayout¹²⁺

onLayout(position: Position): void

Called when this FrameNode needs to determine its layout. This API provides custom layout and overrides the default layout method. It can be used to specify how the FrameNode and its child nodes are positioned and sized within the layout.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
position	Position	Yes	Position information used in layout.

Example

setMeasuredSize¹²⁺

setMeasuredSize(size: Size): void

Sets the measured size of this FrameNode. The default unit is PX. If the configured width or height values are negative, they are automatically set to 0.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
size	Size	Yes	Measured size of the FrameNode.

Example

setLayoutPosition¹²⁺

setLayoutPosition(position: Position): void

Sets the position of this FrameNode after layout. The default unit is PX.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
position	Position	Yes	Position of the FrameNode after layout.

Example

measure¹²⁺

measure(constraint: LayoutConstraint): void

Measures this FrameNode and calculates its size based on the layout constraints of the parent container. If the measurement method is overridden, the overridden method is called. It is recommended that this API be called in onMeasure.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
constraint	LayoutConstraint	Yes	Parent container layout constraints used for measurement.

Example

layout¹²⁺

layout(position: Position): void

Lays out this FrameNode, specifying the layout positions for the FrameNode and its child nodes. If the layout method is overridden, the overridden method is called. It is recommended that this API be called in onLayout.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
position	Position	Yes	Position information used in layout.

Example

setNeedsLayout¹²⁺

setNeedsLayout(): void

Marks this FrameNode as needing layout, so that it will be relaid out in the next frame.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

invalidate¹²⁺

invalidate(): void

Invalidates this FrameNode to trigger a re-rendering of the self-drawing content.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

addComponentContent¹²⁺

addComponentContent<T>(content: ComponentContent<T> | ReactiveComponentContent<T>): void

Adds component content. The current node must be modifiable, which means the return value of isModifiable must be true. If the node is not modifiable, an exception is thrown.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
content	ComponentContent<T> \| ReactiveComponentContent<T>²²⁺	Yes	Component content to display on the FrameNode.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The FrameNode is not modifiable.

import { NodeController, FrameNode, ComponentContent, typeNode } from '@kit.ArkUI';

@Builder
function buildText() {
  Column() {
    Text('hello')
      .width(50)
      .height(50)
      .backgroundColor(Color.Yellow)
  }
}

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute.width(300).height(300).backgroundColor(Color.Red)
    let col = typeNode.createNode(uiContext, "Column")
    col.initialize({ space: 10 })
    node.appendChild(col)
    let row4 = typeNode.createNode(uiContext, "Row")
    row4.attribute.width(200)
      .height(200)
      .borderWidth(1)
      .borderColor(Color.Black)
      .backgroundColor(Color.Green)
    // Create component content.
    let component = new ComponentContent<Object>(uiContext, wrapBuilder(buildText))
    if (row4.isModifiable()) {
      // Add the builderText created to row4.
      row4.addComponentContent(component)
      col.appendChild(row4)
    }
    return node
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Row() {
      NodeContainer(this.myNodeController);
    }
  }
}

disposeTree¹²⁺

disposeTree(): void

Traverses down the tree and recursively releases the subtree with this node as the root.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

import { FrameNode, NodeController, BuilderNode } from '@kit.ArkUI';

// Custom component with mounted event handling, serving as the entry point for the custom component tree.
@Component
struct TestComponent {
  private myNodeController: MyNodeController = new MyNodeController(wrapBuilder(buildComponent2));

  build() {
    Column() {
      Text('This is a BuilderNode.')
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
      NodeContainer(this.myNodeController)
    }
    .width('100%')
    .backgroundColor(Color.Gray)
  }

  aboutToAppear() {
    console.info('BuilderNode aboutToAppear');
  }

  aboutToDisappear() {
    console.info('BuilderNode aboutToDisappear');
  }
}

// Custom component with mounted event handling, serving as the child component of TestComponent1 and the parent component of TestComponent3 and TestComponent4.
@Component
struct TestComponent2 {
  private myNodeController: MyNodeController = new MyNodeController(wrapBuilder(buildComponent3));
  private myNodeController2: MyNodeController = new MyNodeController(wrapBuilder(buildComponent4));

  build() {
    Column() {
      Text('This is a BuilderNode 2.')
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
      NodeContainer(this.myNodeController)
      NodeContainer(this.myNodeController2)
    }
    .width('100%')
    .backgroundColor(Color.Gray)
  }

  aboutToAppear() {
    console.info('BuilderNode 2 aboutToAppear');
  }

  aboutToDisappear() {
    console.info('BuilderNode 2 aboutToDisappear');
  }
}

// Custom component with mounted event handling, serving as the child component of buildComponent2.
@Component
struct TestComponent3 {
  build() {
    Column() {
      Text('This is a BuilderNode 3.')
        .fontSize(16)
        .fontWeight(FontWeight.Bold)

    }
    .width('100%')
    .backgroundColor(Color.Gray)
  }

  aboutToAppear() {
    console.info('BuilderNode 3 aboutToAppear');
  }

  aboutToDisappear() {
    console.info('BuilderNode 3 aboutToDisappear');
  }
}

// Custom component with mounted event handling, serving as the child component of buildComponent2.
@Component
struct TestComponent4 {
  build() {
    Column() {
      Text('This is a BuilderNode 4.')
        .fontSize(16)
        .fontWeight(FontWeight.Bold)

    }
    .width('100%')
    .backgroundColor(Color.Gray)
  }

  aboutToAppear() {
    console.info('BuilderNode 4 aboutToAppear');
  }

  aboutToDisappear() {
    console.info('BuilderNode 4 aboutToDisappear');
  }
}

@Builder
function buildComponent() {
  TestComponent()
}

@Builder
function buildComponent2() {
  TestComponent2()
}

@Builder
function buildComponent3() {
  TestComponent3()
}

@Builder
function buildComponent4() {
  TestComponent4()
}

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  private rootNode: FrameNode | null = null;
  private builderNode: BuilderNode<[]> | null = null;
  private wrappedBuilder: WrappedBuilder<[]>;

  constructor(builder: WrappedBuilder<[]>) {
    super();
    this.wrappedBuilder = builder;
  }

  makeNode(uiContext: UIContext): FrameNode | null {
    this.builderNode = new BuilderNode(uiContext, { selfIdealSize: { width: 200, height: 100 } });
    this.builderNode.build(this.wrappedBuilder);

    return this.builderNode.getFrameNode();
  }

  dispose() {
    if (this.builderNode !== null) {
      // Traverse down the tree and recursively release the subtree with the current node as the root.
      this.builderNode.getFrameNode()?.disposeTree()
    }
  }

  removeBuilderNode() {
    const rootRenderNode = this.rootNode!.getRenderNode();
    if (rootRenderNode !== null && this.builderNode !== null && this.builderNode.getFrameNode() !== null) {
      rootRenderNode.removeChild(this.builderNode!.getFrameNode()!.getRenderNode());
    }
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController(wrapBuilder(buildComponent));

  build() {
    Column({ space: 4 }) {
      NodeContainer(this.myNodeController)
      Button('BuilderNode dispose')
        .onClick(() => {
          this.myNodeController.dispose();
        })
        .width('100%')
      Button('BuilderNode rebuild')
        .onClick(() => {
          this.myNodeController.rebuild();
        })
        .width('100%')
    }
  }
}

en-us_image_disposeTree

setCrossLanguageOptions¹⁵⁺

setCrossLanguageOptions(options: CrossLanguageOptions): void

Sets the cross-language access options for this FrameNode. For example, for nodes created using ArkTS, this API can set whether non-ArkTS languages are allowed to set the attributes of these nodes. Since API version 26.0.0, this API can set whether non-ArkTS languages are allowed to perform operations on the component tree. If the current FrameNode is not modifiable or does not support setting cross-language access options, an exception will be thrown.

NOTE

Currently, the cross-ArkTS language access option can only be configured for the following components: Scroll, Swiper, List, ListItem, ListItemGroup, WaterFlow, FlowItem, Grid, GridItem, TextInput, TextArea, Column, Row, Stack, Flex, RelativeContainer, Progress, LoadingProgress, Image, Button, CheckBox, Radio, Slider, Toggle, and TypedFrameNode of the XComponent type.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
options	CrossLanguageOptions	Yes	Cross-ArkTS language access options.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100022	The FrameNode cannot be set whether to support cross-language common attribute setting.

Example

getCrossLanguageOptions¹⁵⁺

getCrossLanguageOptions(): CrossLanguageOptions

Obtains the cross-language access options for this FrameNode. For example, for nodes created using ArkTS, this API can obtain whether non-ArkTS languages are allowed to set the properties of these nodes and perform operations on the cross-language component tree. Since API version 26.0.0, this API can obtain whether non-ArkTS languages are allowed to perform operations on the component tree.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
CrossLanguageOptions	Cross-ArkTS language access options.

Example

getInteractionEventBindingInfo¹⁹⁺

getInteractionEventBindingInfo(eventType: EventQueryType): InteractionEventBindingInfo | undefined

Obtains the event binding information for the target node. Returns undefined if the specified interaction event type is not bound to the component node.

Atomic service API: This API can be used in atomic services since API version 19.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
eventType	EventQueryType	Yes	Type of the interaction event to query.

Return value

Type	Description
InteractionEventBindingInfo \| undefined	Returns an InteractionEventBindingInfo object containing event binding details if the interaction event is bound to the current node; returns undefined otherwise.

Example

See Example of Setting and Deleting a Polymorphic Style State.

recycle¹⁸⁺

recycle(): void

Triggers child component recycling in global reuse scenarios and fully releases FrameNode backend resources for reuse. This ensures efficient resource reclamation and reuse.

Atomic service API: This API can be used in atomic services since API version 18.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

See Example of Reusing and Recycling Nodes.

reuse¹⁸⁺

reuse(): void

Triggers child component reuse in global reuse scenarios to recycle FrameNode backend resources and improve resource utilization. To ensure adequate resource availability, call this API after the recycle API has been executed.

Atomic service API: This API can be used in atomic services since API version 18.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

See Example of Reusing and Recycling Nodes.

addSupportedUIStates²⁰⁺

addSupportedUIStates(uiStates: number, statesChangeHandler: UIStatesChangeHandler, excludeInner?: boolean): void

Adds the polymorphic style states supported by the component.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
uiStates	number	Yes	UI states of the target node to be processed. Multiple states can be specified simultaneously using bitwise OR operations, for example, targetUIStates = UIState.PRESSED \| UIState.FOCUSED.
statesChangeHandler	UIStatesChangeHandler	Yes	Callback invoked when the state changes.
excludeInner	boolean	No	Whether to disable the default state style processing. Default value: false. true: Disable default state style processing. false: Enable default state style processing.

Example

removeSupportedUIStates²⁰⁺

removeSupportedUIStates(uiStates: number): void

Removes the state processing registration from the component.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
uiStates	number	Yes	UI states to be removed. Multiple states can be specified simultaneously using bitwise OR operations, for example, targetUIStates = UIState.PRESSED \| UIState.FOCUSED.

Example

See Example of Setting and Deleting a Polymorphic Style State.

createAnimation²⁰⁺

createAnimation(property: AnimationPropertyType, startValue: Optional<number[]>, endValue: number[], param: AnimateParam): boolean

Creates a property animation for the FrameNode.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
property	AnimationPropertyType	Yes	Animation property type.
startValue	Optional<number[]>	Yes	Animation start value. The value can be undefined or an array. If the value is undefined, the animation uses the last set value of the property on the node as the starting value. If the value is an array, the length must match the property type requirements: - AnimationPropertyType.ROTATION: [rotationX, rotationY, rotationZ] in degrees (°). - AnimationPropertyType.TRANSLATION: [translateX, translateY] in px. - AnimationPropertyType.SCALE: [scaleX, scaleY] (scale factors). - AnimationPropertyType.OPACITY: [opacity] (value range: [0, 1]). For the first animation of a property, startValue must be explicitly specified. For subsequent animations, it is recommended that you either omit startValue or set it to the previous animation's end value to avoid abrupt changes.
endValue	number[]	Yes	Animation end value. The value is an array. The array length must match the property type requirements: - AnimationPropertyType.ROTATION: [rotationX, rotationY, rotationZ] in degrees (°). - AnimationPropertyType.TRANSLATION: [translateX, translateY] in px. - AnimationPropertyType.SCALE: [scaleX, scaleY] (scale factors). - AnimationPropertyType.OPACITY: [opacity] (value range: [0, 1]).
param	AnimateParam	Yes	Animation parameters, including the duration, animation curve, and end callback.

Return value

Type

Description

boolean

Whether the animation is created successfully.
Returns true if the animation is created successfully. If an end callback is specified in the animation parameters, it will be invoked upon animation completion.
Returns false if the animation creation fails. The end callback will not be invoked even if specified.
Possible failure reasons:
Additional notes:
1. The node has been released (the dispose API has been called).
2. The node is a built-in component proxy (where isModifiable returns false).
3. There is an invalid property enumeration or length mismatch between the property type and startValue or endValue arrays.
4. No start value is available (startValue is undefined for the first animation of a property) or the start and end values are identical.

Example

See Example of Creating and Canceling an Animation.

cancelAnimations²⁰⁺

cancelAnimations(properties: AnimationPropertyType[]): boolean

Cancels all animations for specified properties on the FrameNode. This API executes synchronously in the node's owning thread and blocks until cancellation completes. Upon successful cancellation, the node's property values revert to their current display state at the time of cancellation.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
properties	AnimationPropertyType[]	Yes	Array of animation properties to cancel. You can simultaneously cancel the animations of multiple properties on the node.

Return value

Type

Description

boolean

Animation cancellation status.
true: successful.
false: failed.
The possible causes are as follows:
Additional notes:
1. The node has been released (the dispose API has been called).
2. The node is a built-in component proxy (where isModifiable returns false).
3. The property array contains invalid enumerated values.
4. System error. Example: system IPC communication error.
Additional notes:
1. This API returns true for properties without active animations, if there are no system errors.
2. Valid parameters with normal node returning false indicate a system exception. In this case, you can retry cancellation later or use createAnimation with a zero duration as an alternative.

Example

See Example of Creating and Canceling an Animation.

getNodePropertyValue²⁰⁺

getNodePropertyValue(property: AnimationPropertyType): number[]

Obtains the property value of the FrameNode.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
property	AnimationPropertyType	Yes	Animation property type.

Return value

Type

Description

number[]

Current property value from the render node. The array length corresponds to the property type.
The return value format varies by property:
- An empty array (length 0) is returned if the node has been disposed, the dispose API has been called, or the property enumeration is invalid.
- AnimationPropertyType.ROTATION: [rotationX, rotationY, rotationZ] in degrees (°).
- AnimationPropertyType.TRANSLATION: [translateX, translateY] in px.
- AnimationPropertyType.SCALE: [scaleX, scaleY] (scale factors).
- AnimationPropertyType.OPACITY: [opacity].
1. After animation cancellation, the node's property value is restored to the display value at the time of cancellation, which can be obtained using this API.
2. During animation playback, this API returns the final target value rather than real-time interpolated values.

Example

See Example of Creating and Canceling an Animation.

invalidateAttributes²¹⁺

invalidateAttributes(): void

Forces immediate node property updates in this frame.

By default, property modifications applied after the build phase are deferred until the next frame.

This API ensures rendering synchronization by triggering immediate property updates.

Atomic service API: This API can be used in atomic services since API version 21.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

Starting from API version 21, when dynamically switching between nodes using if/else statements, you can call invalidateAttributes during node creation to trigger immediate attribute updates, preventing visual flickering during component switching.

// index.ets
import { FrameNode, NodeController, typeNode, NodeContent } from '@kit.ArkUI';

// Implement a custom NodeAdapter controller by extending NodeController.
class MyNodeAdapterController extends NodeController {
  rootNode: FrameNode | null = null;
  imageUrl: string = "";

  constructor(imageUrl: string) {
    super();
    this.imageUrl = imageUrl;
  }

  makeNode(uiContext: UIContext): FrameNode | null {
    let imageNode = typeNode.createNode(uiContext, "Image");
    imageNode.initialize($r(this.imageUrl))
    imageNode.attribute.syncLoad(true).width(100).height(100);
    // Force immediate node updates within the current frame to prevent flickering.
    imageNode.invalidateAttributes();
    return imageNode;
  }
}

// Custom component with custom mount event handling that pre-loads sample images before mounting
@Component
struct NodeComponent3 {
  private rootSlot: NodeContent = new NodeContent();

  aboutToAppear(): void {
    const uiContext = this.getUIContext();
    let imageNode = typeNode.createNode(uiContext, "Image");
    imageNode.initialize($r('app.media.startIcon'))
    imageNode.attribute.syncLoad(true).width(100).height(100);
    imageNode.invalidateAttributes();
    this.rootSlot.addFrameNode(imageNode);
  }

  build() {
    ContentSlot(this.rootSlot)
  }
}

// Custom component with custom mount event handling that pre-loads sample images before mounting
@Component
struct NodeComponent4 {
  private rootSlot: NodeContent = new NodeContent();

  aboutToAppear(): void {
    const uiContext = this.getUIContext();
    let imageNode = typeNode.createNode(uiContext, "Image");
    imageNode.initialize($r('app.media.startIcon'))
    imageNode.attribute.syncLoad(true).width(100).height(100);
    imageNode.invalidateAttributes();
    this.rootSlot.addFrameNode(imageNode);
  }

  build() {
    ContentSlot(this.rootSlot)
  }
}

@Entry
@Component
struct ListNodeTest {
  @State flag: boolean = true;
  adapterController: MyNodeAdapterController = new MyNodeAdapterController('app.media.startIcon');

  build() {
    Column() {
      Text("ListNode Adapter");
      if (this.flag) {
        NodeComponent3()
      } else {
        NodeComponent4()
      }
      if (this.flag) {
        NodeContainer(this.adapterController)
          .width(300).height(300)
          .borderWidth(1).borderColor(Color.Black)
      } else {
        NodeContainer(this.adapterController)
          .width(300).height(300)
          .borderWidth(1).borderColor(Color.Black)
      }
      if (this.flag) {
        Image($r('app.media.startIcon')).width(100).height(100).syncLoad(true)
      } else {
        Image($r('app.media.startIcon')).width(100).height(100).syncLoad(true)
      }
      Button('change').onClick(() => {
        this.flag = !this.flag;
      })
    }
    .borderWidth(1)
    .width("100%")
  }
}

adoptChild²²⁺

adoptChild(child: FrameNode): void

Adopts the target node as an affiliated node. The adopted node must not have an existing parent. This API is not used to add a node as a child node. Instead, it only allows the node to receive lifecycle callbacks of the corresponding child node.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
child	FrameNode	Yes	Node to be adopted.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The current FrameNode is not modifiable.
100025	The parameter is invalid. Details about the invalid parameter and the reason are included in the error message. For example: "The parameter 'child' is invalid: it cannot be disposed."
100026	The current FrameNode has been disposed.

Example

See Example of Adopting a Node as an Affiliate.

removeAdoptedChild²²⁺

removeAdoptedChild(child: FrameNode): void

Removes a previously-adopted affiliated node.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
child	FrameNode	Yes	Node to remove.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100021	The current FrameNode is not modifiable.
100025	The parameter is invalid. Details about the invalid parameter and the reason are included in the error message. For example: "The parameter 'child' is invalid: it cannot be null."
100026	The current FrameNode has been disposed.

Example

See Example of Adopting a Node as an Affiliate.

convertPosition²²⁺

convertPosition(position: Position, targetNode: FrameNode): Position

Converts a coordinate point from this node's coordinate system to the target node's coordinate system.

Atomic service API: This API can be used in atomic services since API version 22.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
position	Position	Yes	Coordinates relative to the current node's coordinate system.
targetNode	FrameNode	Yes	Target node for coordinate transformation.

Return value

Type	Description
Position	Converted coordinates relative to the target node's local coordinate system.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100024	The current FrameNode and the target FrameNode do not have a common ancestor node.
100025	The parameter is invalid. Details about the invalid parameter and the reason are included in the error message. For example: "The parameter 'targetNode' is invalid: it cannot be disposed."

Example

@Entry
@Component
struct ConvertPositionTestOnly {
  private uiContext: UIContext = this.getUIContext();
  @State message: string = 'Hello World';
  @State nodeAOk: boolean = false;
  @State nodeBOK: boolean = false;

  build() {
    Column() {
      Text(this.message)
        .id('testNodeA')
        .fontSize($r('app.float.page_text_font_size'))
        .fontWeight(FontWeight.Bold)
        .onAppear(() => {
          this.nodeAOk = true
        })
      Column() {
        Text('testNodeB')
          .id('testNodeB')
          .fontSize($r('app.float.page_text_font_size'))
          .fontWeight(FontWeight.Bold)
          .onAppear(() => {
            this.nodeBOK = true
          })

      }

      Button('Run convertPosition Test')
        .onClick(() => {
          this.runBasicTest();
        })
        .margin(20)

    }
    .width('100%')
    .height('100%')
  }

  private runBasicTest() {
    if (!this.nodeAOk || !this.nodeBOK) {
      return
    }

    // Wait for UI rendering completion.
    if (!this.uiContext) {
      return
    }
    const nodeA = this.uiContext.getAttachedFrameNodeById('testNodeA');
    const nodeB = this.uiContext.getAttachedFrameNodeById('testNodeB');

    if (!nodeA || !nodeB) {
      console.info('Failed to obtain test nodes');
      return;
    }

    const testPoint: Position = { x: 10, y: 10 };
    const result: Position | undefined = nodeA.convertPosition({ x: 30, y: 10 }, nodeB); // Explicitly declare that the method may return undefined.
    if (result === undefined) {
      console.info("Coordinate conversion failed: undefined returned");
      return;
    }
    console.info(`Converted coordinates: (${result.x}, ${result.y})`);

  }
}

isInRenderState²³⁺

isInRenderState(): boolean

Checks whether this node is in render state. A node is considered to be in render state when its corresponding RenderNode is present in the render tree.

Atomic service API: This API can be used in atomic services since API version 23.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	Whether the node is in render state. true: The node is in render state. false: The node is not in render state.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  @State message: string = 'is on render tree';
  @State @Watch('change') isShow: boolean = true;
  data: Array<string> = ['hello1', 'hello2', 'hello3', 'hello4', 'hello5', 'hello6', 'hello7', 'hello8'];

  // Listen for state changes and log the render status.
  change() {
    let buttonNode = this.getUIContext().getFrameNodeById("testButton");
    if (buttonNode == null) {
      return;
    }
    let isOnRenderTree = buttonNode!.isInRenderState();
    if (isOnRenderTree) {
      hilog.info(1, 'frameNode', 'is on render tree');
    } else {
      hilog.info(1, 'frameNode', 'is not on render tree');
    }
  }

  build() {
    Column() {
      Button('change button visibility').onClick(() => {
        // Change the visibility status of the button.
        this.isShow = !this.isShow;
      })
        .margin({ top: 20 })
      Button('test button')
        .visibility(this.isShow ? Visibility.Visible : Visibility.Hidden)
        .margin(20).id('testButton')

      List() {
        ForEach(this.data, (item: string, index: number) => {
          ListItem() {
            Text(item).id(item)
          }.alignSelf(ItemAlign.Center).width('100%')
        })
      }
      .width('30%')
      .alignSelf(ItemAlign.Center)
      .height("10%")
      .onReachEnd(() => {
        let textNode8 = this.getUIContext().getFrameNodeById("hello8");
        if (textNode8 != null) {
          let isOnRenderTree = textNode8!.isInRenderState();
          hilog.info(1, 'frameNode', 'is hello8 on RenderTree: %{public}s', isOnRenderTree);
        }
        let textNode1 = this.getUIContext().getFrameNodeById("hello1");
        if (textNode1 != null) {
          let isOnRenderTree = textNode1!.isInRenderState();
          isOnRenderTree ? this.message = 'is on render tree' : 'is not on render tree'
          hilog.info(1, 'frameNode', 'is hello1 on RenderTree: %{public}s', isOnRenderTree);
        }
      })
    }
    .height('100%')
    .width('100%')
  }
}

isOnMainTree²³⁺

isOnMainTree(): boolean

Queries whether a node is mounted to the main node tree.

Atomic service API: This API can be used in atomic services since API version 23.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	Whether the node is mounted to the main node tree. The value true means that the node is mounted to the main node tree, and false means the opposite.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100026	The current FrameNode has been disposed.

Example

import { NodeController, FrameNode, UIContext, typeNode } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

const TEST_TAG: string = 'FrameNode '

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public frameNode: FrameNode | null = null;
  public childList: Array<FrameNode> = new Array<FrameNode>();
  private rootNode: FrameNode | null = null;
  private uiContext: UIContext | null = null;
  private childrenCount: number = 0;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    this.uiContext = uiContext;

    this.frameNode = new FrameNode(uiContext);
    this.frameNode.commonAttribute.backgroundColor(Color.Pink);
    this.frameNode.commonAttribute.size({ width: 100, height: 100 });
    this.addCommonEvent(this.frameNode)
    this.rootNode.appendChild(this.frameNode);
    this.childrenCount = this.childrenCount + 1;
    for (let i = 0; i < 10; i++) {
      let childNode = new FrameNode(uiContext);
      this.childList.push(childNode);
      this.frameNode.appendChild(childNode);
    }
    let stackNode = typeNode.createNode(uiContext, 'Stack');
    this.frameNode.appendChild(stackNode);
    return this.rootNode;
  }

  addCommonEvent(frameNode: FrameNode) {
    frameNode.commonEvent.setOnClick((event: ClickEvent) => {
      console.info(`Click FrameNode: ${JSON.stringify(event)}`)
    })
  }

  createFrameNode() {
    let frameNode = new FrameNode(this.uiContext!);
    frameNode.commonAttribute.backgroundColor(Color.Pink);
    frameNode.commonAttribute.size({ width: 100, height: 100 });
    frameNode.commonAttribute.position({ x: this.childrenCount * 120, y: 0 });

    return frameNode;
  }

  appendChild() {
    const childNode = this.createFrameNode();
    this.rootNode!.appendChild(childNode);
    this.childrenCount = this.childrenCount + 1;
  }

  insertChildAfter(index: number) {
    let insertNode = this.createFrameNode();
    let childNode = this.rootNode!.getChild(index);
    this.rootNode!.insertChildAfter(insertNode, childNode);
    this.childrenCount = this.childrenCount + 1;
  }

  removeChild(index: number) {
    let childNode = this.rootNode!.getChild(index);
    if (childNode == null) {
      console.info(`${TEST_TAG} getchild at index {${index}} : fail`);
      return;
    }
    this.rootNode!.removeChild(childNode);
    this.childrenCount = this.childrenCount - 1;
  }

  getChildNumber() {
    console.info(`${TEST_TAG} getChildNumber ${this.rootNode!.getChildrenCount()}`)
    console.info(`${TEST_TAG} children count is ${this.childrenCount}`);
  }

  clearChildren() {
    this.rootNode!.clearChildren();
  }

  searchFrameNode() {
    if (this.rootNode!.getFirstChild() === null) {
      console.info(`${TEST_TAG} the rootNode does not have child node.`)
    }
    if (this.rootNode!.getFirstChild() === this.frameNode) {
      console.info(`${TEST_TAG} getFirstChild result: success. The first child of the rootNode is equals to frameNode.`);
    } else {
      console.info(`${TEST_TAG} getFirstChild result: fail. The first child of the rootNode is not equals to frameNode.`);
    }
    if (this.frameNode!.getChild(5) === this.frameNode!.getChild(4)!.getNextSibling()) {
      console.info(`${TEST_TAG} getNextSibling result: success.`);
    } else {
      console.info(`${TEST_TAG} getNextSibling result: fail.`);
    }
    if (this.frameNode!.getChild(3) === this.frameNode!.getChild(4)!.getPreviousSibling()) {
      console.info(`${TEST_TAG} getPreviousSibling result: success.`);
    } else {
      console.info(`${TEST_TAG} getPreviousSibling result: fail.`);
    }
    if (this.rootNode!.getFirstChild() !== null && this.rootNode!.getFirstChild()!.getParent() === this.rootNode) {
      console.info(`${TEST_TAG} getParent result: success.`);
    } else {
      console.info(`${TEST_TAG} getParent result: fail.`);
    }
    if (this.rootNode!.getParent() !== undefined || this.rootNode!.getParent() !== null) {
      console.info(`${TEST_TAG} get ArkTsNode success.`)
      console.info(`${TEST_TAG} check rootNode whether is modifiable ${this.rootNode!.isModifiable()}`)
      console.info(`${TEST_TAG} check getParent whether is modifiable ${this.rootNode!.getParent()!.isModifiable()}`)
    } else {
      console.info(`${TEST_TAG} get ArkTsNode fail.`);
    }
  }

  moveFrameNode() {
    const currentNode = this.frameNode!.getChild(10);
    try {
      currentNode!.moveTo(this.rootNode, 0);
      if (this.rootNode!.getChild(0) === currentNode) {
        console.info(`${TEST_TAG} moveTo result: success.`);
      } else {
        console.info(`${TEST_TAG} moveTo result: fail.`);
      }
    } catch (err) {
      console.info(`${TEST_TAG} ${(err as BusinessError).code} : ${(err as BusinessError).message}`);
      console.info(`${TEST_TAG} moveTo result: fail.`);
    }
  }

  getPositionToWindow() {
    let positionToWindow = this.rootNode?.getPositionToWindow();
    console.info(`${TEST_TAG}${JSON.stringify(positionToWindow)}`);
  }

  getPositionToParent() {
    let positionToParent = this.rootNode?.getPositionToParent();
    console.info(`${TEST_TAG}${JSON.stringify(positionToParent)}`);
  }

  getPositionToScreen() {
    let positionToScreen = this.rootNode?.getPositionToScreen();
    console.info(`${TEST_TAG}${JSON.stringify(positionToScreen)}`);
  }

  getGlobalPositionOnDisplay() {
    let positionOnGlobalDisplay = this.rootNode?.getGlobalPositionOnDisplay();
    console.info(`${TEST_TAG}${JSON.stringify(positionOnGlobalDisplay)}`);
  }

  getPositionToWindowWithTransform() {
    let positionToWindowWithTransform = this.rootNode?.getPositionToWindowWithTransform();
    console.info(`${TEST_TAG}${JSON.stringify(positionToWindowWithTransform)}`);
  }

  getPositionToParentWithTransform() {
    let positionToParentWithTransform = this.rootNode?.getPositionToParentWithTransform();
    console.info(`${TEST_TAG}${JSON.stringify(positionToParentWithTransform)}`);
  }

  getPositionToScreenWithTransform() {
    let positionToScreenWithTransform = this.rootNode?.getPositionToScreenWithTransform();
    console.info(`${TEST_TAG}${JSON.stringify(positionToScreenWithTransform)}`);
  }

  getMeasuredSize() {
    let measuredSize = this.frameNode?.getMeasuredSize();
    console.info(`${TEST_TAG}${JSON.stringify(measuredSize)}`);
  }

  getLayoutPosition() {
    let layoutPosition = this.frameNode?.getLayoutPosition();
    console.info(`${TEST_TAG}${JSON.stringify(layoutPosition)}`);
  }

  getUserConfigBorderWidth() {
    let userConfigBorderWidth = this.frameNode?.getUserConfigBorderWidth();
    console.info(`${TEST_TAG}${JSON.stringify(userConfigBorderWidth)}`);
  }

  getUserConfigPadding() {
    let userConfigPadding = this.frameNode?.getUserConfigPadding();
    console.info(`${TEST_TAG}${JSON.stringify(userConfigPadding)}`);
  }

  getUserConfigMargin() {
    let userConfigMargin = this.frameNode?.getUserConfigMargin();
    console.info(`${TEST_TAG}${JSON.stringify(userConfigMargin)}`);
  }

  getUserConfigSize() {
    let userConfigSize = this.frameNode?.getUserConfigSize();
    console.info(`${TEST_TAG}${JSON.stringify(userConfigSize)}`);
  }

  getId() {
    let id = this.frameNode?.getId();
    console.info(`${TEST_TAG}${id}`);
  }

  getUniqueId() {
    let uniqueId = this.frameNode?.getUniqueId();
    console.info(`${TEST_TAG}${uniqueId}`);
  }

  getNodeType() {
    let nodeType = this.frameNode?.getNodeType();
    console.info(`${TEST_TAG}${nodeType}`);
  }

  getOpacity() {
    let opacity = this.frameNode?.getOpacity();
    console.info(`${TEST_TAG}${JSON.stringify(opacity)}`);
  }

  isVisible() {
    let visible = this.frameNode?.isVisible();
    console.info(`${TEST_TAG}${JSON.stringify(visible)}`);
  }

  isClipToFrame() {
    let clipToFrame = this.frameNode?.isClipToFrame();
    console.info(`${TEST_TAG}${JSON.stringify(clipToFrame)}`);
  }

  isAttached() {
    let attached = this.frameNode?.isAttached();
    console.info(`${TEST_TAG}${JSON.stringify(attached)}`);
  }

  isOnMainTree() {
    let attached = this.frameNode?.isOnMainTree();
    console.info(`${TEST_TAG}${JSON.stringify(attached)}`);
  }

  getInspectorInfo() {
    let inspectorInfo = this.frameNode?.getInspectorInfo();
    console.info(`${TEST_TAG}${JSON.stringify(inspectorInfo)}`);
  }

  setCrossLanguageOptions() {
    console.info(`${TEST_TAG} getCrossLanguageOptions ${JSON.stringify(this.frameNode?.getCrossLanguageOptions())}`);
    try {
      this.frameNode?.setCrossLanguageOptions({
        attributeSetting: true
      });
      console.info(`${TEST_TAG} setCrossLanguageOptions success.`);
    } catch (err) {
      console.error(`${TEST_TAG} ${(err as BusinessError).code} : ${(err as BusinessError).message}`);
      console.error(`${TEST_TAG} setCrossLanguageOptions fail.`);
    }
    console.info(`${TEST_TAG} getCrossLanguageOptions ${JSON.stringify(this.frameNode?.getCrossLanguageOptions())}`);
  }

  getInteractionEventBindingInfo() {
    let bindingInfo = this.frameNode?.getInteractionEventBindingInfo(EventQueryType.ON_CLICK);
    console.info(`${TEST_TAG}${bindingInfo?.baseEventRegistered}`);
    console.info(`${TEST_TAG}${bindingInfo?.nodeEventRegistered}`);
    console.info(`${TEST_TAG}${bindingInfo?.nativeEventRegistered}`);
    console.info(`${TEST_TAG}${bindingInfo?.builtInEventRegistered}`);
    console.info(`${TEST_TAG}${JSON.stringify(bindingInfo)}`);
  }

  throwError() {
    try {
      this.rootNode!.getParent()!.clearChildren();
    } catch (err) {
      console.error(`${TEST_TAG} ${(err as BusinessError).code} : ${(err as BusinessError).message}`);
    }
    try {
      this.rootNode!.getParent()!.appendChild(new FrameNode(this.uiContext));
    } catch (err) {
      console.error(`${TEST_TAG} ${(err as BusinessError).code} : ${(err as BusinessError).message}`);
    }
    try {
      this.rootNode!.getParent()!.removeChild(this.rootNode!.getParent()!.getChild(0));
    } catch (err) {
      console.error(`${TEST_TAG} ${(err as BusinessError).code} : ${(err as BusinessError).message}`);
    }
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  private scroller: Scroller = new Scroller();
  @State index: number = 0;

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Column() {
          Row() {
            Button('ADD')
              .onClick(() => {
                this.index++;
              })
            Button('DEC')
              .onClick(() => {
                this.index--;
              })
          }

          Text('Current index is ' + this.index)
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
        }

        Column() {
          Text('This is a NodeContainer.')
            .textAlign(TextAlign.Center)
            .borderRadius(10)
            .backgroundColor(0xFFFFFF)
            .width('100%')
            .fontSize(16)
          NodeContainer(this.myNodeController)
            .borderWidth(1)
            .width(300)
            .height(100)
        }

        Button('appendChild')
          .width(300)
          .onClick(() => {
            this.myNodeController.appendChild();
          })
        Button('insertChildAfter')
          .width(300)
          .onClick(() => {
            this.myNodeController.insertChildAfter(this.index);
          })
        Button('removeChild')
          .width(300)
          .onClick(() => {
            this.myNodeController.removeChild(this.index);
          })
        Button('clearChildren')
          .width(300)
          .onClick(() => {
            this.myNodeController.clearChildren();
          })
        Button('getChildNumber')
          .width(300)
          .onClick(() => {
            this.myNodeController.getChildNumber();
          })
        Button('searchFrameNode')
          .width(300)
          .onClick(() => {
            this.myNodeController.searchFrameNode();
          })
        Button('moveFrameNode')
          .width(300)
          .onClick(() => {
            this.myNodeController.moveFrameNode();
          })
        Button('getPositionToWindow')
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToWindow();
          })
        Button('getPositionToParent')
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToParent();
          })
        Button('getPositionToScreen')
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToScreen();
          })
        Button('getGlobalPositionOnDisplay')
          .width(300)
          .onClick(() => {
            this.myNodeController.getGlobalPositionOnDisplay();
          })
        Button('getPositionToParentWithTransform')
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToParentWithTransform();
          })
        Button('getPositionToWindowWithTransform')
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToWindowWithTransform();
          })
        Button('getPositionToScreenWithTransform')
          .width(300)
          .onClick(() => {
            this.myNodeController.getPositionToScreenWithTransform();
          })
        Button('getMeasuredSize')
          .width(300)
          .onClick(() => {
            this.myNodeController.getMeasuredSize();
          })
        Button('getLayoutPosition')
          .width(300)
          .onClick(() => {
            this.myNodeController.getLayoutPosition();
          })
        Button('getUserConfigBorderWidth')
          .width(300)
          .onClick(() => {
            this.myNodeController.getUserConfigBorderWidth();
          })
        Button('getUserConfigPadding')
          .width(300)
          .onClick(() => {
            this.myNodeController.getUserConfigPadding();
          })
        Button('getUserConfigMargin')
          .width(300)
          .onClick(() => {
            this.myNodeController.getUserConfigMargin();
          })
        Button('getUserConfigSize')
          .width(300)
          .onClick(() => {
            this.myNodeController.getUserConfigSize();
          })
        Button('getId')
          .width(300)
          .onClick(() => {
            this.myNodeController.getId();
          })
        Button('getUniqueId')
          .width(300)
          .onClick(() => {
            this.myNodeController.getUniqueId();
          })
        Button('getNodeType')
          .width(300)
          .onClick(() => {
            this.myNodeController.getNodeType();
          })
        Button('getOpacity')
          .width(300)
          .onClick(() => {
            this.myNodeController.getOpacity();
          })
        Button('isVisible')
          .width(300)
          .onClick(() => {
            this.myNodeController.isVisible();
          })
        Button('isClipToFrame')
          .width(300)
          .onClick(() => {
            this.myNodeController.isClipToFrame();
          })
        Button('isAttached')
          .width(300)
          .onClick(() => {
            this.myNodeController.isAttached();
          })
        Button('isOnMainTree')
          .width(300)
          .onClick(() => {
            this.myNodeController.isOnMainTree();
          })
        Button('getInspectorInfo')
          .width(300)
          .onClick(() => {
            this.myNodeController.getInspectorInfo();
          })
        Button('getCustomProperty')
          .width(300)
          .onClick(() => {
            const uiContext: UIContext = this.getUIContext();
            if (uiContext) {
              const node: FrameNode | null = uiContext.getFrameNodeById('Test_Button') || null;
              if (node) {
                for (let i = 1; i < 4; i++) {
                  const key = 'customProperty' + i;
                  const property = node.getCustomProperty(key);
                  console.info(`${TEST_TAG}${key}`, JSON.stringify(property));
                }
              }
            }
          })
          .id('Test_Button')
          .customProperty('customProperty1', {
            'number': 10,
            'string': 'this is a string',
            'bool': true,
            'object': {
              'name': 'name',
              'value': 100
            }
          })
          .customProperty('customProperty2', {})
          .customProperty('customProperty2', undefined)
        Button('setCrossLanguageOptions')
          .width(300)
          .onClick(() => {
            this.myNodeController.setCrossLanguageOptions();
          })
        Button('getInteractionEventBindingInfo')
          .width(300)
          .onClick(() => {
            this.myNodeController.getInteractionEventBindingInfo();
          })
        Button('throwError')
          .width(300)
          .onClick(() => {
            this.myNodeController.throwError();
          })
      }
      .width('100%')
    }
    .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
  }
}

convertPositionToWindow²³⁺

convertPositionToWindow(positionByLocal: Position): Position

Converts the coordinates of a point from the coordinate system of the current node to the coordinate system of the window where the current node is located.

Atomic service API: This API can be used in atomic services since API version 23.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
positionByLocal	Position	Yes	Coordinates relative to the current node's coordinate system.

Return value

Type	Description
Position	Converted coordinates in the coordinate system of the window where the current node is located.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100026	The current FrameNode has been disposed.
100028	The current FrameNode is not on the main tree.

Example

For details, see Example of Converting Between Local Coordinates and Window Coordinates.

convertPositionFromWindow²³⁺

convertPositionFromWindow(positionByWindow: Position): Position

Converts the coordinates of a point from the coordinate system of the window where the current node is located to the coordinate system of the current node.

Atomic service API: This API can be used in atomic services since API version 23.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
positionByWindow	Position	Yes	Relative coordinates in the coordinate system of the window where the current node is located.

Return value

Type	Description
Position	Converted coordinates in the coordinate system of the current node.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100026	The current FrameNode has been disposed.
100028	The current FrameNode is not on the main tree.

Example

For details, see Example of Converting Between Local Coordinates and Window Coordinates.

createFrameNodes

static createFrameNodes(uiContext: UIContext, count: number): FrameNode[]

Creates a specified number of FrameNodes in batches and returns a FrameNode array.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
uiContext	UIContext	Yes	UI context for node creation.
count	number	Yes	Number of nodes to be created. The value is an integer greater than 0. If the value is less than or equal to 0 or is not an integer, an empty array is returned.

Return value

Type	Description
FrameNode[]	Array of created FrameNodes.

Example

import { NodeController, FrameNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    // Create 20 FrameNodes and add them to the root node.
    const children: FrameNode[] = FrameNode.createFrameNodes(uiContext, 20);
    for (let i = 0; i < children.length; i++) {
      this.rootNode.appendChild(children[i]);
    }
    return this.rootNode;
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column() {
      NodeContainer(this.myNodeController)
        .borderWidth(1)
        .width(300)
        .height(300)
    }.width("100%")
  }
}

getFrameNodeById

getFrameNodeById(id: string): FrameNode | null

Searches for all child nodes layer by layer from the current node (which is used as the root node) and returns the first node that matches the specified ID. The search sequence is as follows: Search for direct child nodes first, then level-2 child nodes, and so on. The search stops as soon as a matching node is found.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
id	string	Yes	ID of the child node to be queried, which is the same as the component ID.

Return value

Type	Description
FrameNode \| null	First node that matches the specified ID, which is returned by searching for all child nodes layer by layer from the current node (which is used as the root node). If no child node of the current node matches the specified ID, a null is returned.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public rootNode: FrameNode | null = null;
  private id: string = 'text';

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    // Create a Column node.
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    this.rootNode.appendChild(col);

    // Create a Text component and add it to the Column node.
    let text = typeNode.createNode(uiContext, 'Text');
    text.initialize('Hello').id(this.id);
    col.appendChild(text);

    // Create another Text component with the same ID and add it to the Column node.
    let text1 = typeNode.createNode(uiContext, 'Text');
    text1.initialize('World').id(this.id);
    col.appendChild(text1);
    this.update();
    return this.rootNode;
  }

  update() {
    if (this.rootNode) {
      // Query and return the first component whose ID is text, and set the backgroundColor attribute.
      let node = this.rootNode.getFrameNodeById(this.id);
      node?.commonAttribute.backgroundColor('rgb(39,135,217)');
    }
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column() {
      NodeContainer(this.myNodeController)
        .borderWidth(1)
        .width(300)
        .height(300)
    }.width("100%")
  }
}

getFrameNodeByUniqueId

getFrameNodeByUniqueId(id: number): FrameNode | null

Searches for and returns the child node with the specified unique ID (which can be obtained using the getUniqueId API) under the current node (which is used as the root node).

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
id	number	Yes	Unique ID of the child node to be queried.

Return value

Type	Description
FrameNode \| null	Child node with the unique ID, which is found from the current node (which is used as the root node). If the child node with the unique ID cannot be found under the current node, a null is returned.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  public rootNode: FrameNode | null = null;
  private uniqueId: number = 0;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    // Create a Column node.
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    this.rootNode.appendChild(col);

    // Create a Text component and add it to the Column node.
    let text = typeNode.createNode(uiContext, 'Text');
    text.initialize('Hello');
    col.appendChild(text);

    // Create another Text component and add it to the Column node.
    let text1 = typeNode.createNode(uiContext, 'Text');
    text1.initialize('World');
    this.uniqueId = text1.getUniqueId();
    col.appendChild(text1);
    this.update();
    return this.rootNode;
  }

  update() {
    if (this.rootNode) {
      // Query and return the component with the unique ID, and set the backgroundColor attribute.
      let node = this.rootNode.getFrameNodeByUniqueId(this.uniqueId);
      node?.commonAttribute.backgroundColor('rgb(39,135,217)');
    }
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column() {
      NodeContainer(this.myNodeController)
        .borderWidth(1)
        .width(300)
        .height(300)
    }.width("100%")
  }
}

TypedFrameNode¹²⁺

Extends FrameNode to define a FrameNode with specific type constraints.

Properties

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Read-Only	Optional	Description
initialize	C	No	No	Construction parameters for creating a component, used to set or update the component's initial values.
attribute	T	Yes	No	Attribute configuration object for setting or updating common and specific attributes of the component.

NOTE

The commonAttribute API is only effective on CustomFrameNode. For TypedFrameNode, the behavior of commonAttribute is undefined. For setting universal attributes, it is recommended that you use the attribute API, such as node.attribute.backgroundColor(Color.Pink), rather than commonAttribute.

typeNode¹²⁺

Provides APIs for creating a specific type of FrameNode, which can be mounted through the basic API of the FrameNode and be displayed using a placeholder container.

When typeNode is used to create Text, Image, Select, or Toggle nodes, if the UI instance corresponding to the input UIContext is destroyed, this API returns an invalid FrameNode that cannot be properly mounted or displayed.

Example

See Example of Customizing a Specific Type of Node.

Text¹²⁺

type Text = TypedFrameNode<TextInterface, TextAttribute>

Represents a FrameNode of the Text type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<TextInterface, TextAttribute>

FrameNode of the Text type.
TextInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Text component.
TextAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Text component.
TextInterface indicates the API of the Text component, and TextAttribute indicates the attribute of the Text component.

createNode('Text')¹²⁺

createNode(context: UIContext, nodeType: 'Text'): Text

Creates a FrameNode of the Text type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Text'	Yes	Node type. Set to 'Text'.

Return value

Type	Description
Text	FrameNode of the Text type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Text node.
    let text = typeNode.createNode(uiContext, 'Text');
    text.initialize("Hello").fontColor(Color.Blue).fontSize(14);
    typeNode.getAttribute(text, 'Text')?.fontWeight(FontWeight.Bold);
    col.appendChild(text);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Text sample');
      NodeContainer(this.myNodeController);
    }
  }
}

getAttribute('Text')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Text'): TextAttribute | undefined

Obtains the attributes of a Text node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Text'	Yes	Node type. Set to 'Text'.

Return value

Type	Description
TextAttribute \| undefined	Attributes of the Text node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Text node.
    let text = typeNode.createNode(uiContext, 'Text');
    text.initialize("Hello");
    // Obtain the Text node attributes.
    typeNode.getAttribute(text, 'Text')?.fontColor(Color.Red)
    col.appendChild(text);
    // Create another text for comparison.
    let text2 = typeNode.createNode(uiContext, 'Text');
    text2.initialize("world");
    col.appendChild(text2);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Text sample');
      NodeContainer(this.myNodeController);
    }
  }
}

bindController('Text')²⁰⁺

bindController(node: FrameNode, controller: TextController, nodeType: 'Text'): void

Binds a TextController instance to a Text node. Cross-language access must be enabled for nodes not created via ArkTS; otherwise, an exception will be thrown. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node for controller binding.
controller	TextController	Yes	TextController instance to bind.
nodeType	'Text'	Yes	Node type. Set to 'Text'.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100023	Parameter error. Possible causes: 1. The component type of the node is incorrect. 2. The node is null or undefined. 3. The controller is null or undefined.
100021	The FrameNode is not modifiable.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  // Configure the TextController instance, which can be obtained from an external source.
  controller: TextController = new TextController()

  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Text node.
    let text = typeNode.createNode(uiContext, 'Text');
    text.initialize("Hello").fontColor(Color.Blue).fontSize(14);
    typeNode.getAttribute(text, 'Text')?.fontWeight(FontWeight.Bold)
    // Bind a TextController instance.
    typeNode.bindController(text, this.controller, 'Text');
    col.appendChild(text);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  @State line: number = 0
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Text bindController Sample')
      NodeContainer(this.myNodeController)
      Text(`Current line count: ${this.line}`)
      Button(`Obtain Line Count`)
        .onClick(() => {
          this.line = this.myNodeController.controller.getLayoutManager().getLineCount()
        })
    }
  }
}

Column¹²⁺

type Column = TypedFrameNode<ColumnInterface, ColumnAttribute>

Represents a FrameNode of the Column type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ColumnInterface, ColumnAttribute>

FrameNode of the Column type.
ColumnInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Column component.
ColumnAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Column component.
ColumnInterface indicates the API of the Column component, and ColumnAttribute indicates the attribute of the Column component.

createNode('Column')¹²⁺

createNode(context: UIContext, nodeType: 'Column'): Column

Creates a FrameNode of the Column type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Column'	Yes	Node type. Set to 'Column'.

Return value

Type	Description
Column	FrameNode of the Column type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Column controller by extending NodeController.
class MyColumnController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a Column node.
    let col = typeNode.createNode(uiContext, 'Column')
    col.initialize({ space: 5 })
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(col)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myColumnController: MyColumnController = new MyColumnController();

  build() {
    Column({ space: 5 }) {
      Text('ColumnSample')
      NodeContainer(this.myColumnController);
    }.width('100%')
  }
}

getAttribute('Column')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Column'): ColumnAttribute | undefined

Obtains the attributes of a Column node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Column'	Yes	Node type. Set to 'Column'.

Return value

Type	Description
ColumnAttribute \| undefined	Attributes of the Column node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Column node.
    let col1 = typeNode.createNode(uiContext, 'Column');
    col1.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    // Obtain the attributes of the Column node.
    typeNode.getAttribute(col1, 'Column')?.backgroundColor(Color.Blue).width("100%")
    col.appendChild(col1);
    // Create another Column node for comparison.
    let col2 = typeNode.createNode(uiContext, 'Column');
    col2.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    col.appendChild(col2);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Column sample');
      NodeContainer(this.myNodeController);
    }
  }
}

Row¹²⁺

type Row = TypedFrameNode<RowInterface, RowAttribute>

Represents a FrameNode of the Row type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<RowInterface, RowAttribute>

FrameNode of the Row type.
RowInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Row component.
RowAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Row component.
RowInterface indicates the API of the Row component, and RowAttribute indicates the attribute of the Row component.

createNode('Row')¹²⁺

createNode(context: UIContext, nodeType: 'Row'): Row

Creates a FrameNode of the Row type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Row'	Yes	Node type. Set to 'Row'.

Return value

Type	Description
Row	FrameNode of the Row type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Row controller by extending NodeController.
class MyRowController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a row.
    let row = typeNode.createNode(uiContext, 'Row')
    row.initialize({ space: 5 })
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(row)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myRowController: MyRowController = new MyRowController();

  build() {
    Column({ space: 5 }) {
      Text('RowSample')
      NodeContainer(this.myRowController);
    }.width('100%')
  }
}

getAttribute('Row')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Row'): RowAttribute | undefined

Obtains the attributes of a Row node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Row'	Yes	Node type. Set to 'Row'.

Return value

Type	Description
RowAttribute \| undefined	Attributes of the Row node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Row node.
    let row1 = typeNode.createNode(uiContext, 'Row');
    row1.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    // Obtain the attributes of the Row node.
    typeNode.getAttribute(row1, 'Row')?.backgroundColor(Color.Blue).width("100%")
    col.appendChild(row1);
    // Create another Row node for comparison.
    let row2 = typeNode.createNode(uiContext, 'Row');
    row2.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    col.appendChild(row2);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Row sample');
      NodeContainer(this.myNodeController);
    }
  }
}

Stack¹²⁺

type Stack = TypedFrameNode<StackInterface, StackAttribute>

Represents a FrameNode of the Stack type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<StackInterface, StackAttribute>

FrameNode of the Stack type.
StackInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Stack component.
StackAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Stack component.
StackInterface indicates the API of the Stack component, and StackAttribute indicates the attribute of the Stack component.

createNode('Stack')¹²⁺

createNode(context: UIContext, nodeType: 'Stack'): Stack

Creates a FrameNode of the Stack type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Stack'	Yes	Node type. Set to 'Stack'.

Return value

Type	Description
Stack	FrameNode of the Stack type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Stack controller by extending NodeController.
class MyStackController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a Stack node.
    let stack = typeNode.createNode(uiContext, 'Stack')
    stack.initialize({ alignContent: Alignment.Top })
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(stack)
    let text = typeNode.createNode(uiContext, 'Text')
    text.initialize("This is Text")
    // Add a Text node to the Stack node.
    stack.appendChild(text)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myStackController: MyStackController = new MyStackController();

  build() {
    Column({ space: 5 }) {
      Text('StackSample')
      NodeContainer(this.myStackController);
    }.width('100%')
  }
}

getAttribute('Stack')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Stack'): StackAttribute | undefined

Obtains the attributes of a Stack node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Stack'	Yes	Node type. Set to 'Stack'.

Return value

Type	Description
StackAttribute \| undefined	Attributes of the Stack node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Stack node.
    let stack1 = typeNode.createNode(uiContext, 'Stack');
    stack1.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    // Obtain the Stack attributes.
    typeNode.getAttribute(stack1, 'Stack')?.backgroundColor(Color.Blue).width("100%")
    col.appendChild(stack1);
    // Create another Stack node for comparison.
    let stack2 = typeNode.createNode(uiContext, 'Stack');
    stack2.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    col.appendChild(stack2);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Row sample');
      NodeContainer(this.myNodeController);
    }
  }
}

GridRow¹²⁺

type GridRow = TypedFrameNode<GridRowInterface, GridRowAttribute>

Represents a FrameNode of the GridRow type. This type of node only allows child components of the GridCol type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<GridRowInterface, GridRowAttribute>

FrameNode of the GridRow type.
GridRowInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the GridRow component.
GridRowAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the GridRow component.
GridRowInterface indicates the API of the GridRow component, and GridRowAttribute indicates the attribute of the GridRow component.

createNode('GridRow')¹²⁺

createNode(context: UIContext, nodeType: 'GridRow'): GridRow

Creates a FrameNode of the GridRow type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'GridRow'	Yes	Node type. Set to 'GridRow'.

Return value

Type	Description
GridRow	FrameNode of the GridRow type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom GridRow controller by extending NodeController.
class MyGridRowController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a GridRow.
    let gridRow = typeNode.createNode(uiContext, 'GridRow')
    gridRow.initialize({ columns: 12 })
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(gridRow)
    // Create a GridCol node.
    let gridCol = typeNode.createNode(uiContext, 'GridCol')
    gridCol.initialize({ span: 2, offset: 4 })
      .height("100%")
      .backgroundColor(Color.Red)
    // Add gridCol to gridRow.
    gridRow.appendChild(gridCol)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myGridRowController: MyGridRowController = new MyGridRowController();

  build() {
    Column({ space: 5 }) {
      Text('GridRowSample')
      NodeContainer(this.myGridRowController);
    }.width('100%')
  }
}

GridCol¹²⁺

type GridCol = TypedFrameNode<GridColInterface, GridColAttribute>

Represents a FrameNode of the GridCol type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<GridColInterface, GridColAttribute>

FrameNode of the GridCol type.
GridColInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the GridCol component.
GridColAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the GridCol component.
GridColInterface indicates the API of the GridCol component, and GridColAttribute indicates the attribute of the GridCol component.

createNode('GridCol')¹²⁺

createNode(context: UIContext, nodeType: 'GridCol'): GridCol

Creates a FrameNode of the GridCol type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'GridCol'	Yes	Node type. Set to 'GridCol'.

Return value

Type	Description
GridCol	FrameNode of the GridCol type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom GridRow controller by extending NodeController.
class MyGridRowController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a GridRow.
    let gridRow = typeNode.createNode(uiContext, 'GridRow')
    gridRow.initialize({ columns: 12 })
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(gridRow)
    // Create a GridCol node.
    let gridCol = typeNode.createNode(uiContext, 'GridCol')
    gridCol.initialize({ span: 2, offset: 4 })
      .height("100%")
      .backgroundColor(Color.Red)
    // Add gridCol to gridRow.
    gridRow.appendChild(gridCol)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myGridRowController: MyGridRowController = new MyGridRowController();

  build() {
    Column({ space: 5 }) {
      Text('GridColSample')
      NodeContainer(this.myGridRowController);
    }.width('100%')
  }
}

Flex¹²⁺

type Flex = TypedFrameNode<FlexInterface, FlexAttribute>

Represents a FrameNode of the Flex type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<FlexInterface, FlexAttribute>

FrameNode of the Flex type.
FlexInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Flex component.
FlexAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Flex component.
FlexInterface indicates the API of the Flex component, and FlexAttribute indicates the attribute of the Flex component.

createNode('Flex')¹²⁺

createNode(context: UIContext, nodeType: 'Flex'): Flex

Creates a FrameNode of the Flex type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Flex'	Yes	Node type. Set to 'Flex'.

Return value

Type	Description
Flex	FrameNode of the Flex type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Flex controller by extending NodeController.
class MyFlexController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a Flex.
    let flex = typeNode.createNode(uiContext, 'Flex')
    flex.initialize()
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(flex)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myFlexController: MyFlexController = new MyFlexController();

  build() {
    Column({ space: 5 }) {
      Text('FlexSample')
      NodeContainer(this.myFlexController);
    }.width('100%')
  }
}

getAttribute('Flex')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Flex'): FlexAttribute | undefined

Obtains the Flex node attributes. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Flex'	Yes	Flex node type.

Return value

Type	Description
FlexAttribute \| undefined	Flex node type. If the operation fails, undefined is returned.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Flex.
    let flex1 = typeNode.createNode(uiContext, 'Flex');
    flex1.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    // Obtain the Flex attributes.
    typeNode.getAttribute(flex1, 'Flex')?.backgroundColor(Color.Blue).width("100%")
    col.appendChild(flex1);
    // Create another Flex node for comparison.
    let flex2 = typeNode.createNode(uiContext, 'Flex');
    flex2.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    col.appendChild(flex2);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Flex sample');
      NodeContainer(this.myNodeController);
    }
  }
}

Swiper¹²⁺

type Swiper = TypedFrameNode<SwiperInterface, SwiperAttribute>

Represents a FrameNode of the Swiper type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<SwiperInterface, SwiperAttribute>

FrameNode of the Swiper type.
SwiperInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Swiper component.
SwiperAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Swiper component.
SwiperInterface indicates the API of the Swiper component, and SwiperAttribute indicates the attribute of the Swiper component.

createNode('Swiper')¹²⁺

createNode(context: UIContext, nodeType: 'Swiper'): Swiper

Creates a FrameNode of the Swiper type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Swiper'	Yes	Node type. Set to 'Swiper'.

Return value

Type	Description
Swiper	FrameNode of the Swiper type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom Swiper controller by extending NodeController.
class MySwiperController extends NodeController {
  swiperController: SwiperController = new SwiperController()

  makeNode(uiContext: UIContext): FrameNode | null {
    // Create a Swiper node.
    let swiperNode = typeNode.createNode(uiContext, 'Swiper')

    // Create a Text node.
    let text0 = typeNode.createNode(uiContext, 'Text')
    text0.initialize("0")
      .width('100%')
      .height('100%')
      .textAlign(TextAlign.Center)
    // Add text0 to the Swiper.
    swiperNode.appendChild(text0)
    // Create another Text node for switching.
    let text1 = typeNode.createNode(uiContext, 'Text')
    text1.initialize("1")
      .width('100%')
      .height('100%')
      .textAlign(TextAlign.Center)
    // Add text1 to the swiper.
    swiperNode.appendChild(text1)
    swiperNode.commonAttribute.width('100%')
      .height('20%')
      .backgroundColor(0xAFEEEE)
    // Bind the swiper to the controller.
    typeNode.bindController(swiperNode, this.swiperController, 'Swiper')
    typeNode.getAttribute(swiperNode, 'Swiper')?.loop(false)
    return swiperNode;

  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private mySwiperController: MySwiperController = new MySwiperController();

  build() {
    Column({ space: 5 }) {
      Text('SwiperSample')
      NodeContainer(this.mySwiperController);
    }.width('100%')
  }
}

getAttribute('Swiper')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Swiper'): SwiperAttribute | undefined

Obtains the attributes of a Swiper node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Swiper'	Yes	Node type. Set to 'Swiper'.

Return value

Type	Description
SwiperAttribute \| undefined	Properties of the Swiper node, or undefined if they fail to be obtained.

Example

See the example for createNode('Swiper')¹²⁺.

bindController('Swiper')²⁰⁺

bindController(node: FrameNode, controller: SwiperController, nodeType: 'Swiper'): void

Binds a SwiperController instance to the Swiper node. Cross-language access must be enabled for nodes not created via ArkTS; otherwise, an exception will be thrown. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node for controller binding.
controller	SwiperController	Yes	SwiperController instance.
nodeType	'Swiper'	Yes	Node type. Set to 'Swiper'.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100023	Parameter error. Possible causes: 1. The component type of the node is incorrect. 2. The node is null or undefined. 3. The controller is null or undefined.
100021	The FrameNode is not modifiable.

Example

See the example for createNode('Swiper')¹²⁺.

Progress¹²⁺

type Progress = TypedFrameNode<ProgressInterface, ProgressAttribute>

Represents a FrameNode of the Progress type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ProgressInterface, ProgressAttribute>

FrameNode of the Progress type.
ProgressInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Progress component.
ProgressAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Progress component.
ProgressInterface indicates the API of the Progress component, and ProgressAttribute indicates the attribute of the Progress component.

createNode('Progress')¹²⁺

createNode(context: UIContext, nodeType: 'Progress'): Progress

Creates a FrameNode of the Progress type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Progress'	Yes	Node type. Set to 'Progress'.

Return value

Type	Description
Progress	FrameNode of the Progress type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom Progress controller by extending NodeController.
class MyProgressNodeController extends NodeController {
  public uiContext: UIContext | null = null;
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    this.rootNode = new FrameNode(uiContext);
    // Create a Progress node.
    let node = typeNode.createNode(uiContext, 'Progress');
    node.initialize({
      value: 15,
      total: 200,
      type: ProgressType.ScaleRing
    }).width(100)
      .height(100)
    this!.rootNode!.appendChild(node);
    return this.rootNode;
  }
}

@Entry
@Component
struct Sample {
  build() {
    Column({ space: 10 }) {
      NodeContainer(new MyProgressNodeController()).margin(5)
    }.width('100%').height('100%')

  }
}

getAttribute('Progress')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Progress'): ProgressAttribute | undefined

Obtains the attributes of a Progress node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Progress'	Yes	Node type. Set to 'Progress'.

Return value

Type	Description
ProgressAttribute \| undefined	Properties of the Progress node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom Progress controller by extending NodeController.
class MyProgressNodeController extends NodeController {
  public uiContext: UIContext | null = null;
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    this.rootNode = new FrameNode(uiContext);
    let node = typeNode.createNode(uiContext, 'Progress');
    node.initialize({
      value: 15,
      total: 200,
      type: ProgressType.ScaleRing
    }).width(100)
      .height(100)
    // Obtain the attributes of the Progress node.
    typeNode.getAttribute(node, 'Progress');
    this!.rootNode!.appendChild(node);
    return this.rootNode;
  }
}

@Entry
@Component
struct Sample {
  build() {
    Column({ space: 10 }) {
      NodeContainer(new MyProgressNodeController()).margin(5)
    }.width('100%').height('100%')

  }
}

Scroll¹²⁺

type Scroll = TypedFrameNode<ScrollInterface, ScrollAttribute>

Represents a FrameNode of the Scroll type. This type of node allows only one child component to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ScrollInterface, ScrollAttribute>

FrameNode of the Scroll type.
ScrollInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Scroll component.
ScrollAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Scroll component.
ScrollInterface indicates the API of the Scroll component, and ScrollAttribute indicates the attribute of the Scroll component.

createNode('Scroll')¹²⁺

createNode(context: UIContext, nodeType: 'Scroll'): Scroll

Creates a FrameNode of the Scroll type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Scroll'	Yes	Node type. Set to 'Scroll'.

Return value

Type	Description
Scroll	FrameNode of the Scroll type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Scroll controller by extending NodeController.
class MyScrollController extends NodeController {
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    // Create a Scroll node.
    let scroller: Scroller = new Scroller();
    // Create a Scroll node and set its properties.
    let scrollNode = typeNode.createNode(uiContext, 'Scroll');
    scrollNode.initialize(scroller).size({ width: '100%', height: 500 });
    typeNode.getAttribute(scrollNode, "Scroll")?.friction(0.6);

    let colNode = typeNode.createNode(uiContext, 'Column');
    // Add a Column node to Scroll.
    scrollNode.appendChild(colNode);

    for (let i = 0; i < 10; i++) {
      let text = typeNode.createNode(uiContext, 'Text');
      text.initialize('item' + i)
        .size({ width: '90%', height: 100 })
        .textAlign(TextAlign.Center)
        .backgroundColor(0xF9CF93);
      colNode.appendChild(text);
    }

    this!.rootNode!.appendChild(scrollNode);
    return this.rootNode;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myScrollController: MyScrollController = new MyScrollController();

  build() {
    Column({ space: 5 }) {
      Text('ScrollSample')
      NodeContainer(this.myScrollController)

    }.width('100%')
  }
}

getAttribute('Scroll')¹⁵⁺

getAttribute(node: FrameNode, nodeType: 'Scroll'): ScrollAttribute | undefined

Obtains the attributes of a Scroll node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Scroll'	Yes	Node type. Set to 'Scroll'.

Return value

Type	Description
ScrollAttribute \| undefined	Attributes of the Scroll node, or undefined if they fail to be obtained.

Example

See the example for createNode('Scroll').

getEvent('Scroll')¹⁹⁺

getEvent(node: FrameNode, nodeType: 'Scroll'): UIScrollEvent | undefined

Obtains the UIScrollEvent object associated with the Scroll node for configuring scroll events. The scroll events configured through this API coexist with declarative events without overriding them. If both event callbacks are registered, the declaratively defined event callback takes precedence.

Atomic service API: This API can be used in atomic services since API version 19.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node.
nodeType	'Scroll'	Yes	Scroll node type for scroll event configuration.

Return value

Type	Description
UIScrollEvent \| undefined	UIScrollEvent object for the Scroll node, or undefined if it fails to be obtained.

Example

bindController('Scroll')¹⁵⁺

bindController(node: FrameNode, controller: Scroller, nodeType: 'Scroll'): void

Binds the Scroller to the Scroll node. Cross-language access must be enabled for nodes not created via ArkTS; otherwise, an exception will be thrown. This API supports declaratively created nodes since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 15.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node to which the scroll controller is bound.
controller	Scroller	Yes	Scroll controller.
nodeType	'Scroll'	Yes	Node type, which is Scroll in this API.

Error codes

For details about the error codes, see Custom Node Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. the type of the node is error. 2. the node is null or undefined.
100021	The FrameNode is not modifiable.

Example

typeNode.bindController(node, scroller, 'Scroll');

RelativeContainer¹²⁺

type RelativeContainer = TypedFrameNode<RelativeContainerInterface, RelativeContainerAttribute>

Represents a FrameNode of the RelativeContainer type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<RelativeContainerInterface, RelativeContainerAttribute>

FrameNode of the RelativeContainer type.
RelativeContainerInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the RelativeContainer component.
RelativeContainerAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the RelativeContainer component.
RelativeContainerInterface indicates the API of the RelativeContainer component, and RelativeContainerAttribute indicates the attribute of the RelativeContainer component.

createNode('RelativeContainer')¹²⁺

createNode(context: UIContext, nodeType: 'RelativeContainer'): RelativeContainer

Creates a FrameNode of the RelativeContainer type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'RelativeContainer'	Yes	Node type. Set to 'RelativeContainer'.

Return value

Type	Description
RelativeContainer	FrameNode of the RelativeContainer type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom RelativeContainer controller by extending NodeController.
class MyRelativeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    // Create a RelativeContainer node.
    let relative = typeNode.createNode(uiContext, 'RelativeContainer')
    relative.initialize()
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Gray)
    node.appendChild(relative)
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myRelativeController: MyRelativeController = new MyRelativeController();

  build() {
    Column({ space: 5 }) {
      Text('RelativeContainerSample')
      NodeContainer(this.myRelativeController);
    }.width('100%')
  }
}

getAttribute('RelativeContainer')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'RelativeContainer'): RelativeContainerAttribute | undefined

Obtains the attributes of a RelativeContainer node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'RelativeContainer'	Yes	Node type. Set to 'RelativeContainer'.

Return value

Type	Description
RelativeContainerAttribute \| undefined	Attributes of the RelativeContainer node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a RelativeContainer node.
    let relative1 = typeNode.createNode(uiContext, 'RelativeContainer');
    relative1.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    // Obtain the attributes of the RelativeContainer node.
    typeNode.getAttribute(relative1, 'RelativeContainer')?.backgroundColor(Color.Blue).width("100%")
    col.appendChild(relative1);
    // Create another RelativeContainer node for comparison.
    let relative2 = typeNode.createNode(uiContext, 'RelativeContainer');
    relative2.initialize().width("50%").height("20%").backgroundColor(Color.Pink);
    col.appendChild(relative2);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('RelativeContainer sample');
      NodeContainer(this.myNodeController);
    }
  }
}

Divider¹²⁺

type Divider = TypedFrameNode<DividerInterface, DividerAttribute>

Represents a FrameNode of the Divider type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<DividerInterface, DividerAttribute>

FrameNode of the Divider type.
DividerInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the RelativeContainer component.
DividerAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Divider component.
DividerInterface indicates the API of the Divider component, and DividerAttribute indicates the attribute of the Divider component.

createNode('Divider')¹²⁺

createNode(context: UIContext, nodeType: 'Divider'): Divider

Creates a FrameNode of the Divider type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Divider'	Yes	Node type. Set to 'Divider'.

Return value

Type	Description
Divider	FrameNode of the Divider type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Divider controller by extending NodeController.
class MyDividerController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    let col = typeNode.createNode(uiContext, 'Column')
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col)
    // Create a Divider node.
    let divider = typeNode.createNode(uiContext, 'Divider')
    divider.initialize()
      .strokeWidth(1)
    // Add the Divider node to col.
    col.appendChild(divider)

    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myDividerController: MyDividerController = new MyDividerController();

  build() {
    Column({ space: 5 }) {
      Text('DividerSample')
      NodeContainer(this.myDividerController);

    }.width('100%')
  }
}

LoadingProgress¹²⁺

type LoadingProgress = TypedFrameNode<LoadingProgressInterface, LoadingProgressAttribute>

Represents a FrameNode of the LoadingProgress type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<LoadingProgressInterface, LoadingProgressAttribute>

FrameNode of the LoadingProgress type.
LoadingProgressInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the LoadingProgress component.
LoadingProgressAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the LoadingProgress component.
LoadingProgressInterface indicates the API of the LoadingProgress component, and LoadingProgressAttribute indicates the attribute of the LoadingProgress component.

createNode('LoadingProgress')¹²⁺

createNode(context: UIContext, nodeType: 'LoadingProgress'): LoadingProgress

Creates a FrameNode of the LoadingProgress type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'LoadingProgress'	Yes	Node type. Set to 'LoadingProgress'.

Return value

Type	Description
LoadingProgress	FrameNode of the LoadingProgress type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom LoadingProgress controller by extending NodeController.
class MyLoadingProgressNodeController extends NodeController {
  public uiContext: UIContext | null = null;
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    this.rootNode = new FrameNode(uiContext);
    // Create LoadingProgress node.
    let node = typeNode.createNode(uiContext, 'LoadingProgress');
    node.initialize()
      .width(100)
      .height(100)
      .color(Color.Red)
      .enableLoading(true)
    this!.rootNode!.appendChild(node);
    return this.rootNode;
  }
}

@Entry
@Component
struct Sample {
  build() {
    Column({ space: 10 }) {
      NodeContainer(new MyLoadingProgressNodeController()).margin(5)
    }.width('100%').height('100%')
  }
}

getAttribute('LoadingProgress')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'LoadingProgress'): LoadingProgressAttribute | undefined

Obtains the attributes of a LoadingProgress node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'LoadingProgress'	Yes	Node type. Set to 'LoadingProgress'.

Return value

Type	Description
LoadingProgressAttribute \| undefined	Properties of the LoadingProgress node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom LoadingProgress controller by extending NodeController.
class MyLoadingProgressNodeController extends NodeController {
  public uiContext: UIContext | null = null;
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    this.rootNode = new FrameNode(uiContext);
    let node = typeNode.createNode(uiContext, 'LoadingProgress');
    node.initialize()
      .width(100)
      .height(100)
      .color(Color.Red)
      .enableLoading(true)
    // Obtain the attributes of the LoadingProgress node.
    typeNode.getAttribute(node, 'LoadingProgress');
    this!.rootNode!.appendChild(node);
    return this.rootNode;
  }
}

@Entry
@Component
struct Sample {
  build() {
    Column({ space: 10 }) {
      NodeContainer(new MyLoadingProgressNodeController()).margin(5)
    }.width('100%').height('100%')
  }
}

Search¹²⁺

type Search = TypedFrameNode<SearchInterface, SearchAttribute>

Represents a FrameNode of the Search type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<SearchInterface, SearchAttribute>

FrameNode of the Search type.
SearchInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Search component.
SearchAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Search component.
SearchInterface indicates the API of the Search component, and SearchAttribute indicates the attribute of the Search component.

createNode('Search')¹²⁺

createNode(context: UIContext, nodeType: 'Search'): Search

Creates a FrameNode of the Search type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Search'	Yes	Node type. Set to 'Search'.

Return value

Type	Description
Search	FrameNode of the Search type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a Search node.
    let search = typeNode.createNode(uiContext, 'Search');
    search.initialize({ value: "Search" })
      .searchButton('SEARCH')
      .textFont({ size: 14, weight: 400 })
    col.appendChild(search);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('Search sample');
      NodeContainer(this.myNodeController);
    }
  }
}

Blank¹²⁺

type Blank = TypedFrameNode<BlankInterface, BlankAttribute>

Represents a FrameNode of the Blank type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<BlankInterface, BlankAttribute>

FrameNode of the Blank type.
BlankInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Blank component.
BlankAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Blank component.
BlankInterface indicates the API of the Blank component, and BlankAttribute indicates the attribute of the Blank component.

createNode('Blank')¹²⁺

createNode(context: UIContext, nodeType: 'Blank'): Blank

Creates a FrameNode of the Blank type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Blank'	Yes	Node type. Set to 'Blank'.

Return value

Type	Description
Blank	FrameNode of the Blank type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Blank controller by extending NodeController.
class MyBlankController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    let col = typeNode.createNode(uiContext, 'Column')
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col)
    // Create a Blank node.
    let blank = typeNode.createNode(uiContext, 'Blank')
    blank.initialize()
      .width('50%')
      .height('50%')
      .backgroundColor(Color.Blue)
    col.appendChild(blank)

    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myBlankController: MyBlankController = new MyBlankController();

  build() {
    Column({ space: 5 }) {
      Text('BlankSample')
      NodeContainer(this.myBlankController);

    }.width('100%')
  }
}

Image¹²⁺

type Image = TypedFrameNode<ImageInterface, ImageAttribute>

Represents a FrameNode of the Image type. This type of node does not allow child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ImageInterface, ImageAttribute>

FrameNode of the Image type.
ImageInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Image component.
ImageAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Image component.
ImageInterface indicates the API of the Image component, and ImageAttribute indicates the attribute of the Image component.

createNode('Image')¹²⁺

createNode(context: UIContext, nodeType: 'Image'): Image

Creates a FrameNode of the Image type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Image'	Yes	Node type, which is Image in this API.

Return value

Type	Description
Image	FrameNode of the Image type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom Image controller by extending NodeController.
class MyImageController extends NodeController {
  public uiContext: UIContext | null = null;
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    this.rootNode = new FrameNode(uiContext);
    // Create an Image node.
    let imageNode = typeNode.createNode(uiContext, 'Image');
    imageNode
      // Replace $r('app.media.img') with the image resource file you use.
      .initialize($r('app.media.img'))
      .width(100)
      .height(100)
      .fillColor(Color.Red)
      .objectFit(ImageFit.Contain)
      .renderMode(ImageRenderMode.Template)
      .fitOriginalSize(true)
      .matchTextDirection(true)
      .objectRepeat(ImageRepeat.X)
      .autoResize(true)

    this!.rootNode!.appendChild(imageNode);
    return this.rootNode;

  }
}

@Entry
@Component
struct Sample {
  build() {
    Column({ space: 10 }) {
      NodeContainer(new MyImageController()).margin(5)
    }.width('100%').height('100%')

  }
}

getAttribute('Image')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Image'): ImageAttribute | undefined

Obtains the attributes of an Image node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Image'	Yes	Node type. Set to 'Image'.

Return value

Type	Description
ImageAttribute \| undefined	Properties of the Image node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom Image controller by extending NodeController.
class MyImageController extends NodeController {
  public uiContext: UIContext | null = null;
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.uiContext = uiContext;
    this.rootNode = new FrameNode(uiContext);
    let imageNode = typeNode.createNode(uiContext, 'Image');
    imageNode
      // Replace $r('app.media.img') with the image resource file you use.
      .initialize($r('app.media.img'))
      .width(100)
      .height(100)
      .fillColor(Color.Red)
      .objectFit(ImageFit.Contain)
      .renderMode(ImageRenderMode.Template)
      .fitOriginalSize(true)
      .matchTextDirection(true)
      .objectRepeat(ImageRepeat.X)
      .autoResize(true)
    // Obtain the attributes of the Image node.
    typeNode.getAttribute(imageNode, 'Image');
    this!.rootNode!.appendChild(imageNode);
    return this.rootNode;

  }
}

@Entry
@Component
struct Sample {
  build() {
    Column({ space: 10 }) {
      NodeContainer(new MyImageController()).margin(5)
    }.width('100%').height('100%')

  }
}

List¹²⁺

type List = TypedFrameNode<ListInterface, ListAttribute>

Represents a FrameNode of the List type. This type of node only allows child components of the ListItem and ListItemGroup types.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ListInterface, ListAttribute>

FrameNode of the List type.
ListInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the List component.
ListAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the List component.
ListInterface indicates the API of the List component, and ListAttribute indicates the attribute of the List component.

createNode('List')¹²⁺

createNode(context: UIContext, nodeType: 'List'): List

Creates a FrameNode of the List type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'List'	Yes	Node type, which is List in this API.

Return value

Type	Description
List	FrameNode of the List type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom List controller by extending NodeController.
class MyListController extends NodeController {
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    // Create a List node.
    this.rootNode = new FrameNode(uiContext);
    // Create a List node.
    let listNode = typeNode.createNode(uiContext, 'List');
    listNode.initialize({ space: 3 }).size({ width: '100%', height: '100%' });
    typeNode.getAttribute(listNode, "List")?.friction(0.6);

    // Create a ListItemGroup node in the List.
    let listItemGroupNode = typeNode.createNode(uiContext, 'ListItemGroup');
    listItemGroupNode.initialize({ space: 3 });
    listNode.appendChild(listItemGroupNode);

    // Add ListItem nodes to ListItemGroup.
    let listItemNode1 = typeNode.createNode(uiContext, 'ListItem');
    listItemNode1.initialize({ style: ListItemStyle.NONE }).height(100).borderWidth(1).backgroundColor('#FF00FF');
    let text1 = typeNode.createNode(uiContext, 'Text');
    text1.initialize('ListItem1');
    listItemNode1.appendChild(text1);
    listItemGroupNode.appendChild(listItemNode1);

    // Create a ListItem, add a Text to the ListItem, and add the ListItem to listItemGroup.
    let listItemNode2 = typeNode.createNode(uiContext, 'ListItem');
    listItemNode2.initialize({ style: ListItemStyle.CARD }).borderWidth(1).backgroundColor('#FF00FF');
    typeNode.getAttribute(listItemNode2, "ListItem")?.height(100);
    let text2 = typeNode.createNode(uiContext, 'Text');
    text2.initialize('ListItem2');
    listItemNode2.appendChild(text2);
    listItemGroupNode.appendChild(listItemNode2);

    this!.rootNode!.appendChild(listNode);
    return this.rootNode;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myListController: MyListController = new MyListController();

  build() {
    Column({ space: 5 }) {
      Text('ListSample')
      NodeContainer(this.myListController)

    }.width('100%')
  }
}

getEvent('List')¹⁹⁺

getEvent(node: FrameNode, nodeType: 'List'): UIListEvent | undefined

Obtains the UIListEvent object associated with the List node for configuring scroll events. The scroll events configured through this API coexist with declarative events without overriding them. If both event callbacks are registered, the declaratively defined event callback takes precedence.

Atomic service API: This API can be used in atomic services since API version 19.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node.
nodeType	'List'	Yes	List node type for scroll event configuration.

Return value

Type	Description
UIListEvent \| undefined	UIListEvent object for the List node, or undefined if it fails to be obtained.

Example

getAttribute('List')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'List'): ListAttribute | undefined

Obtains the attributes of a List node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'List'	Yes	Node type. Set to 'List'.

Return value

Type	Description
ListAttribute \| undefined	Attributes of the List node, or undefined if they fail to be obtained.

Example

See the example for createNode('List').

bindController('List')²⁰⁺

bindController(node: FrameNode, controller: Scroller, nodeType: 'List'): void

Binds a Scroller instance to the List node. Cross-language access must be enabled for nodes not created via ArkTS; otherwise, an exception will be thrown. This API supports declaratively created nodes since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node to which the scroll controller is bound.
controller	Scroller	Yes	Scroll controller.
nodeType	'List'	Yes	Node type. Set to 'List'.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100023	Parameter error. Possible causes: 1. The component type of the node is incorrect. 2. The node is null or undefined. 3. The controller is null or undefined.
100021	The FrameNode is not modifiable.

Example

typeNode.bindController(node, scroller, 'List');

ListItem¹²⁺

type ListItem = TypedFrameNode<ListItemInterface, ListItemAttribute>

Represents a FrameNode of the ListItem type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ListItemInterface, ListItemAttribute>

FrameNode of the ListItem type.
ListItemInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the ListItem component.
ListItemAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the ListItem component.
ListItemInterface indicates the API of the ListItem component, and ListItemAttribute indicates the attribute of the ListItem component.

createNode('ListItem')¹²⁺

createNode(context: UIContext, nodeType: 'ListItem'): ListItem

Creates a FrameNode of the ListItem type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'ListItem'	Yes	Node type. Set to 'ListItem'.

Return value

Type	Description
ListItem	FrameNode of the ListItem type.

Example

See the example for createNode('List').

getAttribute('ListItem')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'ListItem'): ListItemAttribute | undefined

Obtains the attributes of a ListItem node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'ListItem'	Yes	Node type. Set to 'ListItem'.

Return value

Type	Description
ListItemAttribute \| undefined	Attributes of the ListItem node, or undefined if they fail to be obtained.

Example

See the example for createNode('List').

TextInput¹²⁺

type TextInput = TypedFrameNode<TextInputInterface, TextInputAttribute>

Represents a FrameNode of the TextInput type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<TextInputInterface, TextInputAttribute>

FrameNode of the TextInput type.
TextInputInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the TextInput component.
TextInputAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the TextInput component.
TextInputInterface indicates the API of the TextInput component, and TextInputAttribute indicates the attribute of the TextInput component.

createNode('TextInput')¹²⁺

createNode(context: UIContext, nodeType: 'TextInput'): TextInput

Creates a FrameNode of the TextInput type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'TextInput'	Yes	Node type. Set to 'TextInput'.

Return value

Type	Description
TextInput	FrameNode of the TextInput type.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a TextInput.
    let textInput = typeNode.createNode(uiContext, 'TextInput');
    textInput.initialize({ text: "TextInput" });
    col.appendChild(textInput);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('TextInput sample')
      NodeContainer(this.myNodeController);
    }
  }
}

getAttribute('TextInput')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'TextInput'): TextInputAttribute | undefined

Obtains the attributes of a TextInput node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'TextInput'	Yes	Node type. Set to 'TextInput'.

Return value

Type	Description
TextInputAttribute \| undefined	Properties of the TextInput node, or undefined if they fail to be obtained.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create a TextInput.
    let textInput = typeNode.createNode(uiContext, 'TextInput');
    textInput.initialize({ placeholder: 'TextInput placeholderColor' });
    // Obtain the attributes of the TextInput node.
    typeNode.getAttribute(textInput, 'TextInput')?.placeholderColor(Color.Red);
    col.appendChild(textInput);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('TextInput getAttribute sample');
      NodeContainer(this.myNodeController);
    }
  }
}

bindController('TextInput')²⁰⁺

bindController(node: FrameNode, controller: TextInputController, nodeType: 'TextInput'): void

Binds the TextInputController to the TextInput node. Cross-language access must be enabled for nodes not created via ArkTS; otherwise, an exception will be thrown. This API supports declaratively created nodes since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node to which the input box controller is bound.
controller	TextInputController	Yes	Input box controller.
nodeType	'TextInput'	Yes	Node type. Set to 'TextInput'.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100023	Parameter error. Possible causes: 1. The component type of the node is incorrect. 2. The node is null or undefined. 3. The controller is null or undefined.
100021	The FrameNode is not modifiable.

Example

import { FrameNode, NodeController, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    node.commonAttribute;
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 });
    node.appendChild(col);
    // Create and initialize TextInput. By default, the focus is obtained.
    let textInput = typeNode.createNode(uiContext, 'TextInput');
    textInput.initialize({ text: "TextInput" })
      .defaultFocus(true)
    col.appendChild(textInput);
    // Bind TextInputController and set the cursor position.
    let controller: TextInputController = new TextInputController();
    typeNode.bindController(textInput, controller, 'TextInput');
    controller.caretPosition(3);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('TextInput bindController sample');
      NodeContainer(this.myNodeController);
    }
  }
}

Button¹²⁺

type Button = TypedFrameNode<ButtonInterface, ButtonAttribute>

Represents a FrameNode of the Button type. When created in child component mode, this type of node allows only one child component to be added. When created in label mode, it does not child components to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ButtonInterface, ButtonAttribute>

FrameNode of the Button type.
ButtonInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Button component.
ButtonAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Button component.
If a value is specified for the label parameter, a Button component is created in label mode. This component cannot contain child components, and any attempt to set child components will result in an exception. The mode in which the Button component is created cannot be dynamically modified in subsequent initialize calls. As such, to include child components, do not set the label parameter during the first initialize call.
When created in child component mode, a Button component can contain a single child component. Any attempt to set multiple child components will result in an exception.
ButtonInterface indicates the API of the Button component, and ButtonAttribute indicates the attribute of the Button component.

createNode('Button')¹²⁺

createNode(context: UIContext, nodeType: 'Button'): Button

Creates a FrameNode of the Button type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Button'	Yes	Node type. Set to 'Button'.

Return value

Type	Description
Button	FrameNode of the Button type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Button controller by extending NodeController.
class MyButtonController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    let col = typeNode.createNode(uiContext, 'Column')
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col)
    // Create a Button node.
    let button = typeNode.createNode(uiContext, 'Button')
    button.initialize("This is Button")
      .onClick(() => {
        uiContext.getPromptAction().showToast({ message: "Button clicked" })
      })
    col.appendChild(button)

    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myButtonController: MyButtonController = new MyButtonController();

  build() {
    Column({ space: 5 }) {
      Text('ButtonSample')
      NodeContainer(this.myButtonController);

    }.width('100%')
  }
}

getAttribute('Button')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'Button'): ButtonAttribute | undefined

Obtains the attributes of a Button node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'Button'	Yes	Node type. Set to 'Button'.

Return value

Type	Description
ButtonAttribute \| undefined	Attributes of the Button node, or undefined if they fail to be obtained.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Button controller by extending NodeController.
class MyButtonController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext)
    node.commonAttribute
    let col = typeNode.createNode(uiContext, 'Column')
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col)
    let button = typeNode.createNode(uiContext, 'Button')
    button.initialize("This is Button")
      .onClick(() => {
        uiContext.getPromptAction().showToast({ message: "Button clicked" })
      })
    // Obtain the attributes of the Button node.
    typeNode.getAttribute(button,'Button')?.buttonStyle(ButtonStyleMode.TEXTUAL)
    col.appendChild(button)

    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myButtonController: MyButtonController = new MyButtonController();

  build() {
    Column({ space: 5 }) {
      Text('ButtonSample')
      NodeContainer(this.myButtonController);

    }.width('100%')
  }
}

ListItemGroup¹²⁺

type ListItemGroup = TypedFrameNode<ListItemGroupInterface, ListItemGroupAttribute>

Represents a FrameNode of the ListItemGroup type. Only ListItem child components can be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<ListItemGroupInterface, ListItemGroupAttribute>

FrameNode of the ListItemGroup type.
ListItemGroupInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the ListItemGroup component.
ListItemGroupAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the ListItemGroup component.
ListItemGroupInterface indicates the API of the ListItemGroup component, and ListItemGroupAttribute indicates the attribute of the ListItemGroup component.

createNode('ListItemGroup')¹²⁺

createNode(context: UIContext, nodeType: 'ListItemGroup'): ListItemGroup

Creates a FrameNode of the ListItemGroup type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'ListItemGroup'	Yes	Node type. Set to 'ListItemGroup'.

Return value

Type	Description
ListItemGroup	FrameNode of the ListItemGroup type.

Example

See the example for createNode('List').

getAttribute('ListItemGroup')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'ListItemGroup'): ListItemGroupAttribute | undefined

Obtains the attributes of a ListItemGroup node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'ListItemGroup'	Yes	Node type. Set to 'ListItemGroup'.

Return value

Type	Description
ListItemGroupAttribute \| undefined	Attributes of the ListItemGroup node, or undefined if they fail to be obtained.

Example

typeNode.getAttribute(node, 'ListItemGroup');

WaterFlow¹²⁺

type WaterFlow = TypedFrameNode<WaterFlowInterface, WaterFlowAttribute>

Represents a FrameNode of the WaterFlow type. Only FlowItem child components can be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<WaterFlowInterface, WaterFlowAttribute>

Provides the FrameNode of the WaterFlow type.
WaterFlowInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the WaterFlow component.
WaterFlowAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the WaterFlow component.
WaterFlowInterface indicates the API of the WaterFlow component, and WaterFlowAttribute indicates the attribute of the WaterFlow component.

createNode('WaterFlow')¹²⁺

createNode(context: UIContext, nodeType: 'WaterFlow'): WaterFlow

Creates a FrameNode of the WaterFlow type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'WaterFlow'	Yes	Node type. Set to 'WaterFlow'.

Return value

Type	Description
WaterFlow	FrameNode of the WaterFlow type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom WaterFlow controller by extending NodeController.
class MyWaterFlowController extends NodeController {
  public rootNode: FrameNode | null = null;
  private minHeight: number = 80;
  private maxHeight: number = 180;

  // Calculate the FlowItem height.
  private getHeight() {
    let ret = Math.floor(Math.random() * this.maxHeight);
    return (ret > this.minHeight ? ret : this.minHeight);
  }

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    // Create a WaterFlow node and set its properties.
    let waterFlowNode = typeNode.createNode(uiContext, 'WaterFlow');
    waterFlowNode.attribute.size({ width: '100%', height: '100%' })
      .columnsTemplate('1fr 1fr')
      .columnsGap(10)
      .rowsGap(5);
    typeNode.getAttribute(waterFlowNode, "WaterFlow")?.friction(0.6);

    // Create a FlowItem node and set its properties.
    for (let i = 0; i < 20; i++) {
      let flowItemNode = typeNode.createNode(uiContext, 'FlowItem');
      flowItemNode.attribute.size({ height: this.getHeight() });
      typeNode.getAttribute(flowItemNode, "FlowItem")?.width('100%');
      waterFlowNode.appendChild(flowItemNode);

      let text = typeNode.createNode(uiContext, 'Text');
      text.initialize('N' + i)
        .size({ width: '100%', height: '100%' })
        .textAlign(TextAlign.Center)
        .backgroundColor(0xF9CF93);
      flowItemNode.appendChild(text);
    }

    this!.rootNode!.appendChild(waterFlowNode);
    return this.rootNode;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myWaterFlowController: MyWaterFlowController = new MyWaterFlowController();

  build() {
    Column({ space: 5 }) {
      Text('WaterFlowSample')
      NodeContainer(this.myWaterFlowController);

    }.width('100%')
  }
}

getEvent('WaterFlow')¹⁹⁺

getEvent(node: FrameNode, nodeType: 'WaterFlow'): UIWaterFlowEvent | undefined

Obtains the UIWaterFlowEvent object associated with the WaterFlow node for configuring scroll events. The scroll events configured through this API coexist with declarative events without overriding them. If both event callbacks are registered, the declaratively defined event callback takes precedence.

Atomic service API: This API can be used in atomic services since API version 19.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node.
nodeType	'WaterFlow'	Yes	WaterFlow node type for scroll event configuration.

Return value

Type	Description
UIWaterFlowEvent \| undefined	UIWaterFlowEvent object for the WaterFlow node, or undefined if it fails to be obtained.

Example

getAttribute('WaterFlow')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'WaterFlow'): WaterFlowAttribute | undefined

Obtains the attributes of a WaterFlow node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'WaterFlow'	Yes	Node type. Set to 'WaterFlow'.

Return value

Type	Description
WaterFlowAttribute \| undefined	Properties of the WaterFlow node, or undefined if they fail to be obtained.

Example

See the example for createNode('WaterFlow').

bindController('WaterFlow')²⁰⁺

bindController(node: FrameNode, controller: Scroller, nodeType: 'WaterFlow'): void

Binds a Scroller instance to the WaterFlow node. Cross-language access must be enabled for nodes not created via ArkTS; otherwise, an exception will be thrown. This API supports declaratively created nodes since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node to which the scroll controller is bound.
controller	Scroller	Yes	Scroll controller.
nodeType	'WaterFlow'	Yes	Node type. Set to 'WaterFlow'.

Error codes

For details about the error codes, see Custom Node Error Codes.

ID	Error Message
100023	Parameter error. Possible causes: 1. The component type of the node is incorrect. 2. The node is null or undefined. 3. The controller is null or undefined.
100021	The FrameNode is not modifiable.

Example

typeNode.bindController(node, scroller, 'WaterFlow');

FlowItem¹²⁺

type FlowItem = TypedFrameNode<FlowItemInterface, FlowItemAttribute>

Represents a FrameNode of the FlowItem type. This type of node allows only one child component to be added.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<FlowItemInterface, FlowItemAttribute>

FrameNode of the FlowItem type.
FlowItemInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the FlowItem component.
FlowItemAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the FlowItem component.
FlowItemInterface indicates the API of the FlowItem component, and FlowItemAttribute indicates the attribute of the FlowItem component.

createNode('FlowItem')¹²⁺

createNode(context: UIContext, nodeType: 'FlowItem'): FlowItem

Creates a FrameNode of the FlowItem type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'FlowItem'	Yes	Node type. Set to 'FlowItem'.

Return value

Type	Description
FlowItem	FrameNode of the FlowItem type.

Example

See the example for createNode('WaterFlow').

getAttribute('FlowItem')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'FlowItem'): FlowItemAttribute | undefined

Obtains the attributes of a FlowItem node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'FlowItem'	Yes	Node type. Set to 'FlowItem'.

Return value

Type	Description
FlowItemAttribute \| undefined	Properties of the FlowItem node, or undefined if they fail to be obtained.

Example

See the example for createNode('WaterFlow').

XComponent¹²⁺

type XComponent = TypedFrameNode<XComponentInterface, XComponentAttribute>

Represents a FrameNode of the XComponent type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<XComponentInterface, XComponentAttribute>

FrameNode of the XComponent type.
XComponentInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the XComponent component.
XComponentAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the XComponent component.
XComponentInterface indicates the API of XComponent, and XComponentAttribute indicates the attribute of XComponent.

createNode('XComponent')¹²⁺

createNode(context: UIContext, nodeType: 'XComponent'): XComponent

Creates a FrameNode of the XComponent type.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'XComponent'	Yes	Node type. Set to 'XComponent'.

Return value

Type	Description
XComponent	FrameNode of the XComponent type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col);
    // Create an XComponent object.
    let xcomponent = typeNode.createNode(uiContext, 'XComponent');
    xcomponent.attribute.backgroundColor(Color.Red);
    col.appendChild(xcomponent);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('XComponentSample')
      NodeContainer(this.myNodeController)
    }.width('100%')
  }
}

createNode('XComponent')¹²⁺

createNode(context: UIContext, nodeType: 'XComponent', options: XComponentOptions): XComponent

Creates a FrameNode of the XComponent type based on the settings specified in options.

Atomic service API: This API can be used in atomic services since API version 12.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'XComponent'	Yes	Node type. Set to 'XComponent'.
options	XComponentOptions	Yes	Options of the XComponent.

Return value

Type	Description
XComponent	FrameNode of the XComponent type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  controller: XComponentController = new XComponentController();
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col);
    // Set the XComponent parameter object.
    let options: XComponentOptions = {
      type: XComponentType.SURFACE,
      controller: this.controller
    };
    // Create an XComponent object.
    let xcomponent = typeNode.createNode(uiContext, 'XComponent', options);
    xcomponent.attribute.backgroundColor(Color.Red);
    col.appendChild(xcomponent);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('XComponentSample')
      NodeContainer(this.myNodeController)
    }.width('100%')
  }
}

createNode('XComponent')¹⁹⁺

createNode(context: UIContext, nodeType: 'XComponent', parameters: NativeXComponentParameters): XComponent

Creates a FrameNode of the XComponent type based on the settings specified in parameters.

Atomic service API: This API can be used in atomic services since API version 19.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'XComponent'	Yes	Node type. Set to 'XComponent'.
parameters	NativeXComponentParameters	Yes	Options of the XComponent.

Return value

Type	Description
XComponent	FrameNode of the XComponent type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom UI controller by extending NodeController.
class MyNodeController extends NodeController {
  controller: XComponentController = new XComponentController();
  makeNode(uiContext: UIContext): FrameNode | null {
    let node = new FrameNode(uiContext);
    let col = typeNode.createNode(uiContext, 'Column');
    col.initialize({ space: 5 })
      .width('100%')
      .height('100%')
    node.appendChild(col);
    let parameters: NativeXComponentParameters = {
      type: XComponentType.SURFACE
    };
    // Create an XComponent object.
    let xcomponent = typeNode.createNode(uiContext, 'XComponent', parameters);
    xcomponent.attribute.backgroundColor(Color.Red);
    col.appendChild(xcomponent);
    return node;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myNodeController: MyNodeController = new MyNodeController();

  build() {
    Column({ space: 5 }) {
      Text('XComponentSample')
      NodeContainer(this.myNodeController)
    }.width('100%')
  }
}

getAttribute('XComponent')²⁰⁺

getAttribute(node: FrameNode, nodeType: 'XComponent'): XComponentAttribute | undefined

Obtain the attributes of an XComponent node. If the node is not created using ArkTS, cross-language access must be enabled; otherwise, undefined is returned. This API does not support declaratively created nodes.

Atomic service API: This API can be used in atomic services since API version 20.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node from which to obtain attributes.
nodeType	'XComponent'	Yes	Node type. Set to 'XComponent'.

Return value

Type	Description
XComponentAttribute \| undefined	Properties of the XComponent node, or undefined if they fail to be obtained.

Example

typeNode.getAttribute(node, 'XComponent');

QRCode¹⁴⁺

type QRCode = TypedFrameNode<QRCodeInterface, QRCodeAttribute>

Represents a FrameNode of the QRCode type.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<QRCodeInterface, QRCodeAttribute>

FrameNode of the QRCode type.
QRCodeInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the QRCode component.
QRCodeAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the QRCode component.
QRCodeInterface indicates the API of the QRCode component, and QRCodeAttribute indicates the attribute of the QRCode component.

createNode('QRCode')¹⁴⁺

createNode(context: UIContext, nodeType: 'QRCode'): QRCode

Creates a FrameNode of the QRCode type.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'QRCode'	Yes	Node type, which is QRCode in this API.

Return value

Type	Description
QRCode	FrameNode of the QRCode type.

Example

typeNode.createNode(uiContext, 'QRCode');

Badge¹⁴⁺

type Badge = TypedFrameNode<BadgeInterface, BadgeAttribute>

Represents a FrameNode of the Badge type.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<BadgeInterface, BadgeAttribute>

FrameNode of the Badge type.
BadgeInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Badge component.
BadgeAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Badge component.
BadgeInterface indicates the API of the Badge component, and BadgeAttribute indicates the attribute of the Badge component.

createNode('Badge')¹⁴⁺

createNode(context: UIContext, nodeType: 'Badge'): Badge

Creates a FrameNode of the Badge type.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Badge'	Yes	Node type. Set to 'Badge'.

Return value

Type	Description
Badge	FrameNode of the Badge type.

Example

typeNode.createNode(uiContext, 'Badge');

Grid¹⁴⁺

type Grid = TypedFrameNode<GridInterface, GridAttribute>

Represents a FrameNode of the Grid type.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type

Description

TypedFrameNode<GridInterface, GridAttribute>

FrameNode of the Grid type.
GridInterface is used as the input parameter of the initialize API of TypedFrameNode. The input parameter is of the constructor type for the Grid component.
GridAttribute is used as the return value of the attribute API of TypedFrameNode. It returns the attribute setting object of the Grid component.
GridInterface indicates the API of the Grid component, and GridAttribute indicates the attribute of the Grid component.

createNode('Grid')¹⁴⁺

createNode(context: UIContext, nodeType: 'Grid'): Grid

Creates a FrameNode of the Grid type.

Atomic service API: This API can be used in atomic services since API version 14.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
context	UIContext	Yes	UI context for node creation.
nodeType	'Grid'	Yes	Node type. Set to 'Grid'.

Return value

Type	Description
Grid	FrameNode of the Grid type.

Example

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

// Implement a custom Grid controller by extending NodeController.
class MyGridController extends NodeController {
  public rootNode: FrameNode | null = null;
  private scroller: Scroller = new Scroller();

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);

    // Create a Grid node and set its properties.
    let gridNode = typeNode.createNode(uiContext, 'Grid');
    gridNode.initialize(this.scroller, { regularSize: [1, 1] })
      .size({ width: '90%', height: 300 })
      .columnsTemplate('1fr 1fr 1fr 1fr 1fr')
      .rowsTemplate('1fr 1fr 1fr 1fr 1fr')
      .columnsGap(10)
      .rowsGap(10);
    typeNode.getAttribute(gridNode, "Grid")?.friction(0.6);

    // Create a GridItem node and set its properties.
    for (let i = 0; i < 25; i++) {
      let gridItemNode = typeNode.createNode(uiContext, 'GridItem');
      gridItemNode.initialize({ style: GridItemStyle.NONE }).size({ height: '100%' });
      typeNode.getAttribute(gridItemNode, "GridItem")?.width('100%');

      let text = typeNode.createNode(uiContext, 'Text');
      text.initialize((i % 5).toString())
        .size({ width: '100%', height: '100%' })
        .textAlign(TextAlign.Center)
        .backgroundColor(0xF9CF93);
      gridItemNode.appendChild(text);
      gridNode.appendChild(gridItemNode);
    }

    this!.rootNode!.appendChild(gridNode);
    return this.rootNode;
  }
}

@Entry
@Component
struct FrameNodeTypeTest {
  private myGridController: MyGridController = new MyGridController();

  build() {
    Column({ space: 5 }) {
      Text('GridSample')
      NodeContainer(this.myGridController)

    }.width('100%')
  }
}

getEvent('Grid')¹⁹⁺

getEvent(node: FrameNode, nodeType: 'Grid'): UIGridEvent | undefined

Obtains the UIGridEvent object associated with the Grid node for configuring scroll events. The scroll events configured through this API coexist with declarative events without overriding them. If both event callbacks are registered, the declaratively defined event callback takes precedence.

Atomic service API: This API can be used in atomic services since API version 19.

Model constraint: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
node	FrameNode	Yes	Target node.
nodeType	'Grid'	Yes	Grid node type for scroll event configuration.

Return value

Type	Description
UIGridEvent \| undefined	UIGridEvent object for the Grid node, or undefined if it fails to be obtained.

Example