1# @ohos.screenshot (屏幕截图)(系统接口) 2 3本模块提供屏幕截图的能力，截取屏幕时支持设置截取的区域、大小等图像信息。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 该模块接口为系统接口。 10 11## 导入模块 12 13```ts 14import screenshot from '@ohos.screenshot'; 15``` 16 17## ScreenshotOptions 18 19设置截取图像的信息。 20 21**系统能力：** SystemCapability.WindowManager.WindowManager.Core 22 23 24| 名称 | 类型 | 必填 | 说明 | 25| ---------------------- | ------------- | ---- | ------------------------------------------------------------ | 26| screenRect | [Rect](#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 32## Rect 33 34表示截取图像的区域。 35 36**系统能力：** SystemCapability.WindowManager.WindowManager.Core 37 38| 名称 | 类型 | 必填 | 说明 | 39| ------ | ------ | ---- | ------------------------------------------------------------ | 40| left | number | 是 | 表示截取图像区域的左边界，单位为px，该参数应为整数。 | 41| top | number | 是 | 表示截取图像区域的上边界，单位为px，该参数应为整数。 | 42| width | number | 是 | 表示截取图像区域的宽度，单位为px，该参数应为整数。 | 43| height | number | 是 | 表示截取图像区域的高度，单位为px，该参数应为整数。 | 44 45 46## Size 47 48表示截取图像的大小。 49 50**系统能力：** SystemCapability.WindowManager.WindowManager.Core 51 52| 名称 | 类型 | 必填 | 说明 | 53| ------ | ------ | ---- | ------------------------------------------------------------ | 54| width | number | 是 | 表示截取图像的宽度，单位为px，该参数应为整数。 | 55| height | number | 是 | 表示截取图像的高度，单位为px，该参数应为整数。 | 56 57## screenshot.save 58 59save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>): void 60 61获取屏幕截图。 62 63**系统能力：** SystemCapability.WindowManager.WindowManager.Core 64 65**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 66 67**参数：** 68 69| 参数名 | 类型 | 必填 | 说明 | 70| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 71| options | [ScreenshotOptions](#screenshotoptions) | 是 | 该类型的参数包含screenRect、imageSize、rotation、displayId四个参数，可以分别设置这四个参数。 | 72| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。返回一个PixelMap对象。 | 73 74**错误码：** 75 76以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 77 78| 错误码ID | 错误信息 | 79| ------- | -------------------------- | 80| 1400001 | Invalid display or screen. | 81 82**示例：** 83 84```ts 85import { BusinessError } from '@ohos.base'; 86import image from '@ohos.multimedia.image'; 87 88let screenshotOptions: screenshot.ScreenshotOptions = { 89 "screenRect": { 90 "left": 200, 91 "top": 100, 92 "width": 200, 93 "height": 200 }, 94 "imageSize": { 95 "width": 300, 96 "height": 300 }, 97 "rotation": 0, 98 "displayId": 0 99}; 100try { 101 screenshot.save(screenshotOptions, (err: BusinessError, pixelMap: image.PixelMap) => { 102 if (err) { 103 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 104 return; 105 } 106 console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 107 pixelMap.release(); // PixelMap使用完后及时释放内存 108 }); 109} catch (exception) { 110 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 111}; 112``` 113 114## screenshot.save 115 116save(callback: AsyncCallback<image.PixelMap>): void 117 118获取屏幕截图。 119 120**系统能力：** SystemCapability.WindowManager.WindowManager.Core 121 122**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 128| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。返回一个PixelMap对象。 | 129 130**示例：** 131 132```ts 133import { BusinessError } from '@ohos.base'; 134import image from '@ohos.multimedia.image'; 135 136try { 137 screenshot.save((err: BusinessError, pixelMap: image.PixelMap) => { 138 if (err) { 139 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 140 return; 141 } 142 console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 143 pixelMap.release(); // PixelMap使用完后及时释放内存 144 }); 145} catch (exception) { 146 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 147}; 148``` 149 150## screenshot.save 151 152save(options?: ScreenshotOptions): Promise<image.PixelMap> 153 154获取屏幕截图。 155 156**系统能力：** SystemCapability.WindowManager.WindowManager.Core 157 158**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 164| options | [ScreenshotOptions](#screenshotoptions) | 否 | 该类型的参数包含screenRect、imageSize、rotation、displayId四个参数，可以分别设置这四个参数。 | 165 166**返回值：** 167 168| 类型 | 说明 | 169| ----------------------------- | ----------------------------------------------- | 170| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象。返回一个PixelMap对象。 | 171 172**示例：** 173 174```ts 175import { BusinessError } from '@ohos.base'; 176import image from '@ohos.multimedia.image'; 177 178let screenshotOptions: screenshot.ScreenshotOptions = { 179 "screenRect": { 180 "left": 200, 181 "top": 100, 182 "width": 200, 183 "height": 200 }, 184 "imageSize": { 185 "width": 300, 186 "height": 300 }, 187 "rotation": 0, 188 "displayId": 0 189}; 190try { 191 let promise = screenshot.save(screenshotOptions); 192 promise.then((pixelMap: image.PixelMap) => { 193 console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 194 pixelMap.release(); // PixelMap使用完后及时释放内存 195 }).catch((err: BusinessError) => { 196 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 197 }); 198} catch (exception) { 199 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 200}; 201``` 202