1# @ohos.screenshot (Screenshot) 2 3The **Screenshot** module provides APIs for you to set information such as the region to capture and the size of the screen region when capturing a screen. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> The APIs provided by this module are system APIs. 10 11## Modules to Import 12 13```ts 14import screenshot from '@ohos.screenshot'; 15``` 16 17## ScreenshotOptions 18 19Describes screenshot options. 20 21**System capability**: SystemCapability.WindowManager.WindowManager.Core 22 23 24| Name | Type | Mandatory| Description | 25| ---------------------- | ------------- | ---- | ------------------------------------------------------------ | 26| screenRect | [Rect](#rect) | No | Region of the screen to capture. If this parameter is null, the full screen will be captured. | 27| imageSize | [Size](#size) | No | Size of the screen region to capture. If this parameter is null, the full screen will be captured. | 28| rotation | number | No | Rotation angle of the screenshot. Currently, the value can be **0** only. The default value is **0**. The value must be an integer. | 29| displayId<sup>8+</sup> | number | No | ID of the [display](js-apis-display.md#display) device on which the screen region is to be captured. The value must be an integer.| 30 31 32## Rect 33 34Describes the region of the screen to capture. 35 36**System capability**: SystemCapability.WindowManager.WindowManager.Core 37 38| Name| Type | Mandatory| Description | 39| ------ | ------ | ---- | ------------------------------------------------------------ | 40| left | number | Yes | Left boundary of the screen region to capture, in px. The value must be an integer.| 41| top | number | Yes | Top boundary of the screen region to capture, in px. The value must be an integer.| 42| width | number | Yes | Width of the screen region to capture, in px. The value must be an integer.| 43| height | number | Yes | Height of the screen region to capture, in px. The value must be an integer.| 44 45 46## Size 47 48Describes the size of the screen region to capture. 49 50**System capability**: SystemCapability.WindowManager.WindowManager.Core 51 52| Name| Type | Mandatory| Description | 53| ------ | ------ | ---- | ------------------------------------------------------------ | 54| width | number | Yes | Width of the screen region to capture, in px. The value must be an integer.| 55| height | number | Yes | Height of the screen region to capture, in px. The value must be an integer.| 56 57## screenshot.save 58 59save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>): void 60 61Takes a screenshot and saves it as a **PixelMap** object. This API uses an asynchronous callback to return the result. 62 63**System capability**: SystemCapability.WindowManager.WindowManager.Core 64 65**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 66 67**Parameters** 68 69| Name | Type | Mandatory| Description | 70| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 71| options | [ScreenshotOptions](#screenshotoptions) | Yes | Screenshot settings consist of **screenRect**, **imageSize**, **rotation**, and **displayId**. You can set the parameters separately.| 72| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback used to return a **PixelMap** object. | 73 74**Error codes** 75 76For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 77 78| ID| Error Message| 79| ------- | -------------------------- | 80| 1400001 | Invalid display or screen. | 81 82**Example** 83 84```ts 85import { BusinessError } from '@ohos.base'; 86 87let screenshotOptions: screenshot.ScreenshotOptions = { 88 "screenRect": { 89 "left": 200, 90 "top": 100, 91 "width": 200, 92 "height": 200 }, 93 "imageSize": { 94 "width": 300, 95 "height": 300 }, 96 "rotation": 0, 97 "displayId": 0 98}; 99try { 100 screenshot.save(screenshotOptions, (err: BusinessError, pixelMap) => { 101 if (err) { 102 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 103 return; 104 } 105 console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 106 pixelMap.release(); // Release the memory in time after the PixelMap is used. 107 }); 108} catch (exception) { 109 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 110}; 111``` 112 113## screenshot.save 114 115save(callback: AsyncCallback<image.PixelMap>): void 116 117Takes a screenshot and saves it as a **PixelMap** object. This API uses an asynchronous callback to return the result. 118 119**System capability**: SystemCapability.WindowManager.WindowManager.Core 120 121**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 122 123**Parameters** 124 125| Name | Type | Mandatory| Description | 126| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 127| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback used to return a **PixelMap** object. | 128 129**Example** 130 131```ts 132import { BusinessError } from '@ohos.base'; 133 134try { 135 screenshot.save((err: BusinessError, pixelMap) => { 136 if (err) { 137 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 138 return; 139 } 140 console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 141 pixelMap.release(); // Release the memory in time after the PixelMap is used. 142 }); 143} catch (exception) { 144 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 145}; 146``` 147 148## screenshot.save 149 150save(options?: ScreenshotOptions): Promise<image.PixelMap> 151 152Takes a screenshot and saves it as a **PixelMap** object. This API uses a promise to return the result. 153 154**System capability**: SystemCapability.WindowManager.WindowManager.Core 155 156**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 157 158**Parameters** 159 160| Name | Type | Mandatory| Description | 161| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 162| options | [ScreenshotOptions](#screenshotoptions) | No | Screenshot settings consist of **screenRect**, **imageSize**, **rotation**, and **displayId**. You can set the parameters separately.| 163 164**Return value** 165 166| Type | Description | 167| ----------------------------- | ----------------------------------------------- | 168| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return a **PixelMap** object.| 169 170**Example** 171 172```ts 173import { BusinessError } from '@ohos.base'; 174 175let screenshotOptions: screenshot.ScreenshotOptions = { 176 "screenRect": { 177 "left": 200, 178 "top": 100, 179 "width": 200, 180 "height": 200 }, 181 "imageSize": { 182 "width": 300, 183 "height": 300 }, 184 "rotation": 0, 185 "displayId": 0 186}; 187try { 188 let promise = screenshot.save(screenshotOptions); 189 promise.then((pixelMap) => { 190 console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 191 pixelMap.release(); // Release the memory in time after the PixelMap is used. 192 }).catch((err: BusinessError) => { 193 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 194 }); 195} catch (exception) { 196 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 197}; 198``` 199