1# @ohos.screenshot (屏幕截图)(系统接口)
2
3本模块提供屏幕截图的能力，截取屏幕时支持设置截取的区域、大小等图像信息。
4
5>  **说明：**
6>
7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.screenshot](./js-apis-screenshot.md)。
9
10## 导入模块
11
12```ts
13import { screenshot } from '@kit.ArkUI';
14```
15
16## ScreenshotOptions
17
18设置截取图像的信息。
19
20**系统接口：** 此接口为系统接口。
21
22**系统能力：** SystemCapability.WindowManager.WindowManager.Core
23
24| 名称                 | 类型          | 必填 | 说明                                                         |
25| ---------------------- | ------------- | ---- | ------------------------------------------------------------ |
26| screenRect             | [Rect](js-apis-screenshot.md#rect) | 否   | 表示截取图像的区域，不传值默认为全屏。                       |
27| imageSize              | [Size](#size) | 否   | 表示截取图像的大小，不传值默认为全屏。                       |
28| rotation               | number        | 否   | 表示截取图像的旋转角度，当前仅支持输入值为0，默认值为0，该参数应为整数。     |
29| displayId<sup>8+</sup> | number        | 否   | 表示截取图像的显示设备[Display](js-apis-display.md#display)的ID号，该参数应为整数。 |
30| isNotificationNeeded<sup>14+</sup>| boolean        | 否   | 表示截取图像之后是否发送截屏通知，true表示发送截屏通知，false表示不发送截屏通知，默认值为true。截屏通知可以通过[captureStatusChange](js-apis-display.md#displayoncapturestatuschange12)接口监听。   |
31
32## Size
33
34表示截取图像的大小。
35
36**系统接口：** 此接口为系统接口。
37
38**系统能力：** SystemCapability.WindowManager.WindowManager.Core
39
40| 名称 | 类型   | 必填 | 说明                                                         |
41| ------ | ------ | ---- | ------------------------------------------------------------ |
42| width  | number | 是   | 表示截取图像的宽度，单位为px，该参数应为整数。 |
43| height | number | 是   | 表示截取图像的高度，单位为px，该参数应为整数。 |
44
45## screenshot.save
46
47save(options: ScreenshotOptions, callback: AsyncCallback&lt;image.PixelMap&gt;): void
48
49获取屏幕截图。
50
51**系统接口：** 此接口为系统接口。
52
53**系统能力：** SystemCapability.WindowManager.WindowManager.Core
54
55**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。
56
57**参数：**
58
59| 参数名   | 类型                                    | 必填 | 说明                                                         |
60| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
61| options  | [ScreenshotOptions](#screenshotoptions) | 是   | 要截取的图像信息。 |
62| callback | AsyncCallback&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt;     | 是   | 回调函数。返回一个PixelMap对象。                                   |
63
64**错误码：**
65
66以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。
67
68| 错误码ID | 错误信息 |
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**示例：**
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(); // PixelMap使用完后及时释放内存
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
112获取屏幕截图。
113
114**系统接口：** 此接口为系统接口。
115
116**系统能力：** SystemCapability.WindowManager.WindowManager.Core
117
118**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。
119
120**参数：**
121
122| 参数名   | 类型                                    | 必填 | 说明                                                         |
123| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
124| callback | AsyncCallback&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt;     | 是   | 回调函数。返回一个PixelMap对象。                                   |
125
126
127**错误码：**
128
129以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
130
131| 错误码ID | 错误信息 |
132| ------- | -------------------------- |
133| 201     | Permission verification failed.|
134| 202     | Permission verification failed. A non-system application calls a system API.|
135
136**示例：**
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(); // PixelMap使用完后及时释放内存
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
160获取屏幕截图。
161
162**系统接口：** 此接口为系统接口。
163
164**系统能力：** SystemCapability.WindowManager.WindowManager.Core
165
166**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。
167
168**参数：**
169
170| 参数名  | 类型                                    | 必填 | 说明                                                         |
171| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
172| options | [ScreenshotOptions](#screenshotoptions) | 否   | 要截取的图像信息。 |
173
174**返回值：**
175
176| 类型                          | 说明                                            |
177| ----------------------------- | ----------------------------------------------- |
178| Promise&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt; | Promise对象。返回一个PixelMap对象。 |
179
180
181**错误码：**
182
183以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
184
185| 错误码ID | 错误信息 |
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**示例：**
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(); // PixelMap使用完后及时释放内存
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