1# @ohos.arkui.componentSnapshot (Component Snapshot) 2 3The **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. 4 5Transformation 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. 6 7> **NOTE** 8> 9> 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. 10> 11>In scenarios where [XComponent](arkui-ts/ts-basic-components-xcomponent.md) is used to, for example, display video or camera streams, obtain images through [surface](../apis-image-kit/js-apis-image.md#imagecreatepixelmapfromsurface11), instead of through an API in this module. 12> 13>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](arkui-ts/ts-universal-attributes-image-effect.md) 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](js-apis-window.md#snapshot9). 14> 15> You can preview how this component looks on a real device, but not in DevEco Studio Previewer. 16 17 18## Modules to Import 19 20```ts 21import { componentSnapshot } from '@kit.ArkUI'; 22``` 23 24## componentSnapshot.get<sup>(deprecated)</sup> 25 26get(id: string, callback: AsyncCallback<image.PixelMap>, options?: SnapshotOptions): void 27 28Obtains the snapshot of a component that has been loaded. This API uses an asynchronous callback to return the result. 29 30> **NOTE** 31> 32> This API is deprecated since API version 18. You are advised to use [get](js-apis-arkui-UIContext.md#get12) instead on the obtained [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object. 33> 34> Since API version 12, you can use the [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object associated with the current UI context. 35> 36> 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. 37 38**Atomic service API**: This API can be used in atomic services since API version 12. 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42**Parameters** 43 44| Name | Type | Mandatory | Description | 45| -------- | ----------------------------------- | ---- | ---------------------------------------- | 46| id | string | Yes | [ID](arkui-ts/ts-universal-attributes-component-id.md) of the target component.| 47| callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. | 48| options<sup>12+</sup> | [SnapshotOptions](#snapshotoptions12) | No | Custom settings of the snapshot.| 49 50**Error codes** 51 52For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 53 54| ID| Error Message | 55| -------- | ------------------- | 56| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 57| 100001 | Invalid ID. | 58 59**Example** 60 61> **NOTE** 62> 63> Directly using **componentSnapshot** can lead to [ambiguous instance issues](../../ui/arkts-global-interface.md). To avoid this, obtain a **UIContext** instance using [getUIContext](js-apis-arkui-UIContext.md#uicontext), and then obtain the associated **componentSnapshot** object using [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12). 64 65```ts 66import { componentSnapshot } from '@kit.ArkUI'; 67import { image } from '@kit.ImageKit'; 68 69@Entry 70@Component 71struct SnapshotExample { 72 @State pixmap: image.PixelMap | undefined = undefined 73 74 build() { 75 Column() { 76 Row() { 77 Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5) 78 Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root") 79 } 80 Button("click to generate UI snapshot") 81 .onClick(() => { 82 // You are advised to use this.getUIContext().getComponentSnapshot().get(). 83 componentSnapshot.get("root", (error: Error, pixmap: image.PixelMap) => { 84 if (error) { 85 console.log("error: " + JSON.stringify(error)) 86 return; 87 } 88 this.pixmap = pixmap 89 }, {scale : 2, waitUntilRenderFinished : true}) 90 }).margin(10) 91 } 92 .width('100%') 93 .height('100%') 94 .alignItems(HorizontalAlign.Center) 95 } 96} 97``` 98 99 100 101## componentSnapshot.get<sup>(deprecated)</sup> 102 103get(id: string, options?: SnapshotOptions): Promise<image.PixelMap> 104 105Obtains the snapshot of a component that has been loaded. This API uses a promise to return the result. 106 107> **NOTE** 108> 109> This API is deprecated since API version 18. You are advised to use [get](js-apis-arkui-UIContext.md#get12-1) instead on the obtained [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object. 110> 111> Since API version 12, you can use the [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object associated with the current UI context. 112> 113> 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. 114 115**Atomic service API**: This API can be used in atomic services since API version 12. 116 117**System capability**: SystemCapability.ArkUI.ArkUI.Full 118 119**Parameters** 120 121| Name | Type | Mandatory | Description | 122| ---- | ------ | ---- | ---------------------------------------- | 123| id | string | Yes | [ID](arkui-ts/ts-universal-attributes-component-id.md) of the target component.| 124| options<sup>12+</sup> | [SnapshotOptions](#snapshotoptions12) | No | Custom settings of the snapshot.| 125 126**Return value** 127 128| Type | Description | 129| ----------------------------- | -------- | 130| Promise<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the result.| 131 132**Error codes** 133 134For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 135 136| ID | Error Message | 137| ------ | ------------------- | 138| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 139| 100001 | Invalid ID. | 140 141**Example** 142 143> **NOTE** 144> 145> Directly using **componentSnapshot** can lead to [ambiguous instance issues](../../ui/arkts-global-interface.md). To avoid this, obtain a **UIContext** instance using [getUIContext](js-apis-arkui-UIContext.md#uicontext), and then obtain the associated **componentSnapshot** object using [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12). 146 147```ts 148import { componentSnapshot } from '@kit.ArkUI'; 149import { image } from '@kit.ImageKit'; 150 151@Entry 152@Component 153struct SnapshotExample { 154 @State pixmap: image.PixelMap | undefined = undefined 155 156 build() { 157 Column() { 158 Row() { 159 Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5) 160 Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root") 161 } 162 Button("click to generate UI snapshot") 163 .onClick(() => { 164 // You are advised to use this.getUIContext().getComponentSnapshot().get(). 165 componentSnapshot.get("root", {scale : 2, waitUntilRenderFinished : true}) 166 .then((pixmap: image.PixelMap) => { 167 this.pixmap = pixmap 168 }).catch((err:Error) => { 169 console.log("error: " + err) 170 }) 171 }).margin(10) 172 } 173 .width('100%') 174 .height('100%') 175 .alignItems(HorizontalAlign.Center) 176 } 177} 178``` 179 180 181 182## componentSnapshot.createFromBuilder<sup>(deprecated)</sup> 183 184createFromBuilder(builder: CustomBuilder, callback: AsyncCallback<image.PixelMap>, delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): void 185 186Renders 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. 187 188> **NOTE** 189> 190> This API is deprecated since API version 18. You are advised to use [createFromBuilder](js-apis-arkui-UIContext.md#createfrombuilder12) instead on the obtained [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object. 191> 192> Since API version 12, you can use the [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object associated with the current UI context. 193> 194> 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. 195> 196> Components in the builder do not support the setting of animation-related attributes, such as [transition](arkui-ts/ts-transition-animation-component.md). 197> 198> If a component is on a time-consuming task, for example, an [Image](arkui-ts/ts-basic-components-image.md) or [Web](../apis-arkweb/ts-basic-components-web.md) 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. 199 200**Atomic service API**: This API can be used in atomic services since API version 12. 201 202**System capability**: SystemCapability.ArkUI.ArkUI.Full 203 204**Parameters** 205 206| Name | Type | Mandatory | Description | 207| -------- | ---------------------------------------- | ---- | ---------- | 208| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | Yes | Builder of the custom component.<br>**NOTE**<br>The global builder is not supported.| 209| callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. The coordinates and size of the offscreen component's drawing area can be obtained through the callback.| 210| delay<sup>12+</sup> | 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.<br> 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.<br>**NOTE**<br>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.<br> Default value: **300**<br> Unit: ms<br> Value range: [0, +∞). If the value is less than 0, the default value is used.| 211| checkImageStatus<sup>12+</sup> | 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.<br>Default value: **false**| 212| options<sup>12+</sup> | [SnapshotOptions](#snapshotoptions12) | No | Custom settings of the snapshot.| 213 214**Error codes** 215 216For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 217 218| ID| Error Message | 219| -------- | ------------------------------------------------------------ | 220| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 221| 100001 | The builder is not a valid build function. | 222| 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. | 223 224**Example** 225 226> **NOTE** 227> 228> Directly using **componentSnapshot** can lead to [ambiguous instance issues](../../ui/arkts-global-interface.md). To avoid this, obtain a **UIContext** instance using [getUIContext](js-apis-arkui-UIContext.md#uicontext), and then obtain the associated **componentSnapshot** object using [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12). 229 230```ts 231import { componentSnapshot } from '@kit.ArkUI'; 232import { image } from '@kit.ImageKit'; 233 234@Entry 235@Component 236struct OffscreenSnapshotExample { 237 @State pixmap: image.PixelMap | undefined = undefined 238 239 @Builder 240 RandomBuilder() { 241 Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 242 Text('Test menu item 1') 243 .fontSize(20) 244 .width(100) 245 .height(50) 246 .textAlign(TextAlign.Center) 247 Divider().height(10) 248 Text('Test menu item 2') 249 .fontSize(20) 250 .width(100) 251 .height(50) 252 .textAlign(TextAlign.Center) 253 } 254 .width(100) 255 .id("builder") 256 } 257 258 build() { 259 Column() { 260 Button("click to generate offscreen UI snapshot") 261 .onClick(() => { 262 // You are advised to use this.getUIContext().getComponentSnapshot().createFromBuilder(). 263 componentSnapshot.createFromBuilder(()=>{this.RandomBuilder()}, 264 (error: Error, pixmap: image.PixelMap) => { 265 if(error){ 266 console.log("error: " + JSON.stringify(error)) 267 return; 268 } 269 this.pixmap = pixmap 270 // save pixmap to file 271 // .... 272 // get component size and location 273 let info = this.getUIContext().getComponentUtils().getRectangleById("builder") 274 console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y) 275 }, 320, true, {scale : 2, waitUntilRenderFinished : true}) 276 }) 277 Image(this.pixmap) 278 .margin(10) 279 .height(200) 280 .width(200) 281 .border({ color: Color.Black, width: 2 }) 282 }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300) 283 } 284} 285``` 286 287 288 289## componentSnapshot.createFromBuilder<sup>(deprecated)</sup> 290 291createFromBuilder(builder: CustomBuilder, delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): Promise<image.PixelMap> 292 293Renders 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. 294 295> **NOTE** 296> 297> This API is deprecated since API version 18. You are advised to use [createFromBuilder](js-apis-arkui-UIContext.md#createfrombuilder12-1)instead on the obtained [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object. 298> 299> Since API version 12, you can use the [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) object associated with the current UI context. 300> 301> 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. 302> 303> Components in the builder do not support the setting of animation-related attributes, such as [transition](arkui-ts/ts-transition-animation-component.md). 304> 305> If a component is on a time-consuming task, for example, an [Image](arkui-ts/ts-basic-components-image.md) or [Web](../apis-arkweb/ts-basic-components-web.md) 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. 306 307**Atomic service API**: This API can be used in atomic services since API version 12. 308 309**System capability**: SystemCapability.ArkUI.ArkUI.Full 310 311**Parameters** 312 313| Name | Type | Mandatory | Description | 314| ------- | ---------------------------------------- | ---- | ---------- | 315| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | Yes | Builder of the custom component.<br>**NOTE**<br>The global builder is not supported.| 316| delay<sup>12+</sup> | 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.<br> 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.<br>**NOTE**<br>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.<br> Default value: **300**<br> Unit: ms| 317| checkImageStatus<sup>12+</sup> | 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.<br>Default value: **false**| 318| options<sup>12+</sup> | [SnapshotOptions](#snapshotoptions12) | No | Custom settings of the snapshot.| 319 320**Return value** 321 322| Type | Description | 323| ----------------------------- | -------- | 324| Promise<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the result.| 325 326**Error codes** 327For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 328 329| ID | Error Message | 330| ------ | ---------------------------------------- | 331| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 332| 100001 | The builder is not a valid build function. | 333| 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. | 334 335**Example** 336 337> **NOTE** 338> 339> Directly using **componentSnapshot** can lead to [ambiguous instance issues](../../ui/arkts-global-interface.md). To avoid this, obtain a **UIContext** instance using [getUIContext](js-apis-arkui-UIContext.md#uicontext), and then obtain the associated **componentSnapshot** object using [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12). 340 341```ts 342import { componentSnapshot } from '@kit.ArkUI' 343import { image } from '@kit.ImageKit' 344 345@Entry 346@Component 347struct OffscreenSnapshotExample { 348 @State pixmap: image.PixelMap | undefined = undefined 349 350 @Builder 351 RandomBuilder() { 352 Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 353 Text('Test menu item 1') 354 .fontSize(20) 355 .width(100) 356 .height(50) 357 .textAlign(TextAlign.Center) 358 Divider().height(10) 359 Text('Test menu item 2') 360 .fontSize(20) 361 .width(100) 362 .height(50) 363 .textAlign(TextAlign.Center) 364 } 365 .width(100) 366 .id("builder") 367 } 368 369 build() { 370 Column() { 371 Button("click to generate offscreen UI snapshot") 372 .onClick(() => { 373 // You are advised to use this.getUIContext().getComponentSnapshot().createFromBuilder(). 374 componentSnapshot.createFromBuilder(()=>{this.RandomBuilder()}, 320, true, {scale : 2, waitUntilRenderFinished : true}) 375 .then((pixmap: image.PixelMap) => { 376 this.pixmap = pixmap 377 // save pixmap to file 378 // .... 379 // get component size and location 380 let info = this.getUIContext().getComponentUtils().getRectangleById("builder") 381 console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y) 382 }).catch((err:Error) => { 383 console.log("error: " + err) 384 }) 385 }) 386 Image(this.pixmap) 387 .margin(10) 388 .height(200) 389 .width(200) 390 .border({ color: Color.Black, width: 2 }) 391 }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300) 392 } 393} 394``` 395 396 397 398## componentSnapshot.getSync<sup>12+</sup> 399 400getSync(id: string, options?: SnapshotOptions): image.PixelMap 401 402Obtains the snapshot of a component that has been loaded. This API synchronously waits for the snapshot to complete and returns a [PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) object. 403 404> **NOTE** 405> 406> 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. 407 408**Atomic service API**: This API can be used in atomic services since API version 12. 409 410**System capability**: SystemCapability.ArkUI.ArkUI.Full 411 412**Parameters** 413 414| Name | Type | Mandatory | Description | 415| ---- | ------ | ---- | ---------------------------------------- | 416| id | string | Yes | [ID](arkui-ts/ts-universal-attributes-component-id.md) of the target component.| 417| options | [SnapshotOptions](#snapshotoptions12) | No | Custom settings of the snapshot.| 418 419**Return value** 420 421| Type | Description | 422| ----------------------------- | -------- | 423| image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Promise used to return the result.| 424 425**Error codes** 426 427For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 428 429| ID | Error Message | 430| ------ | ------------------- | 431| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 432| 100001 | Invalid ID. | 433| 160002 | Timeout. | 434 435**Example** 436 437> **NOTE** 438> 439> Directly using **componentSnapshot** can lead to [ambiguous instance issues](../../ui/arkts-global-interface.md). To avoid this, obtain a **UIContext** instance using [getUIContext](js-apis-arkui-UIContext.md#uicontext), and then obtain the associated **componentSnapshot** object using [getComponentSnapshot](js-apis-arkui-UIContext.md#getcomponentsnapshot12). 440 441```ts 442import { componentSnapshot } from '@kit.ArkUI'; 443import { image } from '@kit.ImageKit'; 444 445@Entry 446@Component 447struct SnapshotExample { 448 @State pixmap: image.PixelMap | undefined = undefined 449 450 build() { 451 Column() { 452 Row() { 453 Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5) 454 Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root") 455 } 456 Button("click to generate UI snapshot") 457 .onClick(() => { 458 try { 459 // You are advised to use this.getUIContext().getComponentSnapshot().getSync(). 460 let pixelmap = componentSnapshot.getSync("root", {scale : 2, waitUntilRenderFinished : true}) 461 this.pixmap = pixelmap 462 } catch (error) { 463 console.error("getSync errorCode: " + error.code + " message: " + error.message) 464 } 465 }).margin(10) 466 } 467 .width('100%') 468 .height('100%') 469 .alignItems(HorizontalAlign.Center) 470 } 471} 472``` 473 474 475 476## SnapshotOptions<sup>12+</sup> 477 478**System capability**: SystemCapability.ArkUI.ArkUI.Full 479 480| Name | Type | Mandatory | Description | 481| ---------------|------------ | -----------------------------| -----------------------------| 482| 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.<br>Value range: [0, +∞). If the value is less than or equal to 0, the default value is used.<br> Default value: **1**<br>**NOTE**<br>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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 483| 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.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 484| region<sup>15+</sup> | [SnapshotRegionType](#snapshotregiontype15) | No| Rectangular region for the snapshot. The default region is the entire component.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 485 486## SnapshotRegionType<sup>15+</sup> 487 488type SnapshotRegionType = SnapshotRegion | LocalizedSnapshotRegion 489 490Represents the region of a component to be captured in a snapshot. It can take one of the types listed in the table below. 491 492**Atomic service API**: This API can be used in atomic services since API version 15. 493 494**System capability**: SystemCapability.ArkUI.ArkUI.Full 495 496| Type | Description | 497| ------ | ------ | 498| [SnapshotRegion](#snapshotregion15) | Rectangular region for capturing the component snapshot.| 499| [LocalizedSnapshotRegion ](#localizedsnapshotregion15) | 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.| 500 501## SnapshotRegion<sup>15+</sup> 502 503Defines the rectangular region for capturing the component snapshot. 504 505**System capability**: SystemCapability.ArkUI.ArkUI.Full 506 507**Atomic service API**: This API can be used in atomic services since API version 15. 508 509| Name | Type | Mandatory| Description | 510| ------ | ------ | ---- | --------------------------------------- | 511| left | number | Yes | X-coordinate of the upper left corner of the rectangular region, in px.| 512| top | number | Yes | Y-coordinate of the upper left corner of the rectangular region, in px.| 513| right | number | Yes | X-coordinate of the lower right corner of the rectangular region, in px.| 514| bottom | number | Yes | Y-coordinate of the lower right corner of the rectangular region, in px.| 515 516## LocalizedSnapshotRegion<sup>15+</sup> 517 518Defines the rectangular region for capturing the component snapshot, with coordinates adjusted based on the layout direction (LTR or RTL). 519 520**System capability**: SystemCapability.ArkUI.ArkUI.Full 521 522**Atomic service API**: This API can be used in atomic services since API version 15. 523 524| Name | Type | Mandatory| Description | 525| ------ | ------ | ---- | ------------------------------------------------------------ | 526| start | number | Yes | For LTR layouts: X-coordinate of the upper left corner of the rectangular region, in px.<br>For RTL layouts: X-coordinate of the lower right corner of the rectangular region, in px.| 527| top | number | Yes | For LTR layouts: Y-coordinate of the upper left corner of the rectangular region, in px.<br>For RTL layouts: Y-coordinate of the lower right corner of the rectangular region, in px.| 528| end | number | Yes | For LTR layouts: X-coordinate of the upper right corner of the rectangular region, in px.<br>For RTL layouts: X-coordinate of the lower left corner of the rectangular region, in px.| 529| bottom | number | Yes | For LTR layouts: Y-coordinate of the upper right corner of the rectangular region, in px.<br>For RTL layouts: Y-coordinate of the lower left corner of the rectangular region, in px.| 530
