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 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.screenshot](./js-apis-screenshot.md)。 15 16## 导入模块 17 18```ts 19import { screenshot } from '@kit.ArkUI'; 20``` 21 22## ScreenshotOptions 23 24设置截取图像的信息。 25 26**系统接口：** 此接口为系统接口。 27 28**系统能力：** SystemCapability.WindowManager.WindowManager.Core 29 30| 名称 | 类型 | 只读 | 可选 | 说明 | 31| ---------------------- | ------------- | ---- | ---- | ------------------------------------------------------------ | 32| screenRect | [Rect](js-apis-screenshot.md#rect) | 否 | 是 | 表示截取图像的区域，不传值默认返回displayId所在逻辑屏的区域。 | 33| imageSize | [Size](#size) | 否 | 是 | 表示截取图像的大小，不传值默认为displayId所在逻辑屏的大小。若screenRect小于imageSize，图像会拉伸至imageSize，反之则压缩至imageSize的大小。 | 34| rotation | number | 否 | 是 | 表示截取图像后要旋转的角度，当前仅支持输入值为0，默认值为0。 | 35| displayId<sup>8+</sup> | number | 否 | 是 | 表示截取图像的显示设备[Display](js-apis-display.md#display)的ID号，该参数应为整数。 | 36| isNotificationNeeded<sup>14+</sup>| boolean | 否 | 是 | 表示截取图像之后是否发送截屏通知，true表示发送截屏通知，false表示不发送截屏通知，默认值为true。截屏通知可以通过[captureStatusChange](js-apis-display.md#displayoncapturestatuschange12)接口监听。 | 37| isCaptureFullOfScreen<sup>20+</sup> | boolean | 否 | 是 | 表示是否截取当前Screen上的所有display。对于一个Screen上有多个display的场景，为true表示截取整个Screen，false则只截取displayId所在逻辑屏的区域，默认值为false。 | 38 39## HdrScreenshotOptions<sup>20+</sup> 40 41设置截取HDR图像的信息。 42 43**系统接口：** 此接口为系统接口。 44 45**系统能力：** SystemCapability.Window.SessionManager 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ---------------------- | ------------- |---| ---- | ------------------------------------------------------------ | 49| displayId | number | 否 | 是 | 表示截取图像的显示设备[Display](js-apis-display.md#display)的ID号，该参数应为整数。默认为0。 | 50| isNotificationNeeded| boolean | 否 | 是 | 表示截取图像之后是否发送截屏通知，true表示发送截屏通知，false表示不发送截屏通知，默认值为true。截屏通知可以通过[captureStatusChange](js-apis-display.md#displayoncapturestatuschange12)接口监听。 | 51| isCaptureFullOfScreen | boolean | 否 | 是 | 表示是否截取当前物理屏上所有DisplayId对应的逻辑屏。对于一个物理屏上有多个DisplayId的场景，true表示截取整个物理屏，false表示只截取DisplayId所在区域的逻辑屏。默认值为false。 | 52 53## Size 54 55表示截取图像的大小。 56 57**系统接口：** 此接口为系统接口。 58 59**系统能力：** SystemCapability.WindowManager.WindowManager.Core 60 61| 名称 | 类型 | 只读 | 可选 | 说明 | 62| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 63| width | number | 否 | 否 | 表示截取图像的宽度，单位为px，该参数应为整数。 | 64| height | number | 否 | 否 | 表示截取图像的高度，单位为px，该参数应为整数。 | 65 66## screenshot.save 67 68save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>): void 69 70获取屏幕截图。 71 72**系统接口：** 此接口为系统接口。 73 74**系统能力：** SystemCapability.WindowManager.WindowManager.Core 75 76**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 82| options | [ScreenshotOptions](#screenshotoptions) | 是 | 要截取的图像信息。当指定截取屏幕为虚拟屏时，截取图像为白屏。 | 83| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | 回调函数。返回一个PixelMap对象，其大小为指定的imageSize大小，若未指定默认为displayId所在逻辑屏的大小。 | 84 85**错误码：** 86 87以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 88 89| 错误码ID | 错误信息 | 90| ------- | -------------------------- | 91| 201 | Permission verification failed. The application does not have the permission required to call the API.| 92| 202 | Permission verification failed. A non-system application calls a system API.| 93| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 94| 1400001 | Invalid display or screen. | 95 96**示例：** 97 98```ts 99import { BusinessError } from '@kit.BasicServicesKit'; 100import { image } from '@kit.ImageKit'; 101 102let screenshotOptions: screenshot.ScreenshotOptions = { 103 "screenRect": { 104 "left": 200, 105 "top": 100, 106 "width": 200, 107 "height": 200 }, 108 "imageSize": { 109 "width": 300, 110 "height": 300 }, 111 "rotation": 0, 112 "displayId": 0, 113 "isNotificationNeeded": true, 114 "isCaptureFullOfScreen": true 115}; 116screenshot.save(screenshotOptions, (err: BusinessError, pixelMap: image.PixelMap) => { 117 if (err) { 118 console.error('Failed to save screenshot. Code: ' + JSON.stringify(err)); 119 return; 120 } 121 console.info('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 122 pixelMap.release(); // PixelMap使用完后及时释放内存 123}); 124``` 125 126## screenshot.save 127 128save(callback: AsyncCallback<image.PixelMap>): void 129 130获取屏幕截图。 131 132**系统接口：** 此接口为系统接口。 133 134**系统能力：** SystemCapability.WindowManager.WindowManager.Core 135 136**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 142| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | 回调函数。返回一个PixelMap对象。 | 143 144 145**错误码：** 146 147以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 148 149| 错误码ID | 错误信息 | 150| ------- | -------------------------- | 151| 201 | Permission verification failed. The application does not have the permission required to call the API.| 152| 202 | Permission verification failed. A non-system application calls a system API.| 153 154**示例：** 155 156```ts 157import { BusinessError } from '@kit.BasicServicesKit'; 158import { image } from '@kit.ImageKit'; 159 160screenshot.save((err: BusinessError, pixelMap: image.PixelMap) => { 161 if (err) { 162 console.error('Failed to save screenshot. Code: ' + JSON.stringify(err)); 163 return; 164 } 165 console.info('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 166 pixelMap.release(); // PixelMap使用完后及时释放内存 167}); 168``` 169 170## screenshot.save 171 172save(options?: ScreenshotOptions): Promise<image.PixelMap> 173 174获取屏幕截图。 175 176**系统接口：** 此接口为系统接口。 177 178**系统能力：** SystemCapability.WindowManager.WindowManager.Core 179 180**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 186| options | [ScreenshotOptions](#screenshotoptions) | 否 | 要截取的图像信息。当指定截取屏幕为虚拟屏时，截取图像为白屏。 | 187 188**返回值：** 189 190| 类型 | 说明 | 191| ----------------------------- | ----------------------------------------------- | 192| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。返回一个PixelMap对象。 | 193 194 195**错误码：** 196 197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 198 199| 错误码ID | 错误信息 | 200| ------- | -------------------------- | 201| 201 | Permission verification failed. The application does not have the permission required to call the API.| 202| 202 | Permission verification failed. A non-system application calls a system API.| 203| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 204 205**示例：** 206 207```ts 208import { BusinessError } from '@kit.BasicServicesKit'; 209import { image } from '@kit.ImageKit'; 210 211let screenshotOptions: screenshot.ScreenshotOptions = { 212 "screenRect": { 213 "left": 200, 214 "top": 100, 215 "width": 200, 216 "height": 200 }, 217 "imageSize": { 218 "width": 300, 219 "height": 300 }, 220 "rotation": 0, 221 "displayId": 0, 222 "isNotificationNeeded": true, 223 "isCaptureFullOfScreen": true 224}; 225try { 226 let promise = screenshot.save(screenshotOptions); 227 promise.then((pixelMap: image.PixelMap) => { 228 console.log('Succeeded in saving screenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 229 pixelMap.release(); // PixelMap使用完后及时释放内存 230 }).catch((err: BusinessError) => { 231 console.log('Failed to save screenshot. Code: ' + JSON.stringify(err)); 232 }); 233} catch (exception) { 234 console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception)); 235}; 236``` 237 238## screenshot.saveHdrPicture<sup>20+</sup> 239 240saveHdrPicture(options?: HdrScreenshotOptions): Promise<Array<image.PixelMap>> 241 242获取屏幕截图。SDR为标准动态范围图，HDR为高动态范围图。 243- 当物理屏存在HDR资源（包括HDR资源被遮挡）时，无论HDR是否开启，该接口返回一个包含SDR和HDR的PixelMap数组。 244- 当物理屏不存在HDR资源时，与[save](#screenshotsave)接口返回一个SDR的PixelMap不同，该接口返回包含一个SDR的PixelMap数组。同时该接口不具备[save](#screenshotsave)接口的裁剪、拉伸、旋转功能。 245<br><br> 246 247**系统接口：** 此接口为系统接口。 248 249**系统能力：** SystemCapability.Window.SessionManager 250 251**需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 252 253**参数：** 254 255| 参数名 | 类型 | 必填 | 说明 | 256| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 257| options | [HdrScreenshotOptions](#hdrscreenshotoptions20) | 否 | 要截取的HDR图像信息。默认为空。 | 258 259**返回值：** 260 261| 类型 | 说明 | 262| ----------------------------- | ----------------------------------------------- | 263| Promise<Array<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)>> | Promise对象。返回一个PixelMap对象数组。对于截取的区域存在HDR（包括HDR被遮挡）时，数组返回两个PixelMap，第一个为SDR的PixelMap，第二个为HDR的PixelMap。对于截取的区域不存在HDR时，数组返回一个SDR的PixelMap。| 264 265**错误码：** 266 267以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 268 269| 错误码ID | 错误信息 | 270| ------- | -------------------------- | 271| 201 | Permission verification failed.The application does not have the permission required to call the API.| 272| 202 | Permission verification failed. A non-system application calls a system API.| 273| 801 | Capability not supported. Failed to call the API due to limited device capabilities.| 274| 1400001 | Invalid display or screen.| 275| 1400003 | This display manager service works abnormally.| 276| 1400004 | Parameter error. Possible cause: 1.Invalid parameter range.| 277 278**示例：** 279 280```ts 281import { BusinessError } from '@kit.BasicServicesKit'; 282import { image } from '@kit.ImageKit'; 283 284let hdrScreenshotOptions: screenshot.HdrScreenshotOptions = { 285 "displayId": 0, 286 "isNotificationNeeded": true, 287 "isCaptureFullOfScreen": true 288}; 289try { 290 let promise = screenshot.saveHdrPicture(hdrScreenshotOptions); 291 promise.then((pixelMapArray: Array<image.PixelMap>) => { 292 for (let i = 0; i < pixelMapArray.length; i++) { 293 const pixelMap = pixelMapArray[i]; 294 console.info('succeeded in saving screenshot ${i}. Pixel bytes number' + pixelMap.getPixelBytesNumber()); 295 pixelMap.release(); 296 } 297 }).catch((err: BusinessError) => { 298 console.error('Failed to save SDR and HDR screenshot. Code: ' + JSON.stringify(err)); 299 }); 300} catch (exception) { 301 console.error('Failed to save SDR and HDR screenshot. Code: ' + JSON.stringify(exception)); 302}; 303``` 304