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