• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Screenshot
2The **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.
3
4> **NOTE**
5>
6> 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.
7>
8> The APIs provided by this module are system APIs.
9
10## Modules to Import
11
12```js
13import screenshot from '@ohos.screenshot';
14```
15
16## ScreenshotOptions
17
18Describes screenshot options.
19
20**System capability**: SystemCapability.WindowManager.WindowManager.Core
21
22
23| Name                | Type         | Mandatory| Description                                                        |
24| ---------------------- | ------------- | ---- | ------------------------------------------------------------ |
25| screenRect             | [Rect](#rect) | No  | Region of the screen to capture. If this parameter is null, the full screen will be captured.                      |
26| imageSize              | [Size](#size) | No  | Size of the screen region to capture. If this parameter is null, the full screen will be captured.                      |
27| rotation               | number        | No  | Rotation angle of the screenshot. Currently, the value can be **0** only. The default value is **0**.    |
28| 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.|
29
30
31## Rect
32
33Describes the region of the screen to capture.
34
35**System capability**: SystemCapability.WindowManager.WindowManager.Core
36
37| Name| Type  | Mandatory| Description                                                        |
38| ------ | ------ | ---- | ------------------------------------------------------------ |
39| left   | number | Yes  | Left boundary of the screen region to capture, in pixels.|
40| top    | number | Yes  | Top boundary of the screen region to capture, in pixels.|
41| width  | number | Yes  | Width of the screen region to capture, in pixels.|
42| height | number | Yes  | Height of the screen region to capture, in pixels.|
43
44
45## Size
46
47Describes the size of the screen region to capture.
48
49**System capability**: SystemCapability.WindowManager.WindowManager.Core
50
51| Name| Type  | Mandatory| Description                                                        |
52| ------ | ------ | ---- | ------------------------------------------------------------ |
53| width  | number | Yes  | Width of the screen region to capture, in pixels.|
54| height | number | Yes  | Height of the screen region to capture, in pixels.|
55
56## screenshot.save
57
58save(options?: ScreenshotOptions, callback: AsyncCallback&lt;image.PixelMap&gt;): void
59
60Takes a screenshot and saves it as a **PixelMap** object. This API uses an asynchronous callback to return the result.
61
62**System capability**: SystemCapability.WindowManager.WindowManager.Core
63
64**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
65
66**Parameters**
67
68| Name  | Type                                   | Mandatory| Description                                                        |
69| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
70| options  | [ScreenshotOptions](#screenshotoptions) | No  | Screenshot settings consist of **screenRect**, **imageSize**, **rotation**, and **displayId**. You can set the parameters separately.|
71| callback | AsyncCallback&lt;image.PixelMap&gt;     | Yes  | Callback used to return a **PixelMap** object.                                  |
72
73**Example**
74
75  ```js
76  var ScreenshotOptions = {
77  	"screenRect": {
78  		"left": 200,
79  		"top": 100,
80  		"width": 200,
81  		"height": 200},
82  	"imageSize": {
83  		"width": 300,
84  		"height": 300},
85  	"rotation": 0,
86  	"displayId": 0
87  };
88  screenshot.save(ScreenshotOptions, (err, data) => {
89  	if (err) {
90  		console.error('Failed to save the screenshot. Error: ' + JSON.stringify(err));
91  		return;
92  	}
93  	console.info('Screenshot saved. Data: ' + JSON.stringify(data));
94  });
95  ```
96
97## screenshot.save
98
99save(options?: ScreenshotOptions): Promise&lt;image.PixelMap&gt;
100
101Takes a screenshot and saves it as a **PixelMap** object. This API uses a promise to return the result.
102
103**System capability**: SystemCapability.WindowManager.WindowManager.Core
104
105**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
106
107**Parameters**
108
109| Name | Type                                   | Mandatory| Description                                                        |
110| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
111| options | [ScreenshotOptions](#screenshotoptions) | No  | Screenshot settings consist of **screenRect**, **imageSize**, **rotation**, and **displayId**. You can set the parameters separately.|
112
113**Return value**
114
115| Type                         | Description                                           |
116| ----------------------------- | ----------------------------------------------- |
117| Promise&lt;image.PixelMap&gt; | Promise used to return a **PixelMap** object.|
118
119**Example**
120
121  ```js
122  var ScreenshotOptions = {
123  	"screenRect": {
124  		"left": 200,
125  		"top": 100,
126  		"width": 200,
127  		"height": 200},
128  	"imageSize": {
129  		"width": 300,
130  		"height": 300},
131  	"rotation": 0,
132  	"displayId": 0
133  };
134  let promise = screenshot.save(ScreenshotOptions);
135  promise.then(() => {
136      console.log('screenshot save success');
137  }).catch((err) => {
138      console.log('screenshot save fail: ' + JSON.stringify(err));
139  });
140  ```
141