@ohos.screenshot (屏幕截图)

导入模块

import { screenshot } from '@kit.ArkUI';

Rect

表示截取图像的区域。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.WindowManager.WindowManager.Core

CaptureOption¹⁴⁺

设置截取图像的信息。

系统能力： SystemCapability.WindowManager.WindowManager.Core

PickInfo

截取图像的信息。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.WindowManager.WindowManager.Core

screenshot.pick

pick(): Promise<PickInfo>

获取屏幕截图，当前仅支持获取displayId为0的屏幕截图（如果需要对扩展屏截图，可以通过capture接口实现），使用Promise异步回调。

返回的PickInfo中的PixelMap对象需要手动释放，使用完毕后必须调用release()方法释放内存，否则可能导致内存泄漏。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.WindowManager.WindowManager.Core

设备行为差异： 该接口在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

接口对比： pick接口支持区域截屏，仅支持主屏幕（displayId为0），无需权限；capture接口支持全屏截屏，支持主屏幕和扩展屏（通过displayId参数指定），需要权限。

选取建议： 需要区域截屏时使用pick接口；需要全屏截屏或扩展屏截屏时使用capture接口。

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码和屏幕错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';

try {
  // 调用pick接口获取屏幕截图
  let promise = screenshot.pick();
  promise.then((pickInfo: screenshot.PickInfo) => {
    console.info(`pick Pixel bytes number: ${pickInfo.pixelMap.getPixelBytesNumber()}`);
    console.info(`pick Rect: ${pickInfo.pickRect}`);
    pickInfo.pixelMap.release(); // PixelMap使用完后及时释放内存
  }).catch((err: BusinessError) => {
    console.error(`Failed to pick. Code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to pick. Code: ${exception.code}, message: ${exception.message}`);
}

screenshot.capture¹⁴⁺

capture(options?: CaptureOption): Promise<image.PixelMap>

获取屏幕全屏截图，使用Promise异步回调。

此接口可以通过设置不同的displayId截取不同屏幕的截图，且只能截取全屏；pick接口可实现区域截屏。

返回的PixelMap对象需要手动释放，使用完毕后必须调用release()方法释放内存，否则可能导致内存泄漏。

元服务API： 从API version 14开始，该接口支持在元服务中使用。

系统能力： SystemCapability.WindowManager.WindowManager.Core

设备行为差异： 在API version 21之前，该接口在PC/2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。从API version 21开始，该接口在Phone设备、PC/2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。

需要权限：

• API版本22+：ohos.permission.CUSTOM_SCREEN_CAPTURE 或 ohos.permission.CUSTOM_SCREEN_RECORDING
• API版本14-21：ohos.permission.CUSTOM_SCREEN_CAPTURE

参数：

返回值：

错误码：

以下错误码的详细介绍请参见通用错误码和屏幕错误码。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

// 配置截图参数，指定截取displayId为0的屏幕
let captureOption: screenshot.CaptureOption = {
  displayId: 0
};
try {
  // 调用capture接口获取全屏截图
  let promise = screenshot.capture(captureOption);
  promise.then((pixelMap: image.PixelMap) => {
    console.info(`Succeeded in saving screenshot. Pixel bytes number: ${pixelMap.getPixelBytesNumber()}`);
    pixelMap.release(); // PixelMap使用完后及时释放内存
  }).catch((err: BusinessError) => {
    console.error(`Failed to save screenshot. Code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to save screenshot. Code: ${exception.code}, message: ${exception.message}`);
}