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<PickInfo> 58 59获取屏幕截图。此接口仅可在2in1设备上使用。 60 61**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 62 63**系统能力:** SystemCapability.WindowManager.WindowManager.Core 64 65**返回值:** 66 67| 类型 | 说明 | 68| ----------------------------- | ----------------------------------------------- | 69| Promise<[PickInfo](#pickinfo)> | 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<image.PixelMap> 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<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 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};