1# @ohos.screenshot (Screenshot) (System API) 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 APIs for you to set information such as the region to capture and the size of the screen region when capturing a screen. 10 11> **NOTE** 12> 13> 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. 14> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.screenshot](js-apis-screenshot.md). 15 16## Modules to Import 17 18```ts 19import { screenshot } from '@kit.ArkUI'; 20``` 21 22## ScreenshotOptions 23 24Describes the screenshot options. 25 26**System API**: This is a system API. 27 28**System capability**: SystemCapability.WindowManager.WindowManager.Core 29 30| Name | Type | Read-Only| Optional| Description | 31| ---------------------- | ------------- | ---- | ---- | ------------------------------------------------------------ | 32| screenRect | [Rect](js-apis-screenshot.md#rect) | No | Yes| Region of the screen to capture. If no value is passed, the region of the logical screen associated with the specified display ID is returned. | 33| imageSize | [Size](#size) | No| Yes | Size of the captured image. If no value is passed, the size of the logical screen associated with the specified display ID is returned. If **screenRect** is smaller than **imageSize**, the image is stretched to **imageSize**; otherwise, it is compressed to **imageSize**. | 34| rotation | number | No | Yes| Angle by which the captured image should be rotated. Currently, the value can be **0** only. The default value is **0**. | 35| displayId<sup>8+</sup> | number | No| Yes | 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.| 36| isNotificationNeeded<sup>14+</sup>| boolean | No | Yes| Whether to send a notification after a snapshot is captured. **true** to send, **false** otherwise. The default value is **true**. Such a notification can be listened for through [captureStatusChange](js-apis-display.md#displayoncapturestatuschange12). | 37| isCaptureFullOfScreen<sup>20+</sup> | boolean | No | Yes| Whether to capture all displays on the current screen. If the screen contains multiple displays, the value **true** means that the entire screen is captured, and **false** means that only the region of the logical screen associated with the specified display ID is captured.| 38 39## HdrScreenshotOptions<sup>20+</sup> 40 41Describes the HDR screenshot options. 42 43**System API**: This is a system API. 44 45**System capability**: SystemCapability.Window.SessionManager 46 47| Name | Type | Read-Only| Optional| Description | 48| ---------------------- | ------------- |---| ---- | ------------------------------------------------------------ | 49| displayId | number | No| Yes | 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. The default value is **0**.| 50| isNotificationNeeded| boolean | No| Yes | Whether to send a notification after a snapshot is captured. **true** to send, **false** otherwise. The default value is **true**. Such a notification can be listened for through [captureStatusChange](js-apis-display.md#displayoncapturestatuschange12). | 51| isCaptureFullOfScreen | boolean | No| Yes | Whether to capture all displays on the current screen. If the screen contains multiple displays, the value **true** means that the entire screen is captured, and **false** means that only the region of the logical screen associated with the specified display ID is captured. The default value is **false**.| 52 53## Size 54 55Describes the size of the screen region to capture. 56 57**System API**: This is a system API. 58 59**System capability**: SystemCapability.WindowManager.WindowManager.Core 60 61| Name | Type | Read-Only| Optional| Description | 62| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 63| width | number | No | No | Width of the screen region to capture, in px. The value must be an integer.| 64| height | number | No | No | Height of the screen region to capture, in px. The value must be an integer.| 65 66## screenshot.save 67 68save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>): void 69 70Takes a screenshot. This API uses an asynchronous callback to return the result. 71 72**System API**: This is a system API. 73 74**System capability**: SystemCapability.WindowManager.WindowManager.Core 75 76**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 82| options | [ScreenshotOptions](#screenshotoptions) | Yes | Information about the snapshot. If the screen to capture is a virtual screen, the snapshot is a white screen.| 83| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Yes | Callback used to return a PixelMap object. The size of the PixelMap object is **imageSize**. If **imageSize** is not specified, the size of the logical screen associated with the specified display ID is used. | 84 85**Error codes** 86 87For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 88 89| ID| Error Message| 90| ------- | -------------------------- | 91| 201 | Permission verification failed. The application does not have the permission required to call the API.| 92| 202 | Permission verification failed. A non-system application calls a system API.| 93| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 94| 1400001 | Invalid display or screen. | 95 96**Example** 97 98```ts 99import { BusinessError } from '@kit.BasicServicesKit'; 100import { image } from '@kit.ImageKit'; 101 102let screenshotOptions: screenshot.ScreenshotOptions = { 103 "screenRect": { 104 "left": 200, 105 "top": 100, 106 "width": 200, 107 "height": 200 }, 108 "imageSize": { 109 "width": 300, 110 "height": 300 }, 111 "rotation": 0, 112 "displayId": 0, 113 "isNotificationNeeded": true, 114 "isCaptureFullOfScreen": true 115}; 116screenshot.save(screenshotOptions, (err: BusinessError, pixelMap: image.PixelMap) => { 117 if (err) { 118 console.error('Failed to save screenshot. Code: ' + JSON.stringify(err)); 119 return; 120 } 121 console.info('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 122 pixelMap.release(); // Release the memory in time after the PixelMap is used. 123}); 124``` 125 126## screenshot.save 127 128save(callback: AsyncCallback<image.PixelMap>): void 129 130Takes a screenshot. This API uses an asynchronous callback to return the result. 131 132**System API**: This is a system API. 133 134**System capability**: SystemCapability.WindowManager.WindowManager.Core 135 136**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 137 138**Parameters** 139 140| Name | Type | Mandatory| Description | 141| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 142| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Yes | Callback used to return a PixelMap object. | 143 144 145**Error codes** 146 147For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 148 149| ID| Error Message| 150| ------- | -------------------------- | 151| 201 | Permission verification failed. The application does not have the permission required to call the API.| 152| 202 | Permission verification failed. A non-system application calls a system API.| 153 154**Example** 155 156```ts 157import { BusinessError } from '@kit.BasicServicesKit'; 158import { image } from '@kit.ImageKit'; 159 160screenshot.save((err: BusinessError, pixelMap: image.PixelMap) => { 161 if (err) { 162 console.error('Failed to save screenshot. Code: ' + JSON.stringify(err)); 163 return; 164 } 165 console.info('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 166 pixelMap.release(); // Release the memory in time after the PixelMap is used. 167}); 168``` 169 170## screenshot.save 171 172save(options?: ScreenshotOptions): Promise<image.PixelMap> 173 174Takes a screenshot. This API uses a promise to return the result. 175 176**System API**: This is a system API. 177 178**System capability**: SystemCapability.WindowManager.WindowManager.Core 179 180**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 181 182**Parameters** 183 184| Name | Type | Mandatory| Description | 185| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 186| options | [ScreenshotOptions](#screenshotoptions) | No | Information about the snapshot. If the screen to capture is a virtual screen, the snapshot is a white screen.| 187 188**Return value** 189 190| Type | Description | 191| ----------------------------- | ----------------------------------------------- | 192| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return a PixelMap object.| 193 194 195**Error codes** 196 197For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 198 199| ID| Error Message| 200| ------- | -------------------------- | 201| 201 | Permission verification failed. The application does not have the permission required to call the API.| 202| 202 | Permission verification failed. A non-system application calls a system API.| 203| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 204 205**Example** 206 207```ts 208import { BusinessError } from '@kit.BasicServicesKit'; 209import { image } from '@kit.ImageKit'; 210 211let screenshotOptions: screenshot.ScreenshotOptions = { 212 "screenRect": { 213 "left": 200, 214 "top": 100, 215 "width": 200, 216 "height": 200 }, 217 "imageSize": { 218 "width": 300, 219 "height": 300 }, 220 "rotation": 0, 221 "displayId": 0, 222 "isNotificationNeeded": true, 223 "isCaptureFullOfScreen": true 224}; 225try { 226 let promise = screenshot.save(screenshotOptions); 227 promise.then((pixelMap: image.PixelMap) => { 228 console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 229 pixelMap.release(); // Release the memory in time after the PixelMap is used. 230 }).catch((err: BusinessError) => { 231 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 232 }); 233} catch (exception) { 234 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 235}; 236``` 237 238## screenshot.saveHdrPicture<sup>20+</sup> 239 240saveHdrPicture(options?: HdrScreenshotOptions): Promise<Array<image.PixelMap>> 241 242Takes a screenshot. This API uses a promise to return the result. SDR stands for Standard Dynamic Range, and HDR stands for High Dynamic Range. 243- If the screen contains HDR resources (even if they are partially obscured), this API returns an array with both SDR and HDR PixelMaps, regardless of whether HDR is enabled. 244- If there are no HDR resources, it returns an array with a single SDR PixelMap. Unlike the [save](#screenshotsave) API, which returns a single SDR PixelMap, this API always returns an array. Additionally, this API does not support cropping, stretching, or rotating features available in the [save](#screenshotsave) API. 245<br><br> 246 247**System API**: This is a system API. 248 249**System capability**: SystemCapability.Window.SessionManager 250 251**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 252 253**Parameters** 254 255| Name | Type | Mandatory| Description | 256| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 257| options | [HdrScreenshotOptions](#hdrscreenshotoptions20) | No | Information about the HDR snapshot. This parameter is left unspecified by default.| 258 259**Return value** 260 261| Type | Description | 262| ----------------------------- | ----------------------------------------------- | 263| Promise<Array<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)>> | Promise used to an array of PixelMap objects. If the screen contains HDR resources (even if they are partially obscured), the array contains two PixelMaps: the first is an SDR PixelMap, and the second is an HDR PixelMap. If there are no HDR resources, the array contains a single SDR PixelMap.| 264 265**Error codes** 266 267For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 268 269| ID| Error Message| 270| ------- | -------------------------- | 271| 201 | Permission verification failed.The application does not have the permission required to call the API.| 272| 202 | Permission verification failed. A non-system application calls a system API.| 273| 801 | Capability not supported. Failed to call the API due to limited device capabilities.| 274| 1400001 | Invalid display or screen.| 275| 1400003 | This display manager service works abnormally.| 276| 1400004 | Parameter error. Possible cause: 1.Invalid parameter range.| 277 278**Example** 279 280```ts 281import { BusinessError } from '@kit.BasicServicesKit'; 282import { image } from '@kit.ImageKit'; 283 284let hdrScreenshotOptions: screenshot.HdrScreenshotOptions = { 285 "displayId": 0, 286 "isNotificationNeeded": true, 287 "isCaptureFullOfScreen": true 288}; 289try { 290 let promise = screenshot.saveHdrPicture(hdrScreenshotOptions); 291 promise.then((pixelMapArray: Array<image.PixelMap>) => { 292 for (let i = 0; i < pixelMapArray.length; i++) { 293 const pixelMap = pixelMapArray[i]; 294 console.info('succeeded in saving screenshot ${i}. Pixel bytes number' + pixelMap.getPixelBytesNumber()); 295 pixelMap.release(); 296 } 297 }).catch((err: BusinessError) => { 298 console.error('Failed to save SDR and HDR screenshot. Code: ' + JSON.stringify(err)); 299 }); 300} catch (exception) { 301 console.error('Failed to save SDR and HDR screenshot. Code: ' + JSON.stringify(exception)); 302}; 303``` 304