harmony 鸿蒙@ohos.arkui.componentSnapshot (Component Snapshot)

2025-06-12
浏览 (4)

@ohos.arkui.componentSnapshot (Component Snapshot)

The componentSnapshot module provides APIs for obtaining component snapshots, including snapshots of components that have been loaded and snapshots of components that have not been loaded yet. Snapshots are strictly limited to the component’s layout bounds. Content drawn outside the area of the owning component or the parent component is not visible in the snapshots. In addition, sibling components stacked in the component’s area are not displayed in the snapshot.

Transformation properties such as scaling, translation, and rotation only apply to the child components of the target component. Applying these transformation properties directly to the target component itself has no effect; the snapshot will still display the component as it appears before any transformations are applied.

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.

In scenarios where XComponent is used to, for example, display video or camera streams, obtain images through surface, instead of through an API in this module.

If the content of a component does not fill the entire area allocated for it, any remaining space in the snapshot will be rendered as transparent pixels. In addition, if the component uses image effects or other effect-related attributes, the resulting snapshot may not be as expected. To address these potential issues, check whether to fill the component’s transparent content area or to use an alternative method such as taking a window screenshot.

You can preview how this component looks on a real device, but not in DevEco Studio Previewer.

Modules to Import

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

componentSnapshot.get^(deprecated)

get(id: string, callback: AsyncCallback, options?: SnapshotOptions): void

Obtains the snapshot of a component that has been loaded. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 18. You are advised to use get instead on the obtained ComponentSnapshot object.

Since API version 12, you can use the getComponentSnapshot API in UIContext to obtain the ComponentSnapshot object associated with the current UI context.

The snapshot captures content rendered in the last frame. If this API is called when the component triggers an update, the re-rendered content will not be included in the obtained snapshot.

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.
callback	AsyncCallback<image.PixelMap>	Yes	Callback used to return the result.
options¹²⁺	SnapshotOptions	No	Custom settings of the snapshot.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	Invalid ID.

Example

NOTE

Directly using componentSnapshot can lead to ambiguous instance issues. To avoid this, obtain a UIContext instance using getUIContext, and then obtain the associated componentSnapshot object using getComponentSnapshot.

import { componentSnapshot } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct SnapshotExample {
  @State pixmap: image.PixelMap|undefined = undefined

  build() {
    Column() {
      Row() {
        Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5)
        Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root")
      }
      Button("click to generate UI snapshot")
        .onClick(() => {
          // You are advised to use this.getUIContext().getComponentSnapshot().get().
          componentSnapshot.get("root", (error: Error, pixmap: image.PixelMap) => {
            if (error) {
              console.log("error: " + JSON.stringify(error))
              return;
            }
            this.pixmap = pixmap
          }, {scale : 2, waitUntilRenderFinished : true})
        }).margin(10)
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

componentget

componentSnapshot.get^(deprecated)

get(id: string, options?: SnapshotOptions): Promise

Obtains the snapshot of a component that has been loaded. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 18. You are advised to use get instead on the obtained ComponentSnapshot object.

Since API version 12, you can use the getComponentSnapshot API in UIContext to obtain the ComponentSnapshot object associated with the current UI context.

The snapshot captures content rendered in the last frame. If this API is called when the component triggers an update, the re-rendered content will not be included in the obtained snapshot.

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.
options¹²⁺	SnapshotOptions	No	Custom settings of the snapshot.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	Invalid ID.

Example

NOTE

Directly using componentSnapshot can lead to ambiguous instance issues. To avoid this, obtain a UIContext instance using getUIContext, and then obtain the associated componentSnapshot object using getComponentSnapshot.

import { componentSnapshot } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct SnapshotExample {
  @State pixmap: image.PixelMap|undefined = undefined

  build() {
    Column() {
      Row() {
        Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5)
        Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root")
      }
      Button("click to generate UI snapshot")
        .onClick(() => {
          // You are advised to use this.getUIContext().getComponentSnapshot().get().
          componentSnapshot.get("root", {scale : 2, waitUntilRenderFinished : true})
            .then((pixmap: image.PixelMap) => {
              this.pixmap = pixmap
            }).catch((err:Error) => {
            console.log("error: " + err)
          })
        }).margin(10)
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

componentget

componentSnapshot.createFromBuilder^(deprecated)

createFromBuilder(builder: CustomBuilder, callback: AsyncCallback, delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): void

Renders a custom component in the application background and outputs its snapshot. This API uses an asynchronous callback to return the result. The coordinates and size of the offscreen component’s drawing area can be obtained through the callback.

NOTE

This API is deprecated since API version 18. You are advised to use createFromBuilder instead on the obtained ComponentSnapshot object.

Since API version 12, you can use the getComponentSnapshot API in UIContext to obtain the ComponentSnapshot object associated with the current UI context.

To account for the time spent in awaiting component building and rendering, the callback of offscreen snapshots has a delay of less than 500 ms.

Components in the builder do not support the setting of animation-related attributes, such as transition.

If a component is on a time-consuming task, for example, an Image or Web component that is loading online images, its loading may be still in progress when this API is called. In this case, the output snapshot does not represent the component in the way it looks when the loading is successfully completed.

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
builder	CustomBuilder	Yes	Builder of the custom component. NOTE The global builder is not supported.
callback	AsyncCallback<image.PixelMap>	Yes	Callback used to return the result. The coordinates and size of the offscreen component’s drawing area can be obtained through the callback.
delay¹²⁺	number	No	Delay time for triggering the screenshot command. When the layout includes an image component, it is necessary to set a delay time to allow the system to decode the image resources. The decoding time is subject to the resource size. In light of this, whenever possible, use pixel map resources that do not require decoding. When pixel map resources are used or when syncload to true for the Image component, you can set delay to 0 to forcibly capture snapshots without waiting. This delay time does not refer to the time from the API call to the return: As the system needs to temporarily construct the passed-in builder offscreen, the return time is usually longer than this delay. NOTE In the builder passed in, state variables should not be used to control the construction of child components. If they are used, they should not change when the API is called, so as to avoid unexpected snapshot results. Default value: 300 Unit: ms Value range: [0, +∞). If the value is less than 0, the default value is used.
checkImageStatus¹²⁺	boolean	No	Whether to check the image decoding status before taking a snapshot. If the value is true, the system checks whether all Image components have been decoded before taking the snapshot. If the check is not completed, the system aborts the snapshot and returns an exception. Default value: false
options¹²⁺	SnapshotOptions	No	Custom settings of the snapshot.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	The builder is not a valid build function.
160001	An image component in builder is not ready for taking a snapshot. The check for the ready state is required when the checkImageStatus option is enabled.

Example

NOTE

Directly using componentSnapshot can lead to ambiguous instance issues. To avoid this, obtain a UIContext instance using getUIContext, and then obtain the associated componentSnapshot object using getComponentSnapshot.

import { componentSnapshot } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct OffscreenSnapshotExample {
  @State pixmap: image.PixelMap|undefined = undefined

  @Builder
  RandomBuilder() {
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      Text('Test menu item 1')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
      Divider().height(10)
      Text('Test menu item 2')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
    }
    .width(100)
    .id("builder")
  }

  build() {
    Column() {
      Button("click to generate offscreen UI snapshot")
        .onClick(() => {
          // You are advised to use this.getUIContext().getComponentSnapshot().createFromBuilder().
          componentSnapshot.createFromBuilder(()=>{this.RandomBuilder()},
            (error: Error, pixmap: image.PixelMap) => {
              if(error){
                console.log("error: " + JSON.stringify(error))
                return;
              }
              this.pixmap = pixmap
              // save pixmap to file
              // ....
              // get component size and location
              let info = this.getUIContext().getComponentUtils().getRectangleById("builder")
              console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y)
            }, 320, true, {scale : 2, waitUntilRenderFinished : true})
        })
      Image(this.pixmap)
        .margin(10)
        .height(200)
        .width(200)
        .border({ color: Color.Black, width: 2 })
    }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300)
  }
}

componentcreate

componentSnapshot.createFromBuilder^(deprecated)

createFromBuilder(builder: CustomBuilder, delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): Promise

Renders a custom component in the application background and outputs its snapshot. This API uses a promise to return the result. The coordinates and size of the offscreen component’s drawing area can be obtained through the callback.

NOTE

This API is deprecated since API version 18. You are advised to use createFromBuilderinstead on the obtained ComponentSnapshot object.

Since API version 12, you can use the getComponentSnapshot API in UIContext to obtain the ComponentSnapshot object associated with the current UI context.

To account for the time spent in awaiting component building and rendering, the callback of offscreen snapshots has a delay of less than 500 ms.

Components in the builder do not support the setting of animation-related attributes, such as transition.

If a component is on a time-consuming task, for example, an Image or Web component that is loading online images, its loading may be still in progress when this API is called. In this case, the output snapshot does not represent the component in the way it looks when the loading is successfully completed.

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
builder	CustomBuilder	Yes	Builder of the custom component. NOTE The global builder is not supported.
delay¹²⁺	number	No	Delay time for triggering the screenshot command. When the layout includes an image component, it is necessary to set a delay time to allow the system to decode the image resources. The decoding time is subject to the resource size. In light of this, whenever possible, use pixel map resources that do not require decoding. When pixel map resources are used or when syncload to true for the Image component, you can set delay to 0 to forcibly capture snapshots without waiting. This delay time does not refer to the time from the API call to the return: As the system needs to temporarily construct the passed-in builder offscreen, the return time is usually longer than this delay. NOTE In the builder passed in, state variables should not be used to control the construction of child components. If they are used, they should not change when the API is called, so as to avoid unexpected snapshot results. Default value: 300 Unit: ms
checkImageStatus¹²⁺	boolean	No	Whether to check the image decoding status before taking a snapshot. If the value is true, the system checks whether all Image components have been decoded before taking the snapshot. If the check is not completed, the system aborts the snapshot and returns an exception. Default value: false
options¹²⁺	SnapshotOptions	No	Custom settings of the snapshot.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the result.

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	The builder is not a valid build function.
160001	An image component in builder is not ready for taking a snapshot. The check for the ready state is required when the checkImageStatus option is enabled.

Example

NOTE

Directly using componentSnapshot can lead to ambiguous instance issues. To avoid this, obtain a UIContext instance using getUIContext, and then obtain the associated componentSnapshot object using getComponentSnapshot.

import { componentSnapshot } from '@kit.ArkUI'
import { image } from '@kit.ImageKit'

@Entry
@Component
struct OffscreenSnapshotExample {
  @State pixmap: image.PixelMap|undefined = undefined

  @Builder
  RandomBuilder() {
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      Text('Test menu item 1')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
      Divider().height(10)
      Text('Test menu item 2')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
    }
    .width(100)
    .id("builder")
  }

  build() {
    Column() {
      Button("click to generate offscreen UI snapshot")
        .onClick(() => {
          // You are advised to use this.getUIContext().getComponentSnapshot().createFromBuilder().
          componentSnapshot.createFromBuilder(()=>{this.RandomBuilder()}, 320, true, {scale : 2, waitUntilRenderFinished : true})
            .then((pixmap: image.PixelMap) => {
              this.pixmap = pixmap
              // save pixmap to file
              // ....
              // get component size and location
              let info = this.getUIContext().getComponentUtils().getRectangleById("builder")
              console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y)
            }).catch((err:Error) => {
            console.log("error: " + err)
          })
        })
      Image(this.pixmap)
        .margin(10)
        .height(200)
        .width(200)
        .border({ color: Color.Black, width: 2 })
    }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300)
  }
}

componentcreate

componentSnapshot.getSync¹²⁺

getSync(id: string, options?: SnapshotOptions): image.PixelMap

Obtains the snapshot of a component that has been loaded. This API synchronously waits for the snapshot to complete and returns a PixelMap object.

NOTE

The snapshot captures content rendered in the last frame. If this API is called when the component triggers an update, the re-rendered content will not be included in the obtained snapshot.

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.
options	SnapshotOptions	No	Custom settings of the snapshot.

Return value

Type	Description
image.PixelMap	Promise used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	Invalid ID.
160002	Timeout.

Example

NOTE

Directly using componentSnapshot can lead to ambiguous instance issues. To avoid this, obtain a UIContext instance using getUIContext, and then obtain the associated componentSnapshot object using getComponentSnapshot.

import { componentSnapshot } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct SnapshotExample {
  @State pixmap: image.PixelMap|undefined = undefined

  build() {
    Column() {
      Row() {
        Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5)
        Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root")
      }
      Button("click to generate UI snapshot")
        .onClick(() => {
          try {
          // You are advised to use this.getUIContext().getComponentSnapshot().getSync().
            let pixelmap = componentSnapshot.getSync("root", {scale : 2, waitUntilRenderFinished : true})
            this.pixmap = pixelmap
          } catch (error) {
            console.error("getSync errorCode: " + error.code + " message: " + error.message)
          }
        }).margin(10)
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

componentget

SnapshotOptions¹²⁺

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
scale	number	No	Scale ratio for rendering pixel maps during a snapshot. Note that a high scale ratio may increase the time taken for the snapshot or even result in a snapshot failure. Value range: [0, +∞). If the value is less than or equal to 0, the default value is used. Default value: 1 NOTE Avoid capturing images that are excessively large, ideally not larger than the screen size. If the size of the image to capture exceeds device-specific underlying limits, the capture will fail. Atomic service API: This API can be used in atomic services since API version 12.
waitUntilRenderFinished	boolean	No	Whether to force the system to wait for all rendering commands to complete before taking the snapshot. The value true means to force the system to wait for all rendering commands to complete before taking the snapshot, and false means the opposite. This option ensures the snapshot reflects the most up-to-date content and should be enabled whenever possible. Note that enabling this option may increase the time required for the snapshot to complete, which depends on the size of the area that needs to be redrawn at the time. Default value: false Atomic service API: This API can be used in atomic services since API version 12.
region¹⁵⁺	SnapshotRegionType	No	Rectangular region for the snapshot. The default region is the entire component. Atomic service API: This API can be used in atomic services since API version 15.

SnapshotRegionType¹⁵⁺

type SnapshotRegionType = SnapshotRegion|LocalizedSnapshotRegion

Represents the region of a component to be captured in a snapshot. It can take one of the types listed in the table below.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Type	Description
SnapshotRegion	Rectangular region for capturing the component snapshot.
LocalizedSnapshotRegion	Rectangular region for capturing the component snapshot, with horizontal flipping based on the layout direction. If the layout direction is right-to-left (RTL), the specified region is flipped horizontally to accommodate the RTL layout.

SnapshotRegion¹⁵⁺

Defines the rectangular region for capturing the component snapshot.

System capability: SystemCapability.ArkUI.ArkUI.Full

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

Name	Type	Mandatory	Description
left	number	Yes	X-coordinate of the upper left corner of the rectangular region, in px.
top	number	Yes	Y-coordinate of the upper left corner of the rectangular region, in px.
right	number	Yes	X-coordinate of the lower right corner of the rectangular region, in px.
bottom	number	Yes	Y-coordinate of the lower right corner of the rectangular region, in px.

LocalizedSnapshotRegion¹⁵⁺

Defines the rectangular region for capturing the component snapshot, with coordinates adjusted based on the layout direction (LTR or RTL).

System capability: SystemCapability.ArkUI.ArkUI.Full

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

Name	Type	Mandatory	Description
start	number	Yes	For LTR layouts: X-coordinate of the upper left corner of the rectangular region, in px. For RTL layouts: X-coordinate of the lower right corner of the rectangular region, in px.
top	number	Yes	For LTR layouts: Y-coordinate of the upper left corner of the rectangular region, in px. For RTL layouts: Y-coordinate of the lower right corner of the rectangular region, in px.
end	number	Yes	For LTR layouts: X-coordinate of the upper right corner of the rectangular region, in px. For RTL layouts: X-coordinate of the lower left corner of the rectangular region, in px.
bottom	number	Yes	For LTR layouts: Y-coordinate of the upper right corner of the rectangular region, in px. For RTL layouts: Y-coordinate of the lower left corner of the rectangular region, in px.