目录

@ohos.multimedia.sendableImage (基于Sendable对象的图片处理)

本模块基于Sendable对象，提供图片处理效果，包括通过属性创建PixelMap、读取图像像素数据、读取区域内的图片数据等。

本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { sendableImage } from '@kit.ImageKit';

sendableImage.createPixelMap

createPixelMap(colors: ArrayBuffer, options: image.InitializationOptions): Promise<PixelMap>

通过像素数据和图像属性创建PixelMap。传入的像素数据会进行拷贝并转换为InitializationOptions.pixelFormat指定的像素格式，用于初始化PixelMap的像素。使用Promise异步回调。

  • 此接口不支持创建以下像素格式的PixelMap：RGBA_1010102、YCBCR_P010、YCRCB_P010和ASTC_4x4。
  • 由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
colors ArrayBuffer 是

图像像素数据的缓冲区，用于初始化PixelMap的像素。缓冲区内的像素数据必须紧密排列，不可以包含内存对齐填充字节。

缓冲区的像素格式需要由InitializationOptions.srcPixelFormat指定，否则默认缓冲区的像素格式为BGRA_8888。

说明： 缓冲区长度为：图像宽度 * 图像高度 * 每像素字节数。
options image.InitializationOptions 是

创建图像的初始化属性，包括尺寸、像素格式、透明度类型、缩放模式和是否可编辑。

说明： 如果像素格式被指定为ASTC_4x4，则会使用默认的RGBA_8888格式。

返回值：

类型 说明
Promise<PixelMap>

Promise对象，返回创建的PixelMap。

当创建的PixelMap大小超过源像素数据所能表示的图像大小时，返回按源像素数据所能表示的图像大小创建的PixelMap。

示例：

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

function createPixelMap() {
  const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素缓冲区大小，取值为：width * height * 4。
  let opts: image.InitializationOptions = {
    size: { height: 4, width: 6 },
    srcPixelFormat: image.PixelMapFormat.RGBA_8888, // 缓冲区中的源像素数据的像素格式。
    pixelFormat: image.PixelMapFormat.BGRA_8888, // 新创建的PixelMap的像素格式。
    editable: true
  };
  sendableImage.createPixelMap(color, opts).then((pixelMap: sendableImage.PixelMap) => {
    console.info('Succeeded in creating the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to create the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

sendableImage.createPixelMapSync

createPixelMapSync(colors: ArrayBuffer, options: image.InitializationOptions): PixelMap

通过像素数据和图像属性创建PixelMap。传入的像素数据会进行拷贝并转换为InitializationOptions.pixelFormat指定的像素格式，用于初始化PixelMap的像素。同步返回结果。

  • 此接口不支持创建以下像素格式的PixelMap：RGBA_1010102、YCBCR_P010、YCRCB_P010和ASTC_4x4。
  • 由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
colors ArrayBuffer 是

图像像素数据的缓冲区，用于初始化PixelMap的像素。缓冲区内的像素数据必须紧密排列，不可以包含内存对齐填充字节。

缓冲区的像素格式需要由InitializationOptions.srcPixelFormat指定，否则默认缓冲区的像素格式为BGRA_8888。

说明： 缓冲区长度为：图像宽度 * 图像高度 * 每像素字节数。
options image.InitializationOptions 是

创建图像的初始化属性，包括尺寸、像素格式、透明度类型、缩放模式和是否可编辑。

说明： 如果像素格式被指定为ASTC_4x4，则会使用默认的RGBA_8888格式。

返回值：

类型 说明
PixelMap 返回创建的PixelMap对象，接口调用失败时会抛出异常。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.

示例：

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

function createPixelMapSync() {
  const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素缓冲区大小，取值为：width * height * 4。
  let opts: image.InitializationOptions = {
    size: { height: 4, width: 6 },
    srcPixelFormat: image.PixelMapFormat.RGBA_8888, // 缓冲区中的源像素数据的像素格式。
    pixelFormat: image.PixelMapFormat.BGRA_8888, // 新创建的PixelMap的像素格式。
    editable: true
  };
  try {
    let pixelMap: sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts);
    if (pixelMap == undefined) {
      console.error(`Failed to create the PixelMap.`);
      return;
    }
    console.info('Succeeded in creating the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to create the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

sendableImage.createPixelMapFromParcel

createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap

从MessageSequence中反序列化并获取PixelMap。

由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
sequence rpc.MessageSequence 是 保存了PixelMap序列化数据的MessageSequence。

返回值：

类型 说明
PixelMap 返回创建的PixelMap对象，接口调用失败时会抛出异常。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
62980096 Operation failed.
62980097 IPC error.
62980115 Invalid input parameter.
62980105 Failed to get the data.
62980177 Abnormal API environment.
62980178 Failed to create the PixelMap.
62980179 Abnormal buffer size.
62980180 FD mapping failed.
62980246 Failed to read the PixelMap.

示例：

// EntryAbility.ets
import { image } from '@kit.ImageKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

class MySequence implements rpc.Parcelable {
  pixelMap: sendableImage.PixelMap;
  constructor(pixelMap: sendableImage.PixelMap) {
    this.pixelMap = pixelMap;
  }
  marshalling(messageSequence: rpc.MessageSequence) {
    this.pixelMap.marshalling(messageSequence);
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence) {
    try {
      this.pixelMap = sendableImage.createPixelMapFromParcel(messageSequence);
    } catch (e) {
      const err = e as BusinessError;
      console.error(`Failed to create the PixelMap from parcel. Code: ${err.code}, message: ${err.message}`);
      return false;
    }
    return true;
  }
}

async function createPixelMapFromParcel() {
  const color: ArrayBuffer = new ArrayBuffer(96);
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = 0x80;
  }
  let opts: image.InitializationOptions = {
    editable: true,
    pixelFormat: image.PixelMapFormat.BGRA_8888,
    size: { height: 4, width: 6 },
    alphaType: image.AlphaType.UNPREMUL
  };
  const pixelMap: sendableImage.PixelMap | undefined = await sendableImage.createPixelMap(color, opts);
  if (pixelMap != undefined) {
    // 序列化。
    let parcelable: MySequence = new MySequence(pixelMap);
    let data: rpc.MessageSequence = rpc.MessageSequence.create();
    data.writeParcelable(parcelable);

    // 反序列化rpc获取到data。
    let seq: MySequence = new MySequence(pixelMap);
    data.readParcelable(seq);

    // 获取到PixelMap。
    let newPixelMap = seq.pixelMap;
    if (newPixelMap != undefined) {
      console.info('Succeeded in getting the PixelMap.');
    }
  }
}

sendableImage.createPixelMapFromSurface

createPixelMapFromSurface(surfaceId: string, region: image.Region): Promise<PixelMap>

根据Surface ID和区域信息创建一个PixelMap对象。该区域的大小由Region.size指定。使用Promise异步回调。

  • 当设备为折叠屏，切换折叠状态时，可能因Surface自带旋转角度导致接口创建失败。需根据Surface的旋转角度相应调整传入的宽高值，如旋转90°或270°时互换宽与高。
  • 由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
surfaceId string 是 对应Surface的ID，可通过预览组件获取，如XComponent组件。
region image.Region 是 截取的画面区域。仅支持从画面左上角开始截取部分或整个画面，即Region中的x和y必须为0，Region.size中width和height的取值范围分别为[1, 预览流宽度]和[1, 预览流高度]。如需截取任意区域，可先获取整个画面，再使用crop截取所需区域。

返回值：

类型 说明
Promise<PixelMap> Promise对象，返回创建的PixelMap对象，接口调用失败时会抛出异常。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
62980115 If the image parameter invalid.
62980105 Failed to get the data.
62980178 Failed to create the PixelMap.

示例：

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

function createPixelMapFromSurface(surfaceId: string) {
  let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
  sendableImage.createPixelMapFromSurface(surfaceId, region).then((pixelMap: sendableImage.PixelMap) => {
    console.info('Succeeded in creating the PixelMap from Surface.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to create the PixelMap from Surface. Code: ${err.code}, message: ${err.message}`);
  });
}

sendableImage.convertFromPixelMap

convertFromPixelMap(pixelmap: image.PixelMap): PixelMap

通过image下的PixelMap创建出一个sendableImage下的PixelMap，同步返回PixelMap结果。原PixelMap的方法均不可再调用。

由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
pixelmap image.PixelMap 是 image下的非Sendable的PixelMap。

返回值：

类型 说明
PixelMap 成功同步返回Sendable的PixelMap对象，失败抛出异常。

错误码：

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

错误码ID 错误信息
401 If the image parameter invalid. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
62980104 Failed to initialize the internal object.

示例：

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

function convertFromPixelMap() {
  const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素缓冲区大小，取值为：width * height * 4。
  const opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } };
  let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts);
  try {
    let sendablePixelMap: sendableImage.PixelMap = sendableImage.convertFromPixelMap(pixelMap);
    console.info('Succeeded in converting the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to convert the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

sendableImage.convertToPixelMap

convertToPixelMap(pixelmap: PixelMap): image.PixelMap

通过sendableImage下的PixelMap创建出一个image下的PixelMap，同步返回PixelMap结果。原PixelMap的方法均不可再调用。

由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
pixelmap PixelMap 是 sendableImage下的PixelMap。

返回值：

类型 说明
image.PixelMap 成功同步返回image下的非Sendable的PixelMap对象，失败抛出异常。

错误码：

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

错误码ID 错误信息
401 If the image parameter invalid. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
62980104 Failed to initialize the internal object.

示例：

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

function convertToPixelMap() {
  const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素缓冲区大小，取值为：width * height * 4。
  const opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } };
  let sendablePixelMap: sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts);
  try {
    let pixelMap: image.PixelMap = sendableImage.convertToPixelMap(sendablePixelMap);
    console.info('Succeeded in converting the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to convert the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

ISendable

type ISendable = lang.ISendable

ISendable是所有Sendable类型（除null和undefined）的父类型。自身没有任何必须的方法和属性。

系统能力： SystemCapability.Multimedia.Image.Core

类型 说明
lang.ISendable 所有Sendable类型的父类型。

PixelMap

图像像素类，用于读取或写入图像数据以及获取图像信息，同时支持图像变换（缩放、平移、旋转、翻转、裁剪）、设置不透明度、提取Alpha通道、色彩空间设置等操作，适用于图像处理、图像编辑、图像显示等需要进行像素级数据操作的场景。在调用PixelMap的方法前，需要先通过sendableImage.createPixelMap传入像素数据创建一个PixelMap对象。目前PixelMap序列化大小最大为128MiB，超过会渲染失败。PixelMap大小的计算方式为：宽 * 高 * 每像素占用字节数（详情请参考PixelMapFormat）。

sendableImage下的PixelMap支持Sendable属性，支持Worker线程共享。sendableImage下的PixelMap可以利用sendableImage.convertToPixelMap方法与image下的PixelMap进行互相转换。转换后，原对象的方法均不允许再调用，否则将报错501无法调用接口。跨线程处理PixelMap时，需要考虑多线程竞争问题。

图像占用的内存往往较大，当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

[h2]属性

系统能力： SystemCapability.Multimedia.Image.Core

名称 类型 只读 可选 说明
isEditable boolean 是 否

图像像素是否可被编辑。true表示可被编辑，false表示不可被编辑。为false时，图像的渲染和传输性能更好。

元服务API： 从API version 12开始，该接口支持在元服务中使用。
isStrideAlignment boolean 是 否 图像的行数据是否已进行内存对齐。true表示已进行内存对齐，每行数据的末尾有空白填充字节以满足对齐要求（如果数据本身已满足对齐要求，则不会有填充字节）；false表示未进行内存对齐，每行数据紧密排列，末尾无空白填充字节。

[h2]readPixelsToBuffer

readPixelsToBuffer(dst: ArrayBuffer): Promise<void>

读取整个PixelMap的像素数据，并按照PixelMap的像素格式存入缓冲区。使用Promise异步回调。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
dst ArrayBuffer 是 目标缓冲区，获取的像素数据会被拷贝至该缓冲区。缓冲区内像素的格式与PixelMap相同，不包含内存对齐填充字节。缓冲区的大小由getPixelBytesNumber接口获取。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function readPixelsToBuffer(pixelMap: sendableImage.PixelMap) {
  const readBuffer: ArrayBuffer = new ArrayBuffer(pixelMap.getPixelBytesNumber());
  pixelMap.readPixelsToBuffer(readBuffer).then(() => {
    console.info('Succeeded in reading image pixel data.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to read image pixel data. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]readPixelsToBufferSync

readPixelsToBufferSync(dst: ArrayBuffer): void

读取整个PixelMap的像素数据，并按照PixelMap的像素格式存入缓冲区。同步返回结果。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
dst ArrayBuffer 是 目标缓冲区，获取的像素数据会被拷贝至该缓冲区。缓冲区内像素的格式与PixelMap相同，不包含内存对齐填充字节。缓冲区的大小由getPixelBytesNumber接口获取。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function readPixelsToBufferSync(pixelMap: sendableImage.PixelMap) {
  const readBuffer = new ArrayBuffer(pixelMap.getPixelBytesNumber());
  try {
    pixelMap.readPixelsToBufferSync(readBuffer);
    console.info('Succeeded in reading image pixel data.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to read image pixel data. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]readPixels

readPixels(area: image.PositionArea): Promise<void>

读取PixelMap指定区域内的像素数据并存入缓冲区。如果PixelMap的像素格式为YUV类型，则按照PixelMap的像素格式存入缓冲区，否则按照BGRA_8888格式存入缓冲区。使用Promise异步回调。

可使用公式计算PositionArea需要申请的缓冲区大小。

  • RGBA的区域计算公式：读取区域像素数量（Region.size {width * height}）* 4（1倍R分量 + 1倍G分量 + 1倍B分量 + 1倍A分量）
  • YUV的区域计算公式：读取区域像素数量（Region.size {width * height}）* 1.5（1倍Y分量 + 0.25倍U分量 + 0.25倍V分量）

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
area image.PositionArea 是

读取的区域数据。

该区域由PositionArea.region指定，获取的像素数据会被拷贝至PositionArea.pixels缓冲区。如果PixelMap的像素格式为YUV类型，则获取的像素数据格式与PixelMap相同，否则会被转换为BGRA_8888格式。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function readPixelsRGBA(pixelMap: sendableImage.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8), // 8为需要创建的像素缓冲区大小，取值为：width * height * 4。
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  pixelMap.readPixels(area).then(() => {
    console.info('Succeeded in reading the image data in the area from the specified area.');
    console.info('BGRA data: ', new Uint8Array(area.pixels));
  }).catch((err: BusinessError) => {
    console.error(`Failed to read the image data from the specified area. Code: ${err.code}, message: ${err.message}`);
  });
}

function readPixelsYUV(pixelMap: sendableImage.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(6),  // 6为需要创建的像素缓冲区大小，取值为：width * height * 1.5。
    offset: 0,
    stride: 8,
    region: { size: { height: 2, width: 2 }, x: 0, y: 0 }
  };
  pixelMap.readPixels(area).then(() => {
    console.info('Succeeded in reading the image data in the area from the specified area.');
    console.info('YUV data: ', new Uint8Array(area.pixels));
  }).catch((err: BusinessError) => {
    console.error(`Failed to read the image data from the specified area. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]readPixelsSync

readPixelsSync(area: image.PositionArea): void

读取PixelMap指定区域内的像素数据并存入缓冲区。如果PixelMap的像素格式为YUV类型，则按照PixelMap的像素格式存入缓冲区，否则按照BGRA_8888格式存入缓冲区。同步返回结果。

可使用公式计算PositionArea需要申请的缓冲区大小。

  • RGBA的区域计算公式：读取区域像素数量（Region.size {width * height}）* 4（1倍R分量 + 1倍G分量 + 1倍B分量 + 1倍A分量）
  • YUV的区域计算公式：读取区域像素数量（Region.size {width * height}）* 1.5（1倍Y分量 + 0.25倍U分量 + 0.25倍V分量）

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
area image.PositionArea 是

读取的区域数据。

该区域由PositionArea.region指定，获取的像素数据会被拷贝至PositionArea.pixels缓冲区。如果PixelMap的像素格式为YUV类型，则获取的像素数据格式与PixelMap相同，否则会被转换为BGRA_8888格式。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function readPixelsSync(pixelMap: sendableImage.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8),
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  try {
    pixelMap.readPixelsSync(area);
    console.info('Succeeded in reading the image data from the specified area.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to read the image data from the specified area. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]writePixels

writePixels(area: image.PositionArea): Promise<void>

将缓冲区内的像素数据写入PixelMap的指定区域。如果PixelMap的像素格式为YUV类型，则缓冲区内的数据会按照PixelMap的像素格式解析，否则按照BGRA_8888格式解析。使用Promise异步回调。

可使用公式计算PositionArea需要申请的缓冲区大小。

  • RGBA的区域计算公式：写入区域像素数量（Region.size {width * height}）* 4（1倍R分量 + 1倍G分量 + 1倍B分量 + 1倍A分量）
  • YUV的区域计算公式：写入区域像素数量（Region.size {width * height}）* 1.5（1倍Y分量 + 0.25倍U分量 + 0.25倍V分量）

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
area image.PositionArea 是

写入的区域数据。

该区域由PositionArea.region指定，PositionArea.pixels缓冲区内的像素数据会被写入PixelMap的该区域。如果PixelMap的像素格式为YUV类型，则缓冲区内的像素数据格式需与PixelMap相同，否则需要为BGRA_8888格式。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function writePixelsRGBA(pixelMap: sendableImage.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8), // 8为需要创建的像素缓冲区大小，取值为：width * height * 4。
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  pixelMap.writePixels(area).then(() => {
    console.info('Succeeded in writing pixels into the specified area.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to write pixels into the specified area. Code: ${err.code}, message: ${err.message}`);
  });
}

function writePixelsYUV(pixelMap: sendableImage.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(6), // 6为需要创建的像素缓冲区大小，取值为：width * height * 1.5。
    offset: 0,
    stride: 8, // PixelMap为YUV格式时，writePixels函数不使用该变量。
    region: { size: { height: 2, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  pixelMap.writePixels(area).then(() => {
    console.info('Succeeded in writing pixels into the specified area.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to write pixels into the specified area. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]writePixelsSync

writePixelsSync(area: image.PositionArea): void

将缓冲区内的像素数据写入PixelMap的指定区域。如果PixelMap的像素格式为YUV类型，则缓冲区内的数据会按照PixelMap的像素格式解析，否则按照BGRA_8888格式解析。同步返回结果。

可使用公式计算PositionArea需要申请的缓冲区大小。

  • RGBA的区域计算公式：写入区域像素数量（Region.size {width * height}）* 4（1倍R分量 + 1倍G分量 + 1倍B分量 + 1倍A分量）
  • YUV的区域计算公式：写入区域像素数量（Region.size {width * height}）* 1.5（1倍Y分量 + 0.25倍U分量 + 0.25倍V分量）

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
area image.PositionArea 是

写入的区域数据。

该区域由PositionArea.region指定，PositionArea.pixels缓冲区内的像素数据会被写入PixelMap的该区域。如果PixelMap的像素格式为YUV类型，则缓冲区内的像素数据格式需与PixelMap相同，否则需要为BGRA_8888格式。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function writePixelsSync(pixelMap: sendableImage.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8),
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  try {
    pixelMap.writePixelsSync(area);
    console.info('Succeeded in writing pixels into the specified area.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to write pixels into the specified area. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]writeBufferToPixels

writeBufferToPixels(src: ArrayBuffer): Promise<void>

将缓冲区内的像素数据写入整个PixelMap。使用Promise异步回调。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
src ArrayBuffer 是 源数据缓冲区，该缓冲区内的图像像素数据会被写入PixelMap。缓冲区内的像素数据必须是整个PixelMap的像素数据，且像素格式需与PixelMap相同，不包含内存对齐填充字节。缓冲区的大小可通过getPixelBytesNumber接口获取。

返回值：

类型 说明
Promise<void> Promise实例，用于获取结果，失败时返回错误信息。

示例：

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

function writeBufferToPixels(pixelMap: sendableImage.PixelMap) {
  const color: ArrayBuffer = new ArrayBuffer(pixelMap.getPixelBytesNumber());
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  pixelMap.writeBufferToPixels(color).then(() => {
    console.info('Succeeded in writing data from the buffer to the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to write data from the buffer to the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]writeBufferToPixelsSync

writeBufferToPixelsSync(src: ArrayBuffer): void

将缓冲区内的像素数据写入整个PixelMap。同步返回结果。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
src ArrayBuffer 是 源数据缓冲区，该缓冲区内的图像像素数据会被写入PixelMap。缓冲区内的像素数据必须是整个PixelMap的像素数据，且像素格式需与PixelMap相同，不包含内存对齐填充字节。缓冲区的大小可通过getPixelBytesNumber接口获取。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function writeBufferToPixelsSync(pixelMap: sendableImage.PixelMap) {
  const color: ArrayBuffer = new ArrayBuffer(pixelMap.getPixelBytesNumber());
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  try {
    pixelMap.writeBufferToPixelsSync(color);
    console.info('Succeeded in writing data from the buffer to the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to write data from the buffer to the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]getImageInfo

getImageInfo(): Promise<image.ImageInfo>

获取图像像素信息。使用Promise异步回调。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
Promise<image.ImageInfo> Promise对象，返回图像像素信息。

示例：

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

function getImageInfo(pixelMap: sendableImage.PixelMap) {
  pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
    console.info(`Succeeded in obtaining information of the PixelMap with size ${imageInfo.size} and pixel format ${imageInfo.pixelFormat}.`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to obtain information of the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]getImageInfoSync

getImageInfoSync(): image.ImageInfo

获取图像像素信息。同步返回结果。

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

系统能力： SystemCapability.Multimedia.Image.ImageSource

返回值：

类型 说明
image.ImageInfo 图像像素信息。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
501 Resource Unavailable.

示例：

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

function getImageInfoSync(pixelMap: sendableImage.PixelMap) {
  try {
    let imageInfo: image.ImageInfo = pixelMap.getImageInfoSync();
    console.info(`Succeeded in obtaining information of the PixelMap with size ${imageInfo.size} and pixel format ${imageInfo.pixelFormat}.`);
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to obtain information of the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]getBytesNumberPerRow

getBytesNumberPerRow(): number

获取图像每行像素的字节数。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
number 图像像素的行字节数。单位：字节（Byte）。

示例：

function getBytesNumberPerRow(pixelMap: sendableImage.PixelMap) {
  let rowBytes: number = pixelMap.getBytesNumberPerRow();
}

[h2]getPixelBytesNumber

getPixelBytesNumber(): number

获取图像所有像素占用的总字节数，不包含内存对齐填充字节。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
number 图像像素的总字节数。单位：字节（Byte）。

示例：

function getPixelBytesNumber(pixelMap: sendableImage.PixelMap) {
  let pixelBytesNumber: number = pixelMap.getPixelBytesNumber();
}

[h2]getDensity

getDensity(): number

获取图像的像素密度。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
number 图像的像素密度，单位：ppi（像素/英寸）。

示例：

function getDensity(pixelMap: sendableImage.PixelMap) {
  let density: number = pixelMap.getDensity();
}

[h2]opacity

opacity(rate: number): Promise<void>

设置PixelMap的不透明度，指定的不透明度值将被应用于所有像素，不受原图不透明度的影响。使用Promise异步回调。

YUV格式的图像不支持设置不透明度。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
rate number 是 不透明度的值，取值范围是(0.0, 1.0]。1.0表示完全不透明，数值越接近0.0则透明度越高。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function opacity(pixelMap: sendableImage.PixelMap) {
  const rate: number = 0.5;
  pixelMap.opacity(rate).then(() => {
    console.info('Succeeded in setting opacity.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set opacity. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]opacitySync

opacitySync(rate: number): void

设置PixelMap的不透明度，指定的不透明度值将被应用于所有像素，不受原图不透明度的影响。同步返回结果。

YUV格式的图像不支持设置不透明度。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
rate number 是 不透明度的值，取值范围是(0.0, 1.0]。1.0表示完全不透明，数值越接近0.0则透明度越高。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function opacitySync(pixelMap: sendableImage.PixelMap) {
  const rate: number = 0.5;
  try {
    pixelMap.opacitySync(rate);
    console.info('Succeeded in setting opacity.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to set opacity. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]createAlphaPixelmap

createAlphaPixelmap(): Promise<PixelMap>

根据Alpha通道的信息，生成一个仅包含Alpha通道信息的ALPHA_8格式的PixelMap，生成的新PixelMap不可编辑，可用于阴影效果。使用Promise异步回调。

  • YUV格式不支持此接口。
  • 如果原PixelMap的格式是ALPHA_F16，则新生成的PixelMap将维持ALPHA_F16格式。
  • 由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
Promise<PixelMap> Promise对象，返回仅包含Alpha通道信息的ALPHA_8格式的PixelMap。

示例：

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

function createAlphaPixelmap(pixelMap: sendableImage.PixelMap) {
  pixelMap.createAlphaPixelmap().then((alphaPixelMap: sendableImage.PixelMap) => {
    console.info('Succeeded in creating alpha PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to create alpha PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]createAlphaPixelmapSync

createAlphaPixelmapSync(): PixelMap

根据Alpha通道的信息，生成一个仅包含Alpha通道信息的ALPHA_8格式的PixelMap，生成的新PixelMap不可编辑，可用于阴影效果。同步返回结果。

  • YUV格式不支持此接口。
  • 如果原PixelMap的格式是ALPHA_F16，则新生成的PixelMap将维持ALPHA_F16格式。
  • 由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
PixelMap 成功同步返回仅包含Alpha通道信息的ALPHA_8格式的PixelMap对象，失败抛出异常。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function createAlphaPixelmapSync(pixelMap: sendableImage.PixelMap) {
  try {
    let alphaPixelMap: sendableImage.PixelMap = pixelMap.createAlphaPixelmapSync();
    if (alphaPixelMap == undefined) {
      console.error(`Failed to create alpha PixelMap.`);
      return;
    }
    console.info('Succeeded in creating alpha PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to create alpha PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]scale

scale(x: number, y: number): Promise<void>

根据输入的宽高缩放倍数对图片进行缩放。使用Promise异步回调。

缩放倍数 = 缩放后的图像尺寸 / 缩放前的图像尺寸。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
x number 是

宽度的缩放倍数。

取值不能为0，建议取正数，否则会产生翻转效果。
y number 是

高度的缩放倍数。

取值不能为0，建议取正数，否则会产生翻转效果。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function scale(pixelMap: sendableImage.PixelMap) {
  const scaleX: number = 2.0;
  const scaleY: number = 1.0;
  pixelMap.scale(scaleX, scaleY).then(() => {
    console.info('Succeeded in scaling the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to scale the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]scaleSync

scaleSync(x: number, y: number): void

根据输入的宽高缩放倍数对图片进行缩放。同步返回结果。

缩放倍数 = 缩放后的图像尺寸 / 缩放前的图像尺寸。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
x number 是

宽度的缩放倍数。

取值不能为0，建议取正数，否则会产生翻转效果。
y number 是

高度的缩放倍数。

取值不能为0，建议取正数，否则会产生翻转效果。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function scaleSync(pixelMap: sendableImage.PixelMap) {
  const scaleX: number = 2.0;
  const scaleY: number = 1.0;
  try {
    pixelMap.scaleSync(scaleX, scaleY);
    console.info('Succeeded in scaling the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to scale the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]translate

translate(x: number, y: number): Promise<void>

根据输入的坐标对图片进行位置变换。使用Promise异步回调。

平移后的图像尺寸将变为：宽度 = 原宽度 + x，高度 = 原高度 + y。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
x number 是

横向平移的距离。方向为正数向右，负数向左。取值范围是(-图像宽度, +∞)。单位：像素（px）。

取值为负数时，平移的效果等同于裁剪掉自图像左侧起的x列像素。
y number 是

纵向平移的距离。方向为正数向下，负数向上。取值范围是(-图像高度, +∞)。单位：像素（px）。

取值为负数时，平移的效果等同于裁剪掉自图像上方起的y行像素。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function translate(pixelMap: sendableImage.PixelMap) {
  const translateX: number = 50.0;
  const translateY: number = 10.0;
  pixelMap.translate(translateX, translateY).then(() => {
    console.info('Succeeded in translating the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to translate the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]translateSync

translateSync(x: number, y: number): void

根据输入的坐标对图片进行位置变换。同步返回结果。

平移后的图像尺寸将变为：宽度 = 原宽度 + x，高度 = 原高度 + y。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
x number 是

横向平移的距离。方向为正数向右，负数向左。取值范围是(-图像宽度, +∞)。单位：像素（px）。

取值为负数时，平移的效果等同于裁剪掉自图像左侧起的x列像素。
y number 是

纵向平移的距离。方向为正数向下，负数向上。取值范围是(-图像高度, +∞)。单位：像素（px）。

取值为负数时，平移的效果等同于裁剪掉自图像上方起的y行像素。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function translateSync(pixelMap: sendableImage.PixelMap) {
  const translateX: number = 50.0;
  const translateY: number = 10.0;
  try {
    pixelMap.translateSync(translateX, translateY);
    console.info('Succeeded in translating the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to translate the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]rotate

rotate(angle: number): Promise<void>

根据输入的角度对图片进行旋转。使用Promise异步回调。

  • YUV格式仅支持90°倍数的旋转角。
  • 图像旋转的角度取值范围：[0, 360]。超出取值范围时，根据圆周360°自动矫正。例如，-100°与260°效果相同。
  • 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
angle number 是 图像旋转的角度。方向为正数顺时针，负数逆时针。单位：角度（°）。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function rotate(pixelMap: sendableImage.PixelMap) {
  const angle: number = 90.0;
  pixelMap.rotate(angle).then(() => {
    console.info('Succeeded in rotating the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to rotate the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]rotateSync

rotateSync(angle: number): void

根据输入的角度对图片进行旋转。同步返回结果。

  • YUV格式仅支持90°倍数的旋转角。
  • 图像旋转的角度取值范围：[0, 360]。超出取值范围时，根据圆周360°自动矫正。例如，-100°与260°效果相同。
  • 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
angle number 是 图像旋转的角度。方向为正数顺时针，负数逆时针。单位：角度（°）。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function rotateSync(pixelMap: sendableImage.PixelMap) {
  const angle: number = 90.0;
  try {
    pixelMap.rotateSync(angle);
    console.info('Succeeded in rotating the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to rotate the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]flip

flip(horizontal: boolean, vertical: boolean): Promise<void>

根据输入的水平或垂直翻转条件对图片进行翻转。使用Promise异步回调。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
horizontal boolean 是 true表示进行水平翻转，false表示不进行水平翻转。
vertical boolean 是 true表示进行垂直翻转，false表示不进行垂直翻转。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function flip(pixelMap: sendableImage.PixelMap) {
  const horizontal: boolean = true;
  const vertical: boolean = false;
  pixelMap.flip(horizontal, vertical).then(() => {
    console.info('Succeeded in flipping the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to flip the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]flipSync

flipSync(horizontal: boolean, vertical: boolean): void

根据输入的水平或垂直翻转条件对图片进行翻转。同步返回结果。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
horizontal boolean 是 true表示进行水平翻转，false表示不进行水平翻转。
vertical boolean 是 true表示进行垂直翻转，false表示不进行垂直翻转。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function flipSync(pixelMap: sendableImage.PixelMap) {
  const horizontal: boolean = true;
  const vertical: boolean = false;
  try {
    pixelMap.flipSync(horizontal, vertical);
    console.info('Succeeded in flipping the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to flip the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]crop

crop(region: image.Region): Promise<void>

根据输入的区域信息对图片进行裁剪。使用Promise异步回调。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
region image.Region 是 裁剪的区域，包含起始坐标和宽高。取值范围不能超过图片的宽高。单位：像素（px）。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function crop(pixelMap: sendableImage.PixelMap) {
  const region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
  pixelMap.crop(region).then(() => {
    console.info('Succeeded in cropping the PixelMap.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to crop the PixelMap. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]cropSync

cropSync(region: image.Region): void

根据输入的区域信息对图片进行裁剪。同步返回结果。

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

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
region image.Region 是 裁剪的区域，包含起始坐标和宽高。取值范围不能超过图片的宽高。单位：像素（px）。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501 Resource Unavailable.

示例：

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

function cropSync(pixelMap: sendableImage.PixelMap) {
  const region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
  try {
    pixelMap.cropSync(region);
    console.info('Succeeded in cropping the PixelMap.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to crop the PixelMap. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]getColorSpace

getColorSpace(): colorSpaceManager.ColorSpaceManager

获取图像的色彩空间。

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
colorSpaceManager.ColorSpaceManager 图像色彩空间信息。如果图像不含色彩空间信息，则会抛出异常。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
62980101 If the image data abnormal.
62980103 If the image data unsupport.
62980115 If the image parameter invalid.

示例：

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

function getColorSpace(pixelMap: sendableImage.PixelMap) {
  try {
    const csm = pixelMap.getColorSpace();
    console.info(`Succeeded in getting color space: ${csm.getColorSpaceName()}.`);
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to get color space. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]setColorSpace

setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void

设置图像的色彩空间。如需同时对图像的像素颜色进行色彩空间转换，请使用applyColorSpace。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
colorSpace colorSpaceManager.ColorSpaceManager 是 图像色彩空间信息。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
62980111 If the operation invalid.
62980115 If the image parameter invalid.

示例：

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

function setColorSpace(pixelMap: sendableImage.PixelMap) {
  const colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
  const csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
  try {
    pixelMap.setColorSpace(csm);
    console.info('Succeeded in setting color space.');
  } catch (e) {
    const err = e as BusinessError;
    console.error(`Failed to set color space. Code: ${err.code}, message: ${err.message}`);
  }
}

[h2]applyColorSpace

applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise<void>

根据输入的目标色彩空间对图像的像素颜色进行色彩空间转换。使用Promise异步回调。

本接口仅执行色彩空间之间的数学转换，不包含HDR到SDR的色调映射。当源图像为HDR色彩空间（传输函数为HLG或PQ，例如BT2020_HLG、BT2020_PQ、P3_HLG、P3_PQ等）且目标为SDR色彩空间（传输函数为sRGB gamma，例如SRGB、DISPLAY_P3、DCI_P3、ADOBE_RGB_1998等）时，直接调用本接口会导致图像整体偏亮、泛白、高光细节丢失。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
targetColorSpace colorSpaceManager.ColorSpaceManager 是 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
62980104 Failed to initialize the internal object.
62980108 Failed to convert the color space.
62980115 Invalid image parameter.

示例：

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

function applyColorSpace(pixelMap: sendableImage.PixelMap) {
  const colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
  const targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
  pixelMap.applyColorSpace(targetColorSpace).then(() => {
    console.info('Succeeded in applying color space.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to apply color space. Code: ${err.code}, message: ${err.message}`);
  });
}

[h2]marshalling

marshalling(sequence: rpc.MessageSequence): void

将PixelMap序列化后写入MessageSequence。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
sequence rpc.MessageSequence 是 新创建的MessageSequence。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
62980115 Invalid image parameter.
62980097 IPC error.

示例：

// EntryAbility.ets
import { image } from '@kit.ImageKit';
import { rpc } from '@kit.IPCKit';

class MySequence implements rpc.Parcelable {
  pixelMap: sendableImage.PixelMap;
  constructor(pixelMap: sendableImage.PixelMap) {
    this.pixelMap = pixelMap;
  }
  marshalling(messageSequence: rpc.MessageSequence) {
    this.pixelMap.marshalling(messageSequence);
    console.info('Marshalled the PixelMap.');
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence) {
    sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height: 4, width: 6 }}).then((pixelParcel: sendableImage.PixelMap) => {
      pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: sendableImage.PixelMap) => {
        this.pixelMap = pixelMap;
        pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
          console.info(`Unmarshalled information: height = ${imageInfo.size.height}, width = ${imageInfo.size.width}.`);
        });
      });
    });
    return true;
  }
}

async function marshal() {
  const color: ArrayBuffer = new ArrayBuffer(96);
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = 0x80;
  }
  let opts: image.InitializationOptions = {
    editable: true,
    pixelFormat: image.PixelMapFormat.BGRA_8888,
    size: { height: 4, width: 6 },
    alphaType: image.AlphaType.UNPREMUL
  }
  let pixelMap: sendableImage.PixelMap | undefined = await sendableImage.createPixelMap(color, opts);
  if (pixelMap != undefined) {
    // 序列化。
    let parcelable: MySequence = new MySequence(pixelMap);
    let data: rpc.MessageSequence = rpc.MessageSequence.create();
    data.writeParcelable(parcelable);

    // 反序列化rpc获取到data。
    let seq: MySequence = new MySequence(pixelMap);
    data.readParcelable(seq);
  }
}

[h2]unmarshalling

unmarshalling(sequence: rpc.MessageSequence): Promise<PixelMap>

从MessageSequence中反序列化并获取PixelMap。使用Promise异步回调。

如需使用同步方式反序列化并创建PixelMap可使用createPixelMapFromParcel。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
sequence rpc.MessageSequence 是 保存有PixelMap信息的MessageSequence。

返回值：

类型 说明
Promise<PixelMap> Promise对象，返回反序列化后的PixelMap。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID 错误信息
62980115 Invalid image parameter.
62980097 IPC error.
62980096 The operation failed.

示例：

// EntryAbility.ets
import { image } from '@kit.ImageKit';
import { rpc } from '@kit.IPCKit';

class MySequence implements rpc.Parcelable {
  pixelMap: sendableImage.PixelMap;
  constructor(pixelMap: sendableImage.PixelMap) {
    this.pixelMap = pixelMap;
  }
  marshalling(messageSequence: rpc.MessageSequence) {
    this.pixelMap.marshalling(messageSequence);
    console.info('Marshalled the PixelMap.');
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence) {
    sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height: 4, width: 6 }}).then((pixelParcel: sendableImage.PixelMap) => {
      pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: sendableImage.PixelMap) => {
        this.pixelMap = pixelMap;
        pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
          console.info(`Unmarshalled information: height = ${imageInfo.size.height}, width = ${imageInfo.size.width}.`);
        });
      });
    });
    return true;
  }
}

async function unmarshal() {
  const color: ArrayBuffer = new ArrayBuffer(96);
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = 0x80;
  }
  let opts: image.InitializationOptions = {
    editable: true,
    pixelFormat: image.PixelMapFormat.BGRA_8888,
    size: { height: 4, width: 6 },
    alphaType: image.AlphaType.UNPREMUL
  }
  let pixelMap: sendableImage.PixelMap | undefined = await sendableImage.createPixelMap(color, opts);
  if (pixelMap != undefined) {
    // 序列化。
    let parcelable: MySequence = new MySequence(pixelMap);
    let data: rpc.MessageSequence = rpc.MessageSequence.create();
    data.writeParcelable(parcelable);

    // 反序列化rpc获取到data。
    let seq: MySequence = new MySequence(pixelMap);
    data.readParcelable(seq);
  }
}

[h2]release

release():Promise<void>

释放PixelMap对象。释放后，任何访问该对象内部数据的方法调用都会失败。使用Promise异步回调。

图片使用的内存往往较大，在PixelMap对象使用完成后，应主动调用该方法及时释放内存。

释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

释放指的是ArkTS对象释放与之关联的native对象的管理权。仅当所有管理该native对象的ArkTS对象都被释放时，native对象占用的内存才会被回收。

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

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
Promise<void> Promise对象，无返回结果。

示例：

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

function release(pixelMap: sendableImage.PixelMap) {
  pixelMap.release().then(() => {
    console.info('Succeeded in releasing the PixelMap object.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to release the PixelMap object. Code: ${err.code}, message: ${err.message}`);
  });
}

Size

表示图片尺寸。

继承自lang.ISendable。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

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

系统能力： SystemCapability.Multimedia.Image.Core

名称 类型 只读 可选 说明
height number 否 否 输出图片的高，单位：像素。
width number 否 否 输出图片的宽，单位：像素。

Region

表示区域信息。

继承自lang.ISendable。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

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

系统能力： SystemCapability.Multimedia.Image.Core

名称 类型 只读 可选 说明
size Size 否 否 区域大小。
x number 否 否 区域横坐标。单位：像素。
y number 否 否 区域纵坐标。单位：像素。

sendableImage.createImageSource

createImageSource(uri: string): ImageSource

通过传入的uri创建ImageSource实例。

由于图片占用内存较大，所以当ImageSource实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

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

系统能力： SystemCapability.Multimedia.Image.ImageSource

参数：

参数名 类型 必填 说明
uri string 是

图片路径，当前仅支持应用沙箱路径。

当前支持格式有：.jpg .png .gif .bmp .webp .dng SVG .ico。

返回值：

类型 说明
ImageSource 返回ImageSource类实例，失败时返回undefined。

示例：

import { sendableImage } from '@kit.ImageKit';

async function CreateImageSource(context : Context) {
  const path: string = context.cacheDir + "/test.jpg";
  const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(path);
}

sendableImage.createImageSource

createImageSource(fd: number): ImageSource

通过传入文件描述符来创建ImageSource实例。

由于图片占用内存较大，所以当ImageSource实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

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

系统能力： SystemCapability.Multimedia.Image.ImageSource

参数：

参数名 类型 必填 说明
fd number 是 文件描述符fd。

返回值：

类型 说明
ImageSource 返回ImageSource类实例，失败时返回undefined。

示例：

import { sendableImage } from '@kit.ImageKit';
import { fileIo } from '@kit.CoreFileKit';

async function CreateImageSource(context : Context) {
  const path: string = context.cacheDir + "/test.jpg";
  let file = fileIo.openSync(path, fileIo.OpenMode.CREATE | fileIo.OpenMode.READ_WRITE);
  const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(file.fd);
}

sendableImage.createImageSource

createImageSource(buf: ArrayBuffer): ImageSource

通过缓冲区创建ImageSource实例。buf数据是未解码的数据，不可以传入类似于RGBA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用sendableImage.createPixelMap这一类方法。

由于图片占用内存较大，所以当ImageSource实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

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

系统能力： SystemCapability.Multimedia.Image.ImageSource

参数：

参数名 类型 必填 说明
buf ArrayBuffer 是 图像缓冲区数组。

返回值：

类型 说明
ImageSource 返回ImageSource类实例，失败时返回undefined。

示例：

import { sendableImage } from '@kit.ImageKit';

async function CreateImageSource() {
  const buf: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。
  const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(buf);
}

sendableImage.createImageReceiver

createImageReceiver(size: image.Size, format: image.ImageFormat, capacity: number): ImageReceiver

通过图片大小、图片格式、容量创建ImageReceiver实例。

由于图片占用内存较大，所以当ImageReceiver实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

参数：

参数名 类型 必填 说明
size image.Size 是 图像的默认大小。
format image.ImageFormat 是 图像格式，取值为image.ImageFormat常量，目前仅支持 ImageFormat:JPEG。
capacity number 是 同时访问的最大图像数。该参数仅作为期望值，实际capacity由设备硬件决定。

返回值：

类型 说明
ImageReceiver 如果操作成功，则返回ImageReceiver实例。

错误码：

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

错误码ID 错误信息
401 The parameter check failed.

示例：

import { sendableImage } from '@kit.ImageKit';
import { image } from '@kit.ImageKit';

async function CreateImageReceiver() {
    let size: image.Size = {
        height: 8192,
        width: 8
    }
    let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
}

ImageSource

ImageSource类，用于获取图片相关信息。在调用ImageSource的方法前，需要先通过sendableImage.createImageSource构建一个ImageSource实例。

由于图片占用内存较大，所以当ImageSource实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

[h2]createPixelMap

createPixelMap(options?: image.DecodingOptions): Promise<PixelMap>

通过图片解码参数创建PixelMap对象。使用Promise异步回调。

由于图片占用内存较大，所以当PixelMap对象使用完成后，应主动调用release方法及时释放内存。释放时应确保该对象的所有异步方法均执行完成，且后续不再使用该对象。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

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

系统能力： SystemCapability.Multimedia.Image.ImageSource

参数：

参数名 类型 必填 说明
options image.DecodingOptions 否 解码参数。

返回值：

类型 说明
Promise<PixelMap> Promise实例，用于异步返回创建结果。

示例：

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

async function CreatePixelMap(context : Context) {
  const path: string = context.cacheDir + "/test.jpg";
  const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(path);
  sendableImageSourceObj.createPixelMap().then((pixelMap: sendableImage.PixelMap) => {
    console.info('Succeeded in creating pixelMap object through image decoding parameters.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to create pixelMap object through image decoding parameters. code ${error.code}, message is ${error.message}`);
  })
}

[h2]release

release(): Promise<void>

释放ImageSource实例。使用Promise异步回调。

由于图片占用内存较大，所以当ImageSource实例使用完成后，应主动调用该方法，及时释放内存。

释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

系统能力： SystemCapability.Multimedia.Image.ImageSource

返回值：

类型 说明
Promise<void> Promise实例，异步返回结果。

示例：

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

async function Release(context : Context) {
  const path: string = context.cacheDir + "/test.jpg";
  const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(path);
  sendableImageSourceObj.release().then(() => {
    console.info('Succeeded in releasing the image source instance.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to release the image source instance. code ${error.code}, message is ${error.message}`);
  })
}

Image

提供基本的图像操作，包括获取图像信息、读写图像数据。调用readNextImage和readLatestImage接口时会返回Image。继承自ISendable。

由于图片占用内存较大，所以当Image实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

[h2]属性

系统能力： SystemCapability.Multimedia.Image.Core

名称 类型 只读 可选 说明
clipRect Region 否 否 要裁剪的图像区域。
size Size 是 否

图像大小。

如果Image对象所存储的是相机预览流数据（YUV图像数据），那么获取到的size中的宽和高分别对应YUV图像的宽和高。

如果Image对象所存储的是相机拍照流数据（JPEG图像数据），由于已是编码后的文件，size中的宽等于JPEG文件大小，高等于1。

Image对象所存储的数据是预览流还是拍照流，取决于应用将receiver中的surfaceId传给相机的是previewOutput还是captureOutput。

相机预览与拍照最佳实践请参考双路预览(ArkTS)与拍照实践(ArkTS)。
format number 是 否 图像格式，参考OH_NativeBuffer_Format。
timestamp number 是 否 图像时间戳。时间戳以纳秒为单位，通常是单调递增的。时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。如果要获取某张照片的生成时间，可以通过getImageProperty接口读取相关的EXIF信息。

[h2]getComponent

getComponent(componentType: image.ComponentType): Promise<image.Component>

根据图像的组件类型从图像中获取组件缓存。使用Promise异步回调。getComponent是线程不安全的。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名 类型 必填 说明
componentType image.ComponentType 是 图像的组件类型。

返回值：

类型 说明
Promise<image.Component> Promise实例，用于异步返回组件缓冲区。

示例：

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

async function GetComponent() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  let img = await receiver.readNextImage();
  img.getComponent(image.ComponentType.JPEG).then((component: image.Component) => {
    console.info('Succeeded in getting an image component.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to get an image component. Code: ${error.code}, message: ${error.message}.`);
  })
}

[h2]release

release(): Promise<void>

释放当前图像。使用Promise异步回调。

在接收另一个图像前必须先释放对应资源。

由于图片占用内存较大，所以当Image实例使用完成后，应主动调用该方法及时释放内存。

释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

系统能力： SystemCapability.Multimedia.Image.Core

返回值：

类型 说明
Promise<void> promise返回操作结果。

示例：

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

async function Release() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  let img = await receiver.readNextImage();
  img.release().then(() => {
    console.info('Succeeded in releasing an image.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to release an image. Code: ${error.code}, message: ${error.message}.`);
  })
}

ImageReceiver

图像接收类，用于获取组件Surface ID，接收最新的图片和读取下一张图片，以及释放ImageReceiver实例。

在调用以下方法前需要先创建ImageReceiver实例。

[h2]属性

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

名称 类型 只读 可选 说明
size image.Size 是 否 图片大小。
capacity number 是 否 同时访问的图像数。该参数仅作为期望值，实际capacity由设备硬件决定。
format image.ImageFormat 是 否 图像格式。

[h2]getReceivingSurfaceId

getReceivingSurfaceId(): Promise<string>

用于获取一个Surface ID供Camera或其他组件使用。使用promise异步回调。

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

返回值：

类型 说明
Promise<string> 异步返回Surface ID。

示例：

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

async function GetReceivingSurfaceId() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  receiver.getReceivingSurfaceId().then((id: string) => {
    console.info('Succeeded in getting the ReceivingSurfaceId.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to get the ReceivingSurfaceId.code ${error.code}, message is ${error.message}`);
  })
}

[h2]readLatestImage

readLatestImage(): Promise<Image>

从ImageReceiver读取最新的图片。使用promise异步回调。

此接口需要在on回调触发后调用，才能正常地接收到数据。且此接口返回的Image对象使用完毕后需要调用release方法释放，释放后才可以继续接收新的数据。

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

返回值：

类型 说明
Promise<Image> 异步返回最新图片。

示例：

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

async function ReadLatestImage() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  receiver.readLatestImage().then((img: sendableImage.Image) => {
    console.info('Succeeded in reading the latest image.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to read the latest image. Code: ${error.code}, message: ${error.message}.`);
  })
}

[h2]readNextImage

readNextImage(): Promise<Image>

从ImageReceiver读取下一张图片。使用promise异步回调。

此接口需要在on回调触发后调用，才能正常地接收到数据。且此接口返回的Image对象使用完毕后需要调用release方法释放，释放后才可以继续接收新的数据。

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

返回值：

类型 说明
Promise<Image> 异步返回下一张图片。

示例：

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

async function ReadNextImage() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  receiver.readNextImage().then((img: sendableImage.Image) => {
    console.info('Succeeded in reading the next image.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to read the next image. Code: ${error.code}, message: ${error.message}.`);
  })
}

[h2]on

on(type: 'imageArrival', callback: AsyncCallback<void>): void

接收图片时注册。使用callback异步回调。

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

参数：

参数名 类型 必填 说明
type string 是 注册事件的类型，固定为'imageArrival'，接收图片时触发。
callback AsyncCallback<void> 是 注册的事件回调。

示例：

import { sendableImage } from '@kit.ImageKit';
import { image } from '@kit.ImageKit';

async function On() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  receiver.on('imageArrival', () => {
    // 接收到图片，实现回调函数逻辑。
  })
}

[h2]release

release(): Promise<void>

释放ImageReceiver实例。使用promise异步回调。

由于图片占用内存较大，所以当ImageReceiver实例使用完成后，应主动调用该方法，及时释放内存。

释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

系统能力： SystemCapability.Multimedia.Image.ImageReceiver

返回值：

类型 说明
Promise<void> 异步返回操作结果。

示例：

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

async function Release() {
  let size: image.Size = {
    height: 8192,
    width: 8
  }
  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
  receiver.release().then(() => {
    console.info('Succeeded in releasing an image receiver.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to release an image receiver. Code: ${error.code}, message: ${error.message}.`);
  })
}