1# @ohos.screenshot (屏幕截图)
2
3本模块提供屏幕截图的能力。
4
5>  **说明:**
6>
7> - 本模块首批接口从API version 12开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { screenshot } from '@kit.ArkUI';
13```
14
15## Rect
16
17表示截取图像的区域。
18
19**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
20
21**系统能力:** SystemCapability.WindowManager.WindowManager.Core
22
23| 名称 | 类型   | 必填 | 说明                                                         |
24| ------ | ------ | ---- | ------------------------------------------------------------ |
25| left   | number | 是   | 表示截取图像区域的左边界,单位为px,该参数应为整数。 |
26| top    | number | 是   | 表示截取图像区域的上边界,单位为px,该参数应为整数。 |
27| width  | number | 是   | 表示截取图像区域的宽度,单位为px,该参数应为整数。 |
28| height | number | 是   | 表示截取图像区域的高度,单位为px,该参数应为整数。 |
29
30## CaptureOption<sup>14+</sup>
31
32设置截取图像的信息。
33
34**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。
35
36**系统能力:** SystemCapability.WindowManager.WindowManager.Core
37
38| 名称 | 类型   | 必填 | 说明                                                         |
39| ------ | ------ | ---- | ------------------------------------------------------------ |
40| displayId | number | 否 | 表示截取图像的显示设备[Display](js-apis-display.md#display)的ID号,默认为0,该参数应为大于或等于0的整数,非整数会报参数错误。 |
41
42## PickInfo
43
44截取图像的信息。
45
46**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
47
48**系统能力:** SystemCapability.WindowManager.WindowManager.Core
49
50| 名称                 | 类型          | 必填 | 说明                                                         |
51| -------------------- | ------------- | ---- | ------------------------------------------------------------ |
52| pickRect             | [Rect](#rect) | 是   | 表示截取图像的区域。                       |
53| pixelMap             | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)  | 是   | 表示截取的图像PixelMap对象 |
54
55## screenshot.pick
56
57pick(): Promise&lt;PickInfo&gt;
58
59获取屏幕截图。此接口仅可在2in1设备上使用。
60
61**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
62
63**系统能力:** SystemCapability.WindowManager.WindowManager.Core
64
65**返回值:**
66
67| 类型                          | 说明                                            |
68| ----------------------------- | ----------------------------------------------- |
69| Promise&lt;[PickInfo](#pickinfo)&gt; | Promise对象。返回一个PickInfo对象。 |
70
71**错误码:**
72
73以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。
74
75| 错误码ID | 错误信息 |
76| ------- | ----------------------- |
77| 801 | Capability not supported on this device. |
78| 1400003 | This display manager service works abnormally. |
79
80**示例:**
81
82```ts
83import { BusinessError } from '@kit.BasicServicesKit';
84
85try {
86  let promise = screenshot.pick();
87  promise.then((pickInfo: screenshot.PickInfo) => {
88    console.log('pick Pixel bytes number: ' + pickInfo.pixelMap.getPixelBytesNumber());
89    console.log('pick Rect: ' + pickInfo.pickRect);
90    pickInfo.pixelMap.release(); // PixelMap使用完后及时释放内存
91  }).catch((err: BusinessError) => {
92    console.log('Failed to pick. Code: ' + JSON.stringify(err));
93  });
94} catch (exception) {
95  console.error('Failed to pick Code: ' + JSON.stringify(exception));
96};
97```
98
99## screenshot.capture<sup>14+</sup>
100
101capture(options?: CaptureOption): Promise&lt;image.PixelMap&gt;
102
103获取屏幕全屏截图,此接口仅支持在平板和2in1设备上使用。与[pick](#screenshotpick)接口不同之处是可以通过设置不同的displayId截取不同屏幕的截图。
104
105**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。
106
107**系统能力:** SystemCapability.WindowManager.WindowManager.Core
108
109**需要权限**:ohos.permission.CUSTOM_SCREEN_CAPTURE
110
111**参数:**
112
113| 参数名  | 类型                                    | 必填 | 说明                                                         |
114| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
115| options | [CaptureOption](#captureoption14) | 否 |  截取图像的相关信息。可包含设备ID,即displayId。 此参数不填时,默认截取displayId为0的屏幕截图。|
116
117**返回值:**
118
119| 类型                          | 说明                                            |
120| ----------------------------- | ----------------------------------------------- |
121| Promise&lt;[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)&gt; | Promise对象。返回一个PixelMap对象。 |
122
123**错误码:**
124
125以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
126
127| 错误码ID | 错误信息 |
128| ------- | -------------------------- |
129| 201     | Permission verification failed. The application does not have the permission required to call the API.|
130| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
131| 801 | Capability not supported on this device.|
132| 1400003 | This display manager service works abnormally.|
133
134**示例:**
135
136```ts
137import { BusinessError } from '@kit.BasicServicesKit';
138import { image } from '@kit.ImageKit';
139
140let captureOption: screenshot.CaptureOption = {
141  "displayId": 0
142};
143try {
144  let promise = screenshot.capture(captureOption);
145  promise.then((pixelMap: image.PixelMap) => {
146    console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
147    pixelMap.release(); // PixelMap使用完后及时释放内存
148  }).catch((err: BusinessError) => {
149    console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
150  });
151} catch (exception) {
152  console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
153};