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
31## Size
32
33表示截取图像的大小。
34
35**系统接口：** 此接口为系统接口。
36
37**系统能力：** SystemCapability.WindowManager.WindowManager.Core
38
39| 名称 | 类型   | 必填 | 说明                                                         |
40| ------ | ------ | ---- | ------------------------------------------------------------ |
41| width  | number | 是   | 表示截取图像的宽度，单位为px，该参数应为整数。 |
42| height | number | 是   | 表示截取图像的高度，单位为px，该参数应为整数。 |
43
44## screenshot.save
45
46save(options: ScreenshotOptions, callback: AsyncCallback&lt;image.PixelMap&gt;): void
47
48获取屏幕截图。
49
50**系统接口：** 此接口为系统接口。
51
52**系统能力：** SystemCapability.WindowManager.WindowManager.Core
53
54**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。
55
56**参数：**
57
58| 参数名   | 类型                                    | 必填 | 说明                                                         |
59| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
60| options  | [ScreenshotOptions](#screenshotoptions) | 是   | 该类型的参数包含screenRect、imageSize、rotation、displayId四个参数，可以分别设置这四个参数。 |
61| callback | AsyncCallback&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt;     | 是   | 回调函数。返回一个PixelMap对象。                                   |
62
63**错误码：**
64
65以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。
66
67| 错误码ID | 错误信息 |
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**示例：**
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(); // PixelMap使用完后及时释放内存
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
110获取屏幕截图。
111
112**系统接口：** 此接口为系统接口。
113
114**系统能力：** SystemCapability.WindowManager.WindowManager.Core
115
116**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。
117
118**参数：**
119
120| 参数名   | 类型                                    | 必填 | 说明                                                         |
121| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
122| callback | AsyncCallback&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt;     | 是   | 回调函数。返回一个PixelMap对象。                                   |
123
124
125**错误码：**
126
127以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
128
129| 错误码ID | 错误信息 |
130| ------- | -------------------------- |
131| 201     | Permission verification failed.|
132| 202     | Permission verification failed. A non-system application calls a system API.|
133
134**示例：**
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(); // PixelMap使用完后及时释放内存
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
158获取屏幕截图。
159
160**系统接口：** 此接口为系统接口。
161
162**系统能力：** SystemCapability.WindowManager.WindowManager.Core
163
164**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。
165
166**参数：**
167
168| 参数名  | 类型                                    | 必填 | 说明                                                         |
169| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
170| options | [ScreenshotOptions](#screenshotoptions) | 否   | 该类型的参数包含screenRect、imageSize、rotation、displayId四个参数，可以分别设置这四个参数。 |
171
172**返回值：**
173
174| 类型                          | 说明                                            |
175| ----------------------------- | ----------------------------------------------- |
176| Promise&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt; | Promise对象。返回一个PixelMap对象。 |
177
178
179**错误码：**
180
181以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
182
183| 错误码ID | 错误信息 |
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**示例：**
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(); // PixelMap使用完后及时释放内存
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