1# @ohos.screenshot (Screenshot)
2
3The **Screenshot** module provides the screen capture capability.
4
5>  **NOTE**
6>
7> 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.
8
9## Modules to Import
10
11```ts
12import { screenshot } from '@kit.ArkUI';
13```
14
15## Rect
16
17Describes the region of the screen to capture.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.WindowManager.WindowManager.Core
22
23| Name| Type  | Mandatory| Description                                                        |
24| ------ | ------ | ---- | ------------------------------------------------------------ |
25| left   | number | Yes  | Left boundary of the screen region to capture, in px. The value must be an integer.|
26| top    | number | Yes  | Top boundary of the screen region to capture, in px. The value must be an integer.|
27| width  | number | Yes  | Width of the screen region to capture, in px. The value must be an integer.|
28| height | number | Yes  | Height of the screen region to capture, in px. The value must be an integer.|
29
30## CaptureOption<sup>14+</sup>
31
32Describes the capture options.
33
34**Atomic service API**: This API can be used in atomic services since API version 14.
35
36**System capability**: SystemCapability.WindowManager.WindowManager.Core
37
38| Name| Type  | Mandatory| Description                                                        |
39| ------ | ------ | ---- | ------------------------------------------------------------ |
40| displayId | number | No| 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.|
41
42## PickInfo
43
44Describes the screenshot options.
45
46**Atomic service API**: This API can be used in atomic services since API version 12.
47
48**System capability**: SystemCapability.WindowManager.WindowManager.Core
49
50| Name                | Type         | Mandatory| Description                                                        |
51| -------------------- | ------------- | ---- | ------------------------------------------------------------ |
52| pickRect             | [Rect](#rect) | Yes  | Region of the screen to capture.                      |
53| pixelMap             | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)  | Yes  | **PixelMap** object of the captured image.|
54
55## screenshot.pick
56
57pick(): Promise&lt;PickInfo&gt;
58
59Takes a screenshot. This API can be used only on 2-in-1 devices.
60
61**Atomic service API**: This API can be used in atomic services since API version 12.
62
63**System capability**: SystemCapability.WindowManager.WindowManager.Core
64
65**Return value**
66
67| Type                         | Description                                           |
68| ----------------------------- | ----------------------------------------------- |
69| Promise&lt;[PickInfo](#pickinfo)&gt; | Promise used to return the **PickInfo** object.|
70
71**Error codes**
72
73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
74
75| ID| Error Message|
76| ------- | ----------------------- |
77| 801 | Capability not supported on this device. |
78| 1400003 | This display manager service works abnormally. |
79
80**Example**
81
82```ts
83import { BusinessError } from '@kit.BasicServicesKit';
84
85try {
86  let promise = screenshot.pick();
87  promise.then((pickInfo: screenshot.PickInfo) => {
88    console.log('pick Pixel bytes number: ' + pickInfo.pixelMap.getPixelBytesNumber());
89    console.log('pick Rect: ' + pickInfo.pickRect);
90    pickInfo.pixelMap.release(); // Release the memory in time after the PixelMap is no longer needed.
91  }).catch((err: BusinessError) => {
92    console.log('Failed to pick. Code: ' + JSON.stringify(err));
93  });
94} catch (exception) {
95  console.error('Failed to pick Code: ' + JSON.stringify(exception));
96};
97```
98
99## screenshot.capture<sup>14+</sup>
100
101capture(options?: CaptureOption): Promise&lt;image.PixelMap&gt;
102
103Takes a screenshot of the entire screen. This API can be used only on tablets and 2-in-1 devices.
104
105Different from [pick](#screenshotpick), this API can be used to capture a full-screen screenshot on the specified display
106
107**Atomic service API**: This API can be used in atomic services since API version 14.
108
109**System capability**: SystemCapability.WindowManager.WindowManager.Core
110
111**Required permissions**: ohos.permission.CUSTOM_SCREEN_CAPTURE
112
113**Parameters**
114
115| Name | Type                                   | Mandatory| Description                                                        |
116| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
117| 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.|
118
119**Return value**
120
121| Type                         | Description                                           |
122| ----------------------------- | ----------------------------------------------- |
123| Promise&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt; | Promise used to return a **PixelMap** object.|
124
125**Error codes**
126
127For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
128
129| ID| Error Message|
130| ------- | -------------------------- |
131| 201     | Permission verification failed. The application does not have the permission required to call the API.|
132| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
133| 801 | Capability not supported on this device.|
134| 1400003 | This display manager service works abnormally.|
135
136**Example**
137
138```ts
139import { BusinessError } from '@kit.BasicServicesKit';
140import { image } from '@kit.ImageKit';
141
142let captureOption: screenshot.CaptureOption = {
143  "displayId": 0
144};
145try {
146  let promise = screenshot.capture(captureOption);
147  promise.then((pixelMap: image.PixelMap) => {
148    console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
149    pixelMap.release(); // Release the memory in time after the PixelMap is used.
150  }).catch((err: BusinessError) => {
151    console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
152  });
153} catch (exception) {
154  console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
155};
156