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