1# @ohos.screenshot (Screenshot) 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @oh_wangxk; @logn--> 5<!--Designer: @hejunfei1991--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9The module provides the screen capture capability. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```ts 18import { screenshot } from '@kit.ArkUI'; 19``` 20 21## Rect 22 23Describes the region of the screen to capture. 24 25**Atomic service API**: This API can be used in atomic services since API version 12. 26 27**System capability**: SystemCapability.WindowManager.WindowManager.Core 28 29| Name| Type | Read-Only| Optional| Description | 30| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 31| left | number | No | No | Left boundary of the screen region to capture, in px. The value must be an integer.| 32| top | number | No | No | Top boundary of the screen region to capture, in px. The value must be an integer.| 33| width | number | No | No | Width of the screen region to capture, in px. The value must be an integer.| 34| height | number | No | No | Height of the screen region to capture, in px. The value must be an integer.| 35 36## CaptureOption<sup>14+</sup> 37 38Describes the capture options. 39 40**Atomic service API**: This API can be used in atomic services since API version 14. 41 42**System capability**: SystemCapability.WindowManager.WindowManager.Core 43 44| Name| Type | Read-Only| Optional| Description | 45| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 46| displayId | number | No | Yes| ID of the [display](js-apis-display.md#display) to capture. The default value is **0**. The value must be an integer greater than or equal to 0. If a non-integer is passed, a parameter error is reported.| 47 48## PickInfo 49 50Describes the screenshot options. 51 52**Atomic service API**: This API can be used in atomic services since API version 12. 53 54**System capability**: SystemCapability.WindowManager.WindowManager.Core 55 56| Name | Type | Read-Only| Optional| Description | 57| -------------------- | ------------- | ---- | ---- | ------------------------------------------------------------ | 58| pickRect | [Rect](#rect) | No | No | Region of the screen to capture. | 59| pixelMap | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | No | No | PixelMap object of the captured image.| 60 61## screenshot.pick 62 63pick(): Promise<PickInfo> 64 65Takes a screenshot. Currently, this API only supports taking screenshots of the screen with displayId 0. This API uses a promise to return the result. 66 67**Atomic service API**: This API can be used in atomic services since API version 12. 68 69**System capability**: SystemCapability.WindowManager.WindowManager.Core 70 71**Device behavior differences**: This API can be properly called on 2-in-1 devices. If it is called on other device types, error code 801 is returned. 72 73**Return value** 74 75| Type | Description | 76| ----------------------------- | ----------------------------------------------- | 77| Promise<[PickInfo](#pickinfo)> | Promise used to return the PickInfo object.| 78 79**Error codes** 80 81For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 82 83| ID| Error Message| 84| ------- | ----------------------- | 85| 801 | Capability not supported on this device. | 86| 1400003 | This display manager service works abnormally. | 87 88**Example** 89 90```ts 91import { BusinessError } from '@kit.BasicServicesKit'; 92 93try { 94 let promise = screenshot.pick(); 95 promise.then((pickInfo: screenshot.PickInfo) => { 96 console.log('pick Pixel bytes number: ' + pickInfo.pixelMap.getPixelBytesNumber()); 97 console.log('pick Rect: ' + pickInfo.pickRect); 98 pickInfo.pixelMap.release(); // Release the memory in time after the PixelMap is no longer needed. 99 }).catch((err: BusinessError) => { 100 console.log(`Failed to pick. Code: ' + Code: ${err.code}, message: ${err.message}`); 101 }); 102} catch (exception) { 103 console.error(`Failed to pick Code: ' + Code: ${exception.code}, message: ${exception.message}`); 104}; 105``` 106 107## screenshot.capture<sup>14+</sup> 108 109capture(options?: CaptureOption): Promise<image.PixelMap> 110 111Takes a screenshot of the entire screen. This API uses a promise to return the result. 112 113This API allows you to take screenshots of different screens by setting various **displayId** values, but only full-screen captures are supported. The [pick](#screenshotpick) API allows you to take screenshots of a specified region. 114 115**Atomic service API**: This API can be used in atomic services since API version 14. 116 117**System capability**: SystemCapability.WindowManager.WindowManager.Core 118 119**Device behavior differences**: This API can be properly called on 2-in-1 devices and tablets. If it is called on other device types, error code 801 is returned. 120 121**Required permissions**: ohos.permission.CUSTOM_SCREEN_CAPTURE 122 123**Parameters** 124 125| Name | Type | Mandatory| Description | 126| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 127| options | [CaptureOption](#captureoption14) | No| Capture options. The value can contain the display ID. If this parameter is left blank, the display with ID 0 is captured by default.| 128 129**Return value** 130 131| Type | Description | 132| ----------------------------- | ----------------------------------------------- | 133| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return a PixelMap object.| 134 135**Error codes** 136 137For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 138 139| ID| Error Message| 140| ------- | -------------------------- | 141| 201 | Permission verification failed. The application does not have the permission required to call the API.| 142| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 143| 801 | Capability not supported on this device.| 144| 1400003 | This display manager service works abnormally.| 145 146**Example** 147 148```ts 149import { BusinessError } from '@kit.BasicServicesKit'; 150import { image } from '@kit.ImageKit'; 151 152let captureOption: screenshot.CaptureOption = { 153 "displayId": 0 154}; 155try { 156 let promise = screenshot.capture(captureOption); 157 promise.then((pixelMap: image.PixelMap) => { 158 console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 159 pixelMap.release(); // Release the memory in time after the PixelMap is used. 160 }).catch((err: BusinessError) => { 161 console.error(`Failed to save screenshot. Code: ${err.code}, message: ${err.message}`); 162 }); 163} catch (exception) { 164 console.error(`Failed to save screenshot. Code: ${exception.code}, message: ${exception.message}`); 165}; 166 167```