1# @ohos.screenshot (Screenshot) (System API)
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> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.screenshot](js-apis-screenshot.md).
9
10## Modules to Import
11
12```ts
13import { screenshot } from '@kit.ArkUI';
14```
15
16## ScreenshotOptions
17
18Describes screenshot options.
19
20**System API**: This is a system API.
21
22**System capability**: SystemCapability.WindowManager.WindowManager.Core
23
24| Name                | Type         | Mandatory| Description                                                        |
25| ---------------------- | ------------- | ---- | ------------------------------------------------------------ |
26| screenRect             | [Rect](js-apis-screenshot.md#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| isNotificationNeeded<sup>14+</sup>| boolean        | No  | Whether to send a notification after a snapshot is captured. The value **true** means to send a notification, and **false** means the opposite. The default value is **true**. Such a notification can be listened for through [captureStatusChange](js-apis-display.md#displayoncapturestatuschange12).  |
31
32## Size
33
34Describes the size of the screen region to capture.
35
36**System API**: This is a system API.
37
38**System capability**: SystemCapability.WindowManager.WindowManager.Core
39
40| Name| Type  | Mandatory| Description                                                        |
41| ------ | ------ | ---- | ------------------------------------------------------------ |
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## screenshot.save
46
47save(options: ScreenshotOptions, callback: AsyncCallback&lt;image.PixelMap&gt;): void
48
49Takes a screenshot and saves it as a **PixelMap** object. This API uses an asynchronous callback to return the result.
50
51**System API**: This is a system API.
52
53**System capability**: SystemCapability.WindowManager.WindowManager.Core
54
55**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
56
57**Parameters**
58
59| Name  | Type                                   | Mandatory| Description                                                        |
60| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
61| options  | [ScreenshotOptions](#screenshotoptions) | Yes  | Information about the snapshot.|
62| callback | AsyncCallback&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt;     | Yes  | Callback used to return a **PixelMap** object.                                  |
63
64**Error codes**
65
66For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
67
68| ID| Error Message|
69| ------- | -------------------------- |
70| 201     | Permission verification failed.|
71| 202     | Permission verification failed. A non-system application calls a system API.|
72| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
73| 1400001 | Invalid display or screen. |
74
75**Example**
76
77```ts
78import { BusinessError } from '@kit.BasicServicesKit';
79import  { image } from '@kit.ImageKit';
80
81let screenshotOptions: screenshot.ScreenshotOptions = {
82  "screenRect": {
83    "left": 200,
84    "top": 100,
85    "width": 200,
86    "height": 200 },
87  "imageSize": {
88    "width": 300,
89    "height": 300 },
90  "rotation": 0,
91  "displayId": 0,
92  "isNotificationNeeded": true
93};
94try {
95  screenshot.save(screenshotOptions, (err: BusinessError, pixelMap: image.PixelMap) => {
96    if (err) {
97      console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
98      return;
99    }
100    console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
101    pixelMap.release(); // Release the memory in time after the PixelMap is used.
102  });
103} catch (exception) {
104  console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
105};
106```
107
108## screenshot.save
109
110save(callback: AsyncCallback&lt;image.PixelMap&gt;): void
111
112Takes a screenshot and saves it as a **PixelMap** object. This API uses an asynchronous callback to return the result.
113
114**System API**: This is a system API.
115
116**System capability**: SystemCapability.WindowManager.WindowManager.Core
117
118**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
119
120**Parameters**
121
122| Name  | Type                                   | Mandatory| Description                                                        |
123| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
124| callback | AsyncCallback&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt;     | Yes  | Callback used to return a **PixelMap** object.                                  |
125
126
127**Error codes**
128
129For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
130
131| ID| Error Message|
132| ------- | -------------------------- |
133| 201     | Permission verification failed.|
134| 202     | Permission verification failed. A non-system application calls a system API.|
135
136**Example**
137
138```ts
139import { BusinessError } from '@kit.BasicServicesKit';
140import { image } from '@kit.ImageKit';
141
142try {
143  screenshot.save((err: BusinessError, pixelMap: image.PixelMap) => {
144    if (err) {
145      console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
146      return;
147    }
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  });
151} catch (exception) {
152  console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
153};
154```
155
156## screenshot.save
157
158save(options?: ScreenshotOptions): Promise&lt;image.PixelMap&gt;
159
160Takes a screenshot and saves it as a **PixelMap** object. This API uses a promise to return the result.
161
162**System API**: This is a system API.
163
164**System capability**: SystemCapability.WindowManager.WindowManager.Core
165
166**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
167
168**Parameters**
169
170| Name | Type                                   | Mandatory| Description                                                        |
171| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
172| options | [ScreenshotOptions](#screenshotoptions) | No  | Information about the snapshot.|
173
174**Return value**
175
176| Type                         | Description                                           |
177| ----------------------------- | ----------------------------------------------- |
178| Promise&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt; | Promise used to return a **PixelMap** object.|
179
180
181**Error codes**
182
183For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
184
185| ID| Error Message|
186| ------- | -------------------------- |
187| 201     | Permission verification failed.|
188| 202     | Permission verification failed. A non-system application calls a system API.|
189| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
190
191**Example**
192
193```ts
194import { BusinessError } from '@kit.BasicServicesKit';
195import { image } from '@kit.ImageKit';
196
197let screenshotOptions: screenshot.ScreenshotOptions = {
198  "screenRect": {
199    "left": 200,
200    "top": 100,
201    "width": 200,
202    "height": 200 },
203  "imageSize": {
204    "width": 300,
205    "height": 300 },
206  "rotation": 0,
207  "displayId": 0,
208  "isNotificationNeeded": true
209};
210try {
211  let promise = screenshot.save(screenshotOptions);
212  promise.then((pixelMap: image.PixelMap) => {
213    console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
214    pixelMap.release(); // Release the memory in time after the PixelMap is used.
215  }).catch((err: BusinessError) => {
216    console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
217  });
218} catch (exception) {
219  console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
220};
221```
222