@ohos.arkui.inspector (Layout Callback)

The Inspector module provides APIs for registering the component layout and drawing completion callbacks.

NOTE

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

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

Modules to Import

import { inspector } from '@kit.ArkUI';

inspector.createComponentObserver^(deprecated)

createComponentObserver(id: string): ComponentObserver

Binds to the specified component and returns the corresponding observation handle.

NOTE

This method has been deprecated since API version 18. You are advised to use the getUIInspector method in UIContext to obtain the UIInspector instance, and then use the instance to call the substitute method createComponentObserver.

Since API version 10, you can use the getUIInspector API in UIContext to obtain the UIInspector object associated with the current UI context.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
id	string	Yes	ID of the target component, set using the universal attributes id or key.

Return value

Type	Description
ComponentObserver	Component observer handle, which is used to register and unregister callbacks.

Example

let listener:inspector.ComponentObserver = inspector.createComponentObserver('COMPONENT_ID'); // Listen for callback events for the component whose ID is COMPONENT_ID.

ComponentObserver

Defines the handle for component layout and drawing completion callbacks. You can call the following APIs through this handle:

on('layout')

on(type: 'layout', callback: () => void): void

Registers a layout completion callback through this handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'layout'. 'layout': completion of component layout.
callback	() => void	Yes	Layout completion callback.

off('layout')

off(type: 'layout', callback?: () => void): void

Unregisters the layout completion callback through this handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'layout'. 'layout': completion of component layout.
callback	() => void	No	Callback to unregister. If this parameter is not specified, all callbacks under this handle are unregistered. The callback must be the same object as the one registered with the on('layout') API to successfully unregister.

on('draw')

on(type: 'draw', callback: () => void): void

Registers a drawing completion callback through this handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'draw'. 'draw': completion of component drawing.
callback	() => void	Yes	Drawing completion callback.

off('draw')

off(type: 'draw', callback?: () => void): void

Unregisters the drawing completion callback through this handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'draw'. 'draw': completion of component drawing.
callback	() => void	No	Callback to unregister. If this parameter is not specified, all callbacks under this handle are unregistered. The callback must be the same object as the one registered with the on('draw') API to successfully unregister.

on('drawChildren')²⁰⁺

on(type: 'drawChildren', callback: Callback<void>): void

Registers a child component drawing completion callback through ComponentObserver. When multiple drawChildren callbacks exist in the component tree, only the topmost callback will be triggered. After the topmost callback is canceled, other drawChildren callbacks will not take effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'drawChildren'. 'drawChildren': completion of child component drawing.
callback	Callback<void>	Yes	Child component drawing completion callback.

off('drawChildren')²⁰⁺

off(type: 'drawChildren', callback?: Callback<void>): void

Unregisters the child component drawing completion callback through this handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'drawChildren'. 'drawChildren': completion of child component drawing.
callback	Callback<void>	No	Callback to unregister. If this parameter is not specified, all callbacks under this handle are unregistered. The callback must be the same object as the one registered with the on('drawChildren')20+ API to successfully unregister.

onLayoutChildren²³⁺

onLayoutChildren(callback: Callback<void>): void

Registers a callback used to listen for the layoutChildren event using ComponentObserver. This API uses an asynchronous callback to return the result.

When the node that is currently listened is used as the root node and the nodes in the subtree are laid out, this callback is triggered. When multiple layoutChildren callbacks exist in the component tree, only the topmost callback will be triggered. After the topmost callback is canceled, other layoutChildren callbacks will not take effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

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

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	Yes	Callback used to listen for the layoutChildren event.

offLayoutChildren²³⁺

offLayoutChildren(callback?: Callback<void>): void

Unregisters the callback used to listen for the layoutChildren event. This API uses an asynchronous callback to return the result.

To stop triggering a specific callback after the child component layout is complete, you only need to unregister the callback based on the corresponding query condition using its handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

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

Parameters

Name	Type	Mandatory	Description
callback	Callback<void>	No	Callback to unregister. If this parameter is not specified, all callbacks under this handle are unregistered. The callback can be successfully unregistered only when it matches the callback in the onLayoutChildren23+ method.

Example

The following example demonstrates how to register the component layout and drawing completion callbacks. In addition, you can use the onLayoutChildren²³⁺ API to listen for the callback event triggered when the layout of a node in the subtree is complete.

import { inspector } from '@kit.ArkUI';

@Entry
@Component
struct ImageExample {
  build() {
    Column() {
      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
        Row({ space: 5 }) {
          Image($r('app.media.startIcon'))
            .width(110)
            .height(110)
            .border({ width: 1 })
            .id('IMAGE_ID')
        }
        .id('ROW_ID')
      }
    }.height(320).width(360).padding({ right: 10, top: 10 })
  }

  listenerForImage: inspector.ComponentObserver = this.getUIContext().getUIInspector().createComponentObserver('IMAGE_ID')
  listenerForRow: inspector.ComponentObserver = this.getUIContext().getUIInspector().createComponentObserver('ROW_ID')

  aboutToAppear() {
    let onLayoutComplete: () => void = (): void => {
      // Supplement the implementation code as required.
    }
    let onDrawComplete: () => void = (): void => {
      // Supplement the implementation code as required.
    }
    let onDrawChildrenComplete: () => void = (): void => {
      // Supplement the implementation code as required.
    }
    // Bind to the current JS instance.
    let FuncLayout = onLayoutComplete
    let FuncDraw = onDrawComplete
    let FuncDrawChildren = onDrawChildrenComplete
    let OffFuncLayout = onLayoutComplete
    let OffFuncDraw = onDrawComplete
    let OffFuncDrawChildren = onDrawChildrenComplete

    this.listenerForImage.on('layout', FuncLayout)
    this.listenerForImage.on('draw', FuncDraw)
    this.listenerForRow.on('drawChildren', FuncDrawChildren)

    // Unregister callbacks through the handle. You should decide when to call these APIs.
    // this.listenerForImage.off('layout', OffFuncLayout)
    // this.listenerForImage.off('draw', OffFuncDraw)
    // this.listenerForRow.off('drawChildren', OffFuncDrawChildren)

    let onLayoutChildrenComplete: () => void = (): void => {
      // After the LayoutChildren event is received, you can customize the implementation logic.
    }

    let uniqueId: number = this.getUniqueId();
    let listenerForUniqueId: inspector.ComponentObserver = this.getUIContext().getUIInspector().createComponentObserver(uniqueId)
    listenerForUniqueId.onLayoutChildren(onLayoutChildrenComplete)
  }

  // Unregister callbacks through the handle. You should decide when to call these APIs.
  // listenerForUniqueId.offLayoutChildren(onLayoutChildrenComplete)
}

onDrawChildren²⁴⁺

onDrawChildren(callback: Callback<number[]>): void

Registers a callback used to listen for the drawChildren event using ComponentObserver. This API uses an asynchronous callback to return the result.

When the node that is currently listened is used as the root node, the callback will be triggered after the child components of the component complete drawing. When multiple drawChildren callbacks exist in the component tree, only the topmost callback will be triggered. After the topmost callback is canceled, other drawChildren callbacks will not take effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

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

Parameters

Name	Type	Mandatory	Description
callback	Callback<number[]>	Yes	Child component drawing completion callback.

Example

The following example demonstrates how to register the component layout and drawing completion callbacks. After the rendering of the node in the subtree is complete, you can use the onDrawChildren²⁴⁺ API to return the unique ID of the node through a callback.

import { inspector } from '@kit.ArkUI';

@Entry
@Component
struct ImageExample {
  build() {
    Column() {
      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
        Row({ space: 5 }) {
          Image($r('app.media.startIcon'))
            .width(110)
            .height(110)
            .border({ width: 1 })
            .id('IMAGE_ID')
        }
        .id('ROW_ID')
      }
    }.height(320).width(360).padding({ right: 10, top: 10 })
  }

  listenerForRow: inspector.ComponentObserver = this.getUIContext().getUIInspector().createComponentObserver('ROW_ID')

  aboutToAppear() {
    let onDrawChildrenComplete_uniqueId:(childIds: number[])=>void = (childIds: number[]) : void => {
      // The onDrawChildren API is added since API version 24. After the DrawChildren event is received, you can customize the implementation logic.
    }

    let uniqueId: number = this.getUniqueId();
    this.listenerForRow.onDrawChildren(onDrawChildrenComplete_uniqueId)
  }
}

offDrawChildren²⁴⁺

offDrawChildren(callback?: Callback<number[]>): void

Unregisters the callback used to listen for the drawChildren event. This API uses an asynchronous callback to return the result.

To stop triggering a specific callback after the child component layout is complete, you only need to unregister the callback based on the corresponding query condition using its handle.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

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

Parameters

Name	Type	Mandatory	Description
callback	Callback<number[]>	No	Callback to unregister. If this parameter is not specified, all callbacks under this handle are unregistered. The callback can be successfully unregistered only when it matches the callback in the onDrawChildren method.

Example

import { inspector } from '@kit.ArkUI';

@Entry
@Component
struct ImageExample {
  build() {
    Column() {
      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
        Row({ space: 5 }) {
          Image($r('app.media.startIcon'))
            .width(110)
            .height(110)
            .border({ width: 1 })
            .id('IMAGE_ID')
        }
        .id('ROW_ID')
      }
    }.height(320).width(360).padding({ right: 10, top: 10 })
  }

  listenerForRow: inspector.ComponentObserver = this.getUIContext().getUIInspector().createComponentObserver('ROW_ID')

  aboutToAppear() {
    let onDrawChildrenComplete_uniqueId:(childIds: number[])=>void = (childIds: number[]) : void => {
      // The onDrawChildren API is added since API version 24. After the DrawChildren event is received, you can customize the implementation logic.
    }

    let uniqueId: number = this.getUniqueId();
    this.listenerForRow.onDrawChildren(onDrawChildrenComplete_uniqueId)
  }
  // Unregister callbacks through the handle. You should decide when to call these APIs.
  // this.listenerForRow.offDrawChildren(onDrawChildrenComplete_uniqueId)
}

@ohos.arkui.inspector (Layout Callback)

Modules to Import

inspector.createComponentObserver(deprecated)

ComponentObserver

on('layout')

off('layout')

on('draw')

off('draw')

on('drawChildren')20+

off('drawChildren')20+

onLayoutChildren23+

offLayoutChildren23+

onDrawChildren24+

offDrawChildren24+

inspector.createComponentObserver^(deprecated)

on('drawChildren')²⁰⁺

off('drawChildren')²⁰⁺

onLayoutChildren²³⁺

offLayoutChildren²³⁺

onDrawChildren²⁴⁺

offDrawChildren²⁴⁺