• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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```js
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**.    |
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.|
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 pixels.|
41| top    | number | Yes  | Top boundary of the screen region to capture, in pixels.|
42| width  | number | Yes  | Width of the screen region to capture, in pixels.|
43| height | number | Yes  | Height of the screen region to capture, in pixels.|
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 pixels.|
55| height | number | Yes  | Height of the screen region to capture, in pixels.|
56
57## screenshot.save
58
59save(options: ScreenshotOptions, callback: AsyncCallback&lt;image.PixelMap&gt;): 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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt;     | Yes  | Callback used to return a **PixelMap** object.                                  |
73
74**Example**
75
76  ```js
77  let screenshotOptions = {
78    "screenRect": {
79        "left": 200,
80        "top": 100,
81        "width": 200,
82        "height": 200},
83    "imageSize": {
84        "width": 300,
85        "height": 300},
86    "rotation": 0,
87    "displayId": 0
88  };
89  try {
90    screenshot.save(screenshotOptions, (err, pixelMap) => {
91      if (err) {
92          console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
93          return;
94      }
95      console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
96      pixelMap.release(); // Release the memory in time after the PixelMap is used.
97    });
98  } catch (exception) {
99    console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
100  };
101  ```
102
103## screenshot.save
104
105save(callback: AsyncCallback&lt;image.PixelMap&gt;): void
106
107Takes a screenshot and saves it as a **PixelMap** object. This API uses an asynchronous callback to return the result.
108
109**System capability**: SystemCapability.WindowManager.WindowManager.Core
110
111**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
112
113**Parameters**
114
115| Name  | Type                                   | Mandatory| Description                                                        |
116| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
117| callback | AsyncCallback&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt;     | Yes  | Callback used to return a **PixelMap** object.                                  |
118
119**Example**
120
121  ```js
122  try {
123    screenshot.save((err, pixelMap) => {
124      if (err) {
125          console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
126          return;
127      }
128      console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
129      pixelMap.release(); // Release the memory in time after the PixelMap is used.
130    });
131  } catch (exception) {
132    console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
133  };
134  ```
135
136## screenshot.save
137
138save(options?: ScreenshotOptions): Promise&lt;image.PixelMap&gt;
139
140Takes a screenshot and saves it as a **PixelMap** object. This API uses a promise to return the result.
141
142**System capability**: SystemCapability.WindowManager.WindowManager.Core
143
144**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
145
146**Parameters**
147
148| Name | Type                                   | Mandatory| Description                                                        |
149| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
150| options | [ScreenshotOptions](#screenshotoptions) | No  | Screenshot settings consist of **screenRect**, **imageSize**, **rotation**, and **displayId**. You can set the parameters separately.|
151
152**Return value**
153
154| Type                         | Description                                           |
155| ----------------------------- | ----------------------------------------------- |
156| Promise&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | Promise used to return a **PixelMap** object.|
157
158**Example**
159
160  ```js
161  let screenshotOptions = {
162  	"screenRect": {
163  		"left": 200,
164  		"top": 100,
165  		"width": 200,
166  		"height": 200},
167  	"imageSize": {
168  		"width": 300,
169  		"height": 300},
170  	"rotation": 0,
171  	"displayId": 0
172  };
173  try {
174    let promise = screenshot.save(screenshotOptions);
175    promise.then((pixelMap) => {
176        console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
177        pixelMap.release(); // Release the memory in time after the PixelMap is used.
178    }).catch((err) => {
179        console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
180    });
181  } catch (exception) {
182    console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
183  };
184  ```
185