1# @ohos.multimedia.sendableImage (基于Sendable对象的图片处理) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--Designer: @liyang_bryan--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9本模块基于Sendable对象，提供图片处理效果，包括通过属性创建PixelMap、读取图像像素数据、读取区域内的图片数据等。 10 11> **说明：** 12> 13> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { sendableImage } from '@kit.ImageKit'; 19``` 20 21## sendableImage.createPixelMap 22 23createPixelMap(colors: ArrayBuffer, options: image.InitializationOptions): Promise\<PixelMap> 24 25通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过Promise返回结果。 26 27**系统能力：** SystemCapability.Multimedia.Image.Core 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 33| colors | ArrayBuffer | 是 | 默认按照BGRA_8888格式处理的颜色数组。 | 34| options | [image.InitializationOptions](arkts-apis-image-i.md#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 35 36**返回值：** 37 38| 类型 | 说明 | 39| -------------------------------- | ----------------------------------------------------------------------- | 40| Promise\<[PixelMap](#pixelmap)> | 返回Pixelmap。<br>当创建的pixelmap大小超过原图大小时，返回原图pixelmap大小。| 41 42**示例：** 43 44```ts 45import { sendableImage } from '@kit.ImageKit'; 46import { image } from '@kit.ImageKit'; 47import { BusinessError } from '@kit.BasicServicesKit'; 48 49async function Demo() { 50 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 51 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 52 sendableImage.createPixelMap(color, opts).then((pixelMap: sendableImage.PixelMap) => { 53 console.info('Succeeded in creating pixelmap.'); 54 }).catch((error: BusinessError) => { 55 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 56 }) 57} 58``` 59 60## sendableImage.createPixelMapFromParcel 61 62createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap 63 64从MessageSequence中获取PixelMap。 65 66**系统能力：** SystemCapability.Multimedia.Image.Core 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 72| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 73 74**返回值：** 75 76| 类型 | 说明 | 77| -------------------------------- | --------------------- | 78| [PixelMap](#pixelmap) | 成功同步返回PixelMap对象，失败抛出异常。 | 79 80**错误码：** 81 82以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 83 84| 错误码ID | 错误信息 | 85| ------- | --------------------------------------------| 86| 62980096 | Operation failed| 87| 62980097 | IPC error| 88| 62980115 | Invalid input parameter| 89| 62980105 | Failed to get the data| 90| 62980177 | Abnormal API environment| 91| 62980178 | Failed to create the PixelMap| 92| 62980179 | Abnormal buffer size| 93| 62980180 | FD mapping failed| 94| 62980246 | Failed to read the PixelMap| 95 96**示例：** 97 98```ts 99import { sendableImage } from '@kit.ImageKit'; 100import { image } from '@kit.ImageKit'; 101import { rpc } from '@kit.IPCKit'; 102import { BusinessError } from '@kit.BasicServicesKit'; 103 104class MySequence implements rpc.Parcelable { 105 pixel_map: sendableImage.PixelMap; 106 constructor(conPixelmap: sendableImage.PixelMap) { 107 this.pixel_map = conPixelmap; 108 } 109 marshalling(messageSequence: rpc.MessageSequence) { 110 this.pixel_map.marshalling(messageSequence); 111 return true; 112 } 113 unmarshalling(messageSequence: rpc.MessageSequence) { 114 try { 115 this.pixel_map = sendableImage.createPixelMapFromParcel(messageSequence); 116 } catch(e) { 117 let error = e as BusinessError; 118 console.error(`createPixelMapFromParcel error. code is ${error.code}, message is ${error.message}`); 119 return false; 120 } 121 return true; 122 } 123} 124async function Demo() { 125 const color: ArrayBuffer = new ArrayBuffer(96); 126 let bufferArr: Uint8Array = new Uint8Array(color); 127 for (let i = 0; i < bufferArr.length; i++) { 128 bufferArr[i] = 0x80; 129 } 130 let opts: image.InitializationOptions = { 131 editable: true, 132 pixelFormat: 4, 133 size: { height: 4, width: 6 }, 134 alphaType: 3 135 } 136 let pixelMap: sendableImage.PixelMap | undefined = undefined; 137 await sendableImage.createPixelMap(color, opts).then((srcPixelMap: sendableImage.PixelMap) => { 138 pixelMap = srcPixelMap; 139 }) 140 if (pixelMap != undefined) { 141 // 序列化。 142 let parcelable: MySequence = new MySequence(pixelMap); 143 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 144 data.writeParcelable(parcelable); 145 146 // 反序列化rpc获取到data。 147 let ret: MySequence = new MySequence(pixelMap); 148 data.readParcelable(ret); 149 150 // 获取到pixelmap。 151 let unmarshPixelmap = ret.pixel_map; 152 } 153} 154``` 155 156## sendableImage.createPixelMapFromSurface 157 158createPixelMapFromSurface(surfaceId: string, region: image.Region): Promise\<PixelMap> 159 160根据Surface ID和区域信息创建一个PixelMap对象。该区域的大小由[Region](arkts-apis-image-i.md#region8).size指定。使用Promise形式返回。 161 162**系统能力：** SystemCapability.Multimedia.Image.Core 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ---------------------- | ------------- | ---- | ---------------------------------------- | 168| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 169| region | [image.Region](arkts-apis-image-i.md#region8) | 是 | 截取的画面区域。仅支持从画面左上角开始截取部分或整个画面，即Region中的x和y必须为0，Region.size中width和height的取值范围分别为[1, 预览流宽度]和[1, 预览流高度]。如需截取任意区域，可先获取整个画面，再使用[crop](#crop)截取所需区域。 | 170 171**返回值：** 172| 类型 | 说明 | 173| -------------------------------- | --------------------- | 174| Promise\<[PixelMap](#pixelmap)> | 成功同步返回PixelMap对象，失败抛出异常。 | 175 176**错误码：** 177 178以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 179 180| 错误码ID | 错误信息 | 181| ------- | --------------------------------------------| 182| 62980115 | If the image parameter invalid.| 183| 62980105 | Failed to get the data| 184| 62980178 | Failed to create the PixelMap| 185 186**示例：** 187 188```ts 189import { sendableImage } from '@kit.ImageKit'; 190import { image } from '@kit.ImageKit'; 191import { BusinessError } from '@kit.BasicServicesKit'; 192 193async function Demo(surfaceId: string) { 194 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 195 sendableImage.createPixelMapFromSurface(surfaceId, region).then(() => { 196 console.info('Succeeded in creating pixelmap from Surface'); 197 }).catch((error: BusinessError) => { 198 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 199 }); 200} 201``` 202 203## sendableImage.createPixelMapSync 204 205createPixelMapSync(colors: ArrayBuffer, options: image.InitializationOptions): PixelMap 206 207通过属性创建PixelMap，同步返回PixelMap结果。 208 209**系统能力：** SystemCapability.Multimedia.Image.Core 210 211**参数：** 212 213| 参数名 | 类型 | 必填 | 说明 | 214| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 215| colors | ArrayBuffer | 是 | BGRA_8888格式的颜色数组。 | 216| options | [image.InitializationOptions](arkts-apis-image-i.md#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 217 218**返回值：** 219| 类型 | 说明 | 220| -------------------------------- | --------------------- | 221| [PixelMap](#pixelmap) | 成功同步返回PixelMap对象，失败抛出异常。 | 222 223**错误码：** 224 225以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 226 227| 错误码ID | 错误信息 | 228| ------- | --------------------------------------------| 229| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 230 231**示例：** 232 233```ts 234import { sendableImage } from '@kit.ImageKit'; 235import { image } from '@kit.ImageKit'; 236import { BusinessError } from '@kit.BasicServicesKit'; 237 238async function Demo() { 239 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 240 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 241 let pixelMap : sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts); 242 return pixelMap; 243} 244``` 245 246## sendableImage.convertFromPixelMap 247 248convertFromPixelMap(pixelmap: image.PixelMap): PixelMap 249 250通过image下的PixelMap创建出一个sendableImage下的PixelMap，同步返回PixelMap结果。原PixelMap的方法均不可再调用。 251 252**系统能力：** SystemCapability.Multimedia.Image.Core 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 258| pixelmap | [image.PixelMap](arkts-apis-image-PixelMap.md) | 是 | image下的非sendable的PixelMap。 | 259 260**返回值：** 261| 类型 | 说明 | 262| -------------------------------- | --------------------- | 263| [PixelMap](#pixelmap) | 成功同步返回sendable的PixelMap对象，失败抛出异常。 | 264 265**错误码：** 266 267以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 268 269| 错误码ID | 错误信息 | 270| ------- | --------------------------------------------| 271| 401 | If the image parameter invalid. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 272| 62980104 | Failed to initialize the internal object.| 273 274**示例：** 275 276```ts 277import { sendableImage } from '@kit.ImageKit'; 278import { image } from '@kit.ImageKit'; 279 280async function Demo() { 281 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 282 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 283 let pixelMap : image.PixelMap = image.createPixelMapSync(color, opts); 284 let sendablePixelMap : sendableImage.PixelMap = sendableImage.convertFromPixelMap(pixelMap); 285 return sendablePixelMap; 286} 287``` 288 289## sendableImage.convertToPixelMap 290 291convertToPixelMap(pixelmap: PixelMap): image.PixelMap 292 293通过sendableImage下的PixelMap创建出一个image下的PixelMap，同步返回PixelMap结果。原PixelMap的方法均不可再调用。 294 295**系统能力：** SystemCapability.Multimedia.Image.Core 296 297**参数：** 298 299| 参数名 | 类型 | 必填 | 说明 | 300| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 301| pixelmap | [PixelMap](#pixelmap) | 是 | sendableImage下的PixelMap。 | 302 303**返回值：** 304| 类型 | 说明 | 305| -------------------------------- | --------------------- | 306| [image.PixelMap](arkts-apis-image-PixelMap.md) | 成功同步返回image下的非sendable的PixelMap对象，失败抛出异常。 | 307 308**错误码：** 309 310以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 311 312| 错误码ID | 错误信息 | 313| ------- | --------------------------------------------| 314| 401 | If the image parameter invalid. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 315| 62980104 | Failed to initialize the internal object.| 316 317**示例：** 318 319```ts 320import { sendableImage } from '@kit.ImageKit'; 321import { image } from '@kit.ImageKit'; 322 323async function Demo() { 324 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 325 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 326 let sendablePixelMap : sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts); 327 let pixelMap : image.PixelMap = sendableImage.convertToPixelMap(sendablePixelMap); 328 return pixelMap; 329} 330``` 331 332## ISendable 333type ISendable = lang.ISendable 334 335ISendable是所有Sendable类型（除null和undefined）的父类型。自身没有任何必须的方法和属性。 336 337**系统能力：** SystemCapability.Multimedia.Image.Core 338 339| 类型 | 说明 | 340| ------------------ | ------------------------ | 341| [lang.ISendable](../apis-arkts/js-apis-arkts-lang.md#langisendable) | 所有Sendable类型的父类型。 | 342 343## PixelMap 344 345图像像素类，用于读取或写入图像数据以及获取图像信息。在调用PixelMap的方法前，需要先通过[createPixelMap](#sendableimagecreatepixelmap)创建一个PixelMap实例。目前pixelmap序列化大小最大128MB，超过会送显失败。大小计算方式为(宽\*高\*每像素占用字节数)。 346 347sendableImage下的PixelMap支持sendable属性，支持worker线程共享。sendableImage下的PixelMap，可以利用[Convert](#sendableimageconverttopixelmap)方法与image下的PixelMap进行互相转换。转换后，原对象的方法均不允许再调用，否则将报错501 无法调用接口。跨线程处理PixelMap时，需要考虑多线程问题。 348 349在调用PixelMap的方法前，需要先通过[sendableImage.createPixelMap](#sendableimagecreatepixelmap)构建一个PixelMap对象。 350 351### 属性 352 353**系统能力：** SystemCapability.Multimedia.Image.Core 354 355| 名称 | 类型 | 只读 | 可选 | 说明 | 356| -----------------| ------- | ---- | ---- | -------------------------- | 357| isEditable | boolean | 是 | 否 | true表示图像像素可被编辑，false表示不可被编辑。 <br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 358| isStrideAlignment | boolean | 是 | 否 | true表示图像内存为DMA内存，false表示非DMA内存。DMA内存的PixelMap会做256字节内存对齐，行末会存在padding区域。 | 359 360### readPixelsToBuffer 361 362readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 363 364读取图像像素数据，结果写入ArrayBuffer里，使用Promise形式返回。指定BGRA_8888格式创建pixelmap，读取的像素数据与原数据保持一致。 365 366**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 367 368**系统能力：** SystemCapability.Multimedia.Image.Core 369 370**参数：** 371 372| 参数名 | 类型 | 必填 | 说明 | 373| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 374| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber)接口获取。 | 375 376**返回值：** 377 378| 类型 | 说明 | 379| -------------- | ----------------------------------------------- | 380| Promise\<void> | Promise实例，用于获取结果，失败时返回错误信息。 | 381 382**示例：** 383 384```ts 385import { BusinessError } from '@kit.BasicServicesKit'; 386import { sendableImage } from '@kit.ImageKit'; 387 388async function Demo(pixelMap : sendableImage.PixelMap) { 389 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 390 if (pixelMap != undefined) { 391 pixelMap.readPixelsToBuffer(readBuffer).then(() => { 392 console.info('Succeeded in reading image pixel data.'); // 符合条件则进入。 393 }).catch((error: BusinessError) => { 394 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 395 }) 396 } 397} 398``` 399 400### readPixelsToBufferSync 401 402readPixelsToBufferSync(dst: ArrayBuffer): void 403 404以同步方法读取PixelMap到Buffer里。 405 406**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 407 408**系统能力：** SystemCapability.Multimedia.Image.Core 409 410**参数：** 411 412| 参数名 | 类型 | 必填 | 说明 | 413| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 414| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber)接口获取。 | 415 416**错误码：** 417 418以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 419 420| 错误码ID | 错误信息 | 421| ------- | --------------------------------------------| 422| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 423| 501 | Resource Unavailable. | 424 425**示例：** 426 427```ts 428import { sendableImage } from '@kit.ImageKit'; 429 430async function Demo(pixelMap: sendableImage.PixelMap) { 431 const bufferSize = pixelMap.getPixelBytesNumber(); 432 const readBuffer: ArrayBuffer = new ArrayBuffer(bufferSize); 433 if (pixelMap != undefined) { 434 pixelMap.readPixelsToBufferSync(readBuffer); 435 } 436} 437``` 438 439### readPixels 440 441readPixels(area: image.PositionArea): Promise\<void> 442 443读取区域内的图片数据，使用Promise形式返回。 444 445**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 446 447**系统能力：** SystemCapability.Multimedia.Image.Core 448 449**参数：** 450 451| 参数名 | 类型 | 必填 | 说明 | 452| ------ | ------------------------------ | ---- | ------------------------ | 453| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域大小，根据区域读取。 | 454 455**返回值：** 456 457| 类型 | 说明 | 458| :------------- | :-------------------------------------------------- | 459| Promise\<void> | Promise实例，用于获取读取结果，失败时返回错误信息。 | 460 461**示例：** 462 463```ts 464import { sendableImage } from '@kit.ImageKit'; 465import { image } from '@kit.ImageKit'; 466import { BusinessError } from '@kit.BasicServicesKit'; 467 468async function Demo(pixelMap : sendableImage.PixelMap) { 469 const area: image.PositionArea = { 470 pixels: new ArrayBuffer(8), 471 offset: 0, 472 stride: 8, 473 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 474 }; 475 if (pixelMap != undefined) { 476 pixelMap.readPixels(area).then(() => { 477 console.info('Succeeded in reading the image data in the area.'); // 符合条件则进入。 478 }).catch((error: BusinessError) => { 479 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 480 }) 481 } 482} 483``` 484 485### readPixelsSync 486 487readPixelsSync(area: image.PositionArea): void 488 489读取区域内的图片数据并同步返回结果。 490 491**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 492 493**系统能力：** SystemCapability.Multimedia.Image.Core 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| ------ | ------------------------------ | ---- | ------------------------ | 499| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域大小，根据区域读取。 | 500 501**错误码：** 502 503以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 504 505| 错误码ID | 错误信息 | 506| ------- | --------------------------------------------| 507| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 508| 501 | Resource Unavailable. | 509 510**示例：** 511 512```ts 513import { sendableImage } from '@kit.ImageKit'; 514import { image } from '@kit.ImageKit'; 515 516async function Demo(pixelMap : sendableImage.PixelMap) { 517 const area : image.PositionArea = { 518 pixels: new ArrayBuffer(8), 519 offset: 0, 520 stride: 8, 521 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 522 }; 523 if (pixelMap != undefined) { 524 pixelMap.readPixelsSync(area); 525 } 526} 527``` 528 529### writePixels 530 531writePixels(area: image.PositionArea): Promise\<void> 532 533将PixelMap写入指定区域内，使用Promise形式返回写入结果。 534 535**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 536 537**系统能力：** SystemCapability.Multimedia.Image.Core 538 539**参数：** 540 541| 参数名 | 类型 | 必填 | 说明 | 542| ------ | ------------------------------ | ---- | -------------------- | 543| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域，根据区域写入。 | 544 545**返回值：** 546 547| 类型 | 说明 | 548| :------------- | :-------------------------------------------------- | 549| Promise\<void> | Promise实例，用于获取写入结果，失败时返回错误信息。 | 550 551**示例：** 552 553```ts 554import { sendableImage } from '@kit.ImageKit'; 555import { image } from '@kit.ImageKit'; 556import { BusinessError } from '@kit.BasicServicesKit'; 557 558async function Demo(pixelMap : sendableImage.PixelMap) { 559 const area: image.PositionArea = { 560 pixels: new ArrayBuffer(8), 561 offset: 0, 562 stride: 8, 563 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 564 }; 565 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 566 for (let i = 0; i < bufferArr.length; i++) { 567 bufferArr[i] = i + 1; 568 } 569 if (pixelMap != undefined) { 570 pixelMap.writePixels(area).then(() => { 571 console.info('Succeeded to write pixelmap into the specified area.'); 572 }).catch((error: BusinessError) => { 573 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 574 }) 575 } 576} 577``` 578 579### writePixelsSync 580 581writePixelsSync(area: image.PositionArea): void 582 583以同步方法将PixelMap写入指定区域内。 584 585**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 586 587**系统能力：** SystemCapability.Multimedia.Image.Core 588 589**参数：** 590 591| 参数名 | 类型 | 必填 | 说明 | 592| ------ | ------------------------------ | ---- | -------------------- | 593| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域，根据区域写入。 | 594 595**错误码：** 596 597以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 598 599| 错误码ID | 错误信息 | 600| ------- | --------------------------------------------| 601| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 602| 501 | Resource Unavailable. | 603 604**示例：** 605 606```ts 607import { sendableImage } from '@kit.ImageKit'; 608import { image } from '@kit.ImageKit'; 609 610async function Demo(pixelMap : sendableImage.PixelMap) { 611 const area: image.PositionArea = { 612 pixels: new ArrayBuffer(8), 613 offset: 0, 614 stride: 8, 615 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 616 }; 617 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 618 for (let i = 0; i < bufferArr.length; i++) { 619 bufferArr[i] = i + 1; 620 } 621 if (pixelMap != undefined) { 622 pixelMap.writePixelsSync(area); 623 } 624} 625``` 626 627### writeBufferToPixels 628 629writeBufferToPixels(src: ArrayBuffer): Promise\<void> 630 631读取缓冲区中的图片数据，结果写入PixelMap中，使用Promise形式返回。 632 633**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 634 635**系统能力：** SystemCapability.Multimedia.Image.Core 636 637**参数：** 638 639| 参数名 | 类型 | 必填 | 说明 | 640| ------ | ----------- | ---- | -------------- | 641| src | ArrayBuffer | 是 | 图像像素数据。 | 642 643**返回值：** 644 645| 类型 | 说明 | 646| -------------- | ----------------------------------------------- | 647| Promise\<void> | Promise实例，用于获取结果，失败时返回错误信息。 | 648 649**示例：** 650 651```ts 652import { sendableImage } from '@kit.ImageKit'; 653import { BusinessError } from '@kit.BasicServicesKit'; 654 655async function Demo(pixelMap : sendableImage.PixelMap) { 656 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 657 let bufferArr: Uint8Array = new Uint8Array(color); 658 for (let i = 0; i < bufferArr.length; i++) { 659 bufferArr[i] = i + 1; 660 } 661 if (pixelMap != undefined) { 662 pixelMap.writeBufferToPixels(color).then(() => { 663 console.info("Succeeded in writing data from a buffer to a PixelMap."); 664 }).catch((error: BusinessError) => { 665 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 666 }) 667 } 668} 669``` 670 671### writeBufferToPixelsSync 672 673writeBufferToPixelsSync(src: ArrayBuffer): void 674 675读取缓冲区中的图片数据，结果写入PixelMap并同步返回结果。 676 677**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 678 679**系统能力：** SystemCapability.Multimedia.Image.Core 680 681**参数：** 682 683| 参数名 | 类型 | 必填 | 说明 | 684| ------ | ----------- | ---- | -------------- | 685| src | ArrayBuffer | 是 | 图像像素数据。 | 686 687**错误码：** 688 689以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 690 691| 错误码ID | 错误信息 | 692| ------- | --------------------------------------------| 693| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 694| 501 | Resource Unavailable. | 695 696**示例：** 697 698```ts 699import { sendableImage } from '@kit.ImageKit'; 700 701async function Demo(pixelMap: sendableImage.PixelMap) { 702 const bufferSize = pixelMap.getPixelBytesNumber(); 703 const color : ArrayBuffer = new ArrayBuffer(bufferSize); 704 let bufferArr : Uint8Array = new Uint8Array(color); 705 for (let i = 0; i < bufferArr.length; i++) { 706 bufferArr[i] = i + 1; 707 } 708 if (pixelMap != undefined) { 709 pixelMap.writeBufferToPixelsSync(color); 710 } 711} 712``` 713 714### getImageInfo 715 716getImageInfo(): Promise\<image.ImageInfo> 717 718获取图像像素信息，使用Promise形式返回获取的图像像素信息。 719 720**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 721 722**系统能力：** SystemCapability.Multimedia.Image.Core 723 724**返回值：** 725 726| 类型 | 说明 | 727| --------------------------------- | ----------------------------------------------------------- | 728| Promise\<[image.ImageInfo](arkts-apis-image-i.md#imageinfo)> | Promise实例，用于异步获取图像像素信息，失败时返回错误信息。 | 729 730**示例：** 731 732```ts 733import { sendableImage } from '@kit.ImageKit'; 734import { image } from '@kit.ImageKit'; 735import { BusinessError } from '@kit.BasicServicesKit'; 736 737async function Demo(pixelMap : sendableImage.PixelMap) { 738 if (pixelMap != undefined) { 739 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 740 if (imageInfo != undefined) { 741 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 742 } 743 }).catch((error: BusinessError) => { 744 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 745 }) 746 } 747} 748``` 749 750### getImageInfoSync 751 752getImageInfoSync(): image.ImageInfo 753 754以同步方法获取图像像素信息。 755 756**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 757 758**系统能力：** SystemCapability.Multimedia.Image.ImageSource 759 760**返回值：** 761 762| 类型 | 说明 | 763| --------------------------------- | ----------------------------------------------------------- | 764| [image.ImageInfo](arkts-apis-image-i.md#imageinfo) | 图像像素信息。 | 765 766**错误码：** 767 768以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 769 770| 错误码ID | 错误信息 | 771| ------- | --------------------------------------------| 772| 501 | Resource Unavailable | 773 774**示例：** 775 776```ts 777import { image } from '@kit.ImageKit'; 778import { sendableImage } from '@kit.ImageKit'; 779 780async function Demo(pixelMap : sendableImage.PixelMap) { 781 if (pixelMap != undefined) { 782 let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync(); 783 } 784} 785``` 786 787### getBytesNumberPerRow 788 789getBytesNumberPerRow(): number 790 791获取图像像素每行字节数。 792 793**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 794 795**系统能力：** SystemCapability.Multimedia.Image.Core 796 797**返回值：** 798 799| 类型 | 说明 | 800| ------ | -------------------- | 801| number | 图像像素的行字节数。 | 802 803**示例：** 804 805```ts 806import { sendableImage } from '@kit.ImageKit'; 807 808async function Demo(pixelMap : sendableImage.PixelMap) { 809 let rowCount: number = pixelMap.getBytesNumberPerRow(); 810} 811``` 812 813### getPixelBytesNumber 814 815getPixelBytesNumber(): number 816 817获取图像像素的总字节数。 818 819**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 820 821**系统能力：** SystemCapability.Multimedia.Image.Core 822 823**返回值：** 824 825| 类型 | 说明 | 826| ------ | -------------------- | 827| number | 图像像素的总字节数。 | 828 829**示例：** 830 831```ts 832import { sendableImage } from '@kit.ImageKit'; 833 834async function Demo(pixelMap : sendableImage.PixelMap) { 835 let pixelBytesNumber: number = pixelMap.getPixelBytesNumber(); 836} 837``` 838 839### getDensity 840 841getDensity():number 842 843获取当前图像像素的密度。 844 845**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 846 847**系统能力：** SystemCapability.Multimedia.Image.Core 848 849**返回值：** 850 851| 类型 | 说明 | 852| ------ | --------------- | 853| number | 图像像素的密度，单位为ppi。| 854 855**示例：** 856 857```ts 858import { sendableImage } from '@kit.ImageKit'; 859 860async function Demo(pixelMap : sendableImage.PixelMap) { 861 let getDensity: number = pixelMap.getDensity(); 862} 863``` 864 865### opacity 866 867opacity(rate: number): Promise\<void> 868 869通过设置透明比率来让PixelMap达到对应的透明效果，使用Promise形式返回。 870 871**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 872 873**系统能力：** SystemCapability.Multimedia.Image.Core 874 875**参数：** 876 877| 参数名 | 类型 | 必填 | 说明 | 878| ------ | ------ | ---- | --------------------------- | 879| rate | number | 是 | 透明比率的值，取值范围是(0,1]。| 880 881**返回值：** 882 883| 类型 | 说明 | 884| -------------- | ----------------------------------------------- | 885| Promise\<void> | Promise实例，用于获取结果，失败时返回错误信息。 | 886 887**示例：** 888 889```ts 890import { sendableImage } from '@kit.ImageKit'; 891import { BusinessError } from '@kit.BasicServicesKit'; 892 893async function Demo(pixelMap : sendableImage.PixelMap) { 894 let rate: number = 0.5; 895 if (pixelMap != undefined) { 896 pixelMap.opacity(rate).then(() => { 897 console.info('Succeeded in setting opacity.'); 898 }).catch((err: BusinessError) => { 899 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 900 }) 901 } 902} 903``` 904 905### opacitySync 906 907opacitySync(rate: number): void 908 909设置PixelMap的透明比率，初始化PixelMap。 910 911**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 912 913**系统能力：** SystemCapability.Multimedia.Image.Core 914 915**参数：** 916 917| 参数名 | 类型 | 必填 | 说明 | 918| -------- | -------------------- | ---- | ------------------------------ | 919| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 920 921**错误码：** 922 923以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 924 925| 错误码ID | 错误信息 | 926| ------- | --------------------------------------------| 927| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 928| 501 | Resource Unavailable. | 929 930**示例：** 931 932```ts 933import { sendableImage } from '@kit.ImageKit'; 934 935async function Demo(pixelMap : sendableImage.PixelMap) { 936 let rate : number = 0.5; 937 if (pixelMap != undefined) { 938 pixelMap.opacitySync(rate); 939 } 940} 941``` 942 943### createAlphaPixelmap 944 945createAlphaPixelmap(): Promise\<PixelMap> 946 947根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的PixelMap，可用于阴影效果，使用Promise形式返回。 948 949**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 950 951**系统能力：** SystemCapability.Multimedia.Image.Core 952 953**返回值：** 954 955| 类型 | 说明 | 956| -------------------------------- | --------------------------- | 957| Promise\<[PixelMap](#pixelmap)> | Promise实例，返回pixelmap。 | 958 959**示例：** 960 961```ts 962import { sendableImage } from '@kit.ImageKit'; 963import { BusinessError } from '@kit.BasicServicesKit'; 964 965async function Demo(pixelMap : sendableImage.PixelMap) { 966 if (pixelMap != undefined) { 967 pixelMap.createAlphaPixelmap().then((alphaPixelMap: sendableImage.PixelMap) => { 968 console.info('Succeeded in creating alpha pixelmap.'); 969 }).catch((error: BusinessError) => { 970 console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`); 971 }) 972 } 973} 974``` 975 976### createAlphaPixelmapSync 977 978createAlphaPixelmapSync(): PixelMap 979 980根据Alpha通道的信息，生成一个仅包含Alpha通道信息的PixelMap，可用于阴影效果，同步返回PixelMap类型的结果。 981 982**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 983 984**系统能力：** SystemCapability.Multimedia.Image.Core 985 986**返回值：** 987 988| 类型 | 说明 | 989| -------------------------------- | --------------------- | 990| [PixelMap](#pixelmap) | 成功同步返回PixelMap对象，失败抛出异常。 | 991 992**错误码：** 993 994以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 995 996| 错误码ID | 错误信息 | 997| ------- | --------------------------------------------| 998| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 999| 501 | Resource Unavailable. | 1000 1001**示例：** 1002 1003```ts 1004import { sendableImage } from '@kit.ImageKit'; 1005 1006async function Demo(pixelMap : sendableImage.PixelMap) { 1007 let resPixelMap : sendableImage.PixelMap = pixelMap.createAlphaPixelmapSync(); 1008 return resPixelMap; 1009} 1010``` 1011 1012### scale 1013 1014scale(x: number, y: number): Promise\<void> 1015 1016根据输入的宽高对图片进行缩放，使用Promise形式返回。 1017 1018**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1019 1020**系统能力：** SystemCapability.Multimedia.Image.Core 1021 1022**参数：** 1023 1024| 参数名 | 类型 | 必填 | 说明 | 1025| ------ | ------ | ---- | ------------------------------- | 1026| x | number | 是 | 宽度的缩放倍数。| 1027| y | number | 是 | 高度的缩放倍数。| 1028 1029**返回值：** 1030 1031| 类型 | 说明 | 1032| -------------- | --------------------------- | 1033| Promise\<void> | Promise实例，异步返回结果。 | 1034 1035**示例：** 1036 1037```ts 1038import { sendableImage } from '@kit.ImageKit'; 1039import { BusinessError } from '@kit.BasicServicesKit'; 1040 1041async function Demo(pixelMap : sendableImage.PixelMap) { 1042 let scaleX: number = 2.0; 1043 let scaleY: number = 1.0; 1044 if (pixelMap != undefined) { 1045 pixelMap.scale(scaleX, scaleY).then(() => { 1046 console.info('Succeeded in scaling pixelmap.'); 1047 }).catch((err: BusinessError) => { 1048 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 1049 1050 }) 1051 } 1052} 1053``` 1054 1055### scaleSync 1056 1057scaleSync(x: number, y: number): void 1058 1059以同步方法根据输入的宽高对图片进行缩放。 1060 1061**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1062 1063**系统能力：** SystemCapability.Multimedia.Image.Core 1064 1065**参数：** 1066 1067| 参数名 | 类型 | 必填 | 说明 | 1068| ------ | ------ | ---- | ------------------------------- | 1069| x | number | 是 | 宽度的缩放倍数。| 1070| y | number | 是 | 高度的缩放倍数。| 1071 1072**错误码：** 1073 1074以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 1075 1076| 错误码ID | 错误信息 | 1077| ------- | --------------------------------------------| 1078| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1079| 501 | Resource Unavailable. | 1080 1081**示例：** 1082 1083```ts 1084import { sendableImage } from '@kit.ImageKit'; 1085 1086async function Demo(pixelMap : sendableImage.PixelMap) { 1087 let scaleX: number = 2.0; 1088 let scaleY: number = 1.0; 1089 if (pixelMap != undefined) { 1090 pixelMap.scaleSync(scaleX, scaleY); 1091 } 1092} 1093``` 1094 1095### translate 1096 1097translate(x: number, y: number): Promise\<void> 1098 1099根据输入的坐标对图片进行位置变换，使用Promise形式返回。 1100 1101translate后的图片尺寸改变为：width+X，height+Y，建议translate后的图片尺寸宽高不超过屏幕的宽高。 1102 1103**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1104 1105**系统能力：** SystemCapability.Multimedia.Image.Core 1106 1107**参数：** 1108 1109| 参数名 | 类型 | 必填 | 说明 | 1110| ------ | ------ | ---- | ----------- | 1111| x | number | 是 | 区域横坐标。单位：像素。| 1112| y | number | 是 | 区域纵坐标。单位：像素。| 1113 1114**返回值：** 1115 1116| 类型 | 说明 | 1117| -------------- | --------------------------- | 1118| Promise\<void> | Promise实例，异步返回结果。 | 1119 1120**示例：** 1121 1122```ts 1123import { sendableImage } from '@kit.ImageKit'; 1124import { BusinessError } from '@kit.BasicServicesKit'; 1125 1126async function Demo(pixelMap : sendableImage.PixelMap) { 1127 let translateX: number = 50.0; 1128 let translateY: number = 10.0; 1129 if (pixelMap != undefined) { 1130 pixelMap.translate(translateX, translateY).then(() => { 1131 console.info('Succeeded in translating pixelmap.'); 1132 }).catch((err: BusinessError) => { 1133 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 1134 }) 1135 } 1136} 1137``` 1138 1139### translateSync 1140 1141translateSync(x: number, y: number): void 1142 1143根据输入的坐标对图片进行位置变换并同步返回结果。 1144 1145translate后的图片尺寸改变为：width+X，height+Y，建议translate后的图片尺寸宽高不超过屏幕的宽高。 1146 1147**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1148 1149**系统能力：** SystemCapability.Multimedia.Image.Core 1150 1151**参数：** 1152 1153| 参数名 | 类型 | 必填 | 说明 | 1154| -------- | -------------------- | ---- | ------------------------------- | 1155| x | number | 是 | 宽度的缩放倍数。| 1156| y | number | 是 | 高度的缩放倍数。| 1157 1158**错误码：** 1159 1160以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 1161 1162| 错误码ID | 错误信息 | 1163| ------- | --------------------------------------------| 1164| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1165| 501 | Resource Unavailable. | 1166 1167**示例：** 1168 1169```ts 1170import { sendableImage } from '@kit.ImageKit'; 1171 1172async function Demo(pixelMap : sendableImage.PixelMap) { 1173 let translateX : number = 50.0; 1174 let translateY : number = 10.0; 1175 if (pixelMap != undefined) { 1176 pixelMap.translateSync(translateX, translateY); 1177 } 1178} 1179``` 1180 1181### rotate 1182 1183rotate(angle: number): Promise\<void> 1184 1185根据输入的角度对图片进行旋转，使用Promise形式返回。 1186 1187> **说明：** 1188> 1189> - 图片旋转的角度取值范围：[0, 360]。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 1190> - 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 1191 1192**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1193 1194**系统能力：** SystemCapability.Multimedia.Image.Core 1195 1196**参数：** 1197 1198| 参数名 | 类型 | 必填 | 说明 | 1199| ------ | ------ | ---- | ----------------------------- | 1200| angle | number | 是 | 图片旋转的角度。 | 1201 1202**返回值：** 1203 1204| 类型 | 说明 | 1205| -------------- | --------------------------- | 1206| Promise\<void> | Promise实例，异步返回结果。 | 1207 1208**示例：** 1209 1210```ts 1211import { sendableImage } from '@kit.ImageKit'; 1212import { BusinessError } from '@kit.BasicServicesKit'; 1213 1214async function Demo(pixelMap : sendableImage.PixelMap) { 1215 let angle: number = 90.0; 1216 if (pixelMap != undefined) { 1217 pixelMap.rotate(angle).then(() => { 1218 console.info('Succeeded in rotating pixelmap.'); 1219 }).catch((err: BusinessError) => { 1220 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 1221 }) 1222 } 1223} 1224``` 1225 1226### rotateSync 1227 1228rotateSync(angle: number): void 1229 1230根据输入的角度对图片进行旋转并同步返回结果。 1231 1232> **说明：** 1233> 1234> - 图片旋转的角度取值范围：[0, 360]。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 1235> - 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 1236 1237**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1238 1239**系统能力：** SystemCapability.Multimedia.Image.Core 1240 1241**参数：** 1242 1243| 参数名 | 类型 | 必填 | 说明 | 1244| -------- | -------------------- | ---- | ----------------------------- | 1245| angle | number | 是 | 图片旋转的角度。 | 1246 1247**错误码：** 1248 1249以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 1250 1251| 错误码ID | 错误信息 | 1252| ------- | --------------------------------------------| 1253| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1254| 501 | Resource Unavailable. | 1255 1256**示例：** 1257 1258```ts 1259import { sendableImage } from '@kit.ImageKit'; 1260 1261async function Demo(pixelMap : sendableImage.PixelMap) { 1262 let angle : number = 90.0; 1263 if (pixelMap != undefined) { 1264 pixelMap.rotateSync(angle); 1265 } 1266} 1267``` 1268 1269### flip 1270 1271flip(horizontal: boolean, vertical: boolean): Promise\<void> 1272 1273根据输入的条件对图片进行翻转，使用Promise形式返回。 1274 1275**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1276 1277**系统能力：** SystemCapability.Multimedia.Image.Core 1278 1279**参数：** 1280 1281| 参数名 | 类型 | 必填 | 说明 | 1282| ---------- | ------- | ---- | --------- | 1283| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 1284| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 1285 1286**返回值：** 1287 1288| 类型 | 说明 | 1289| -------------- | --------------------------- | 1290| Promise\<void> | Promise实例，异步返回结果。 | 1291 1292**示例：** 1293 1294```ts 1295import { sendableImage } from '@kit.ImageKit'; 1296import { BusinessError } from '@kit.BasicServicesKit'; 1297 1298async function Demo(pixelMap : sendableImage.PixelMap) { 1299 let horizontal: boolean = true; 1300 let vertical: boolean = false; 1301 if (pixelMap != undefined) { 1302 pixelMap.flip(horizontal, vertical).then(() => { 1303 console.info('Succeeded in flipping pixelmap.'); 1304 }).catch((err: BusinessError) => { 1305 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 1306 1307 }) 1308 } 1309} 1310``` 1311 1312### flipSync 1313 1314flipSync(horizontal: boolean, vertical: boolean): void 1315 1316根据输入的条件对图片进行翻转并同步返回结果。 1317 1318**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1319 1320**系统能力：** SystemCapability.Multimedia.Image.Core 1321 1322**参数：** 1323 1324| 参数名 | 类型 | 必填 | 说明 | 1325| ---------- | -------------------- | ---- | ----------------------------- | 1326| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 1327| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 1328 1329**错误码：** 1330 1331以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 1332 1333| 错误码ID | 错误信息 | 1334| ------- | --------------------------------------------| 1335| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1336| 501 | Resource Unavailable. | 1337 1338**示例：** 1339 1340```ts 1341import { sendableImage } from '@kit.ImageKit'; 1342 1343async function Demo(pixelMap : sendableImage.PixelMap) { 1344 let horizontal : boolean = true; 1345 let vertical : boolean = false; 1346 if (pixelMap != undefined) { 1347 pixelMap.flipSync(horizontal, vertical); 1348 } 1349} 1350``` 1351 1352### crop 1353 1354crop(region: image.Region): Promise\<void> 1355 1356根据输入的尺寸对图片进行裁剪，使用Promise形式返回。 1357 1358**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1359 1360**系统能力：** SystemCapability.Multimedia.Image.Core 1361 1362**参数：** 1363 1364| 参数名 | 类型 | 必填 | 说明 | 1365| ------ | ------------------ | ---- | ----------- | 1366| region | [image.Region](../apis-image-kit/arkts-apis-image-i.md#region8) | 是 | 裁剪的尺寸。| 1367 1368**返回值：** 1369 1370| 类型 | 说明 | 1371| -------------- | --------------------------- | 1372| Promise\<void> | Promise实例，异步返回结果。 | 1373 1374**示例：** 1375 1376```ts 1377import { sendableImage } from '@kit.ImageKit'; 1378import { image } from '@kit.ImageKit'; 1379import { BusinessError } from '@kit.BasicServicesKit'; 1380 1381async function Demo(pixelMap : sendableImage.PixelMap) { 1382 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1383 if (pixelMap != undefined) { 1384 pixelMap.crop(region).then(() => { 1385 console.info('Succeeded in cropping pixelmap.'); 1386 }).catch((err: BusinessError) => { 1387 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 1388 1389 }); 1390 } 1391} 1392``` 1393 1394### cropSync 1395 1396cropSync(region: image.Region): void 1397 1398根据输入的尺寸裁剪图片。 1399 1400**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1401 1402**系统能力：** SystemCapability.Multimedia.Image.Core 1403 1404**参数：** 1405 1406| 参数名 | 类型 | 必填 | 说明 | 1407| -------- | -------------------- | ---- | ----------------------------- | 1408| region | [image.Region](../apis-image-kit/arkts-apis-image-i.md#region8) | 是 | 裁剪的尺寸。 | 1409 1410**错误码：** 1411 1412以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 1413 1414| 错误码ID | 错误信息 | 1415| ------- | --------------------------------------------| 1416| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1417| 501 | Resource Unavailable. | 1418 1419**示例：** 1420 1421```ts 1422import { sendableImage } from '@kit.ImageKit'; 1423import { image } from '@kit.ImageKit'; 1424 1425async function Demo(pixelMap : sendableImage.PixelMap) { 1426 let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1427 if (pixelMap != undefined) { 1428 pixelMap.cropSync(region); 1429 } 1430} 1431``` 1432 1433### getColorSpace 1434 1435getColorSpace(): colorSpaceManager.ColorSpaceManager 1436 1437获取图像广色域信息。 1438 1439**系统能力：** SystemCapability.Multimedia.Image.Core 1440 1441**返回值：** 1442 1443| 类型 | 说明 | 1444| ----------------------------------- | ---------------- | 1445| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 图像广色域信息。 | 1446 1447**错误码：** 1448 1449以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1450 1451| 错误码ID | 错误信息 | 1452| ------- | --------------------------------------------| 1453| 62980101| If the image data abnormal. | 1454| 62980103| If the image data unsupport. | 1455| 62980115| If the image parameter invalid. | 1456 1457**示例：** 1458 1459```ts 1460import { sendableImage } from '@kit.ImageKit'; 1461 1462async function Demo(pixelMap : sendableImage.PixelMap) { 1463 if (pixelMap != undefined) { 1464 let csm = pixelMap.getColorSpace(); 1465 } 1466} 1467``` 1468 1469### setColorSpace 1470 1471setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void 1472 1473设置图像广色域信息。 1474 1475**系统能力：** SystemCapability.Multimedia.Image.Core 1476 1477**参数：** 1478 1479| 参数名 | 类型 | 必填 | 说明 | 1480| ---------- | ----------------------------------- | ---- | --------------- | 1481| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 图像广色域信息。| 1482 1483**错误码：** 1484 1485以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1486 1487| 错误码ID | 错误信息 | 1488| ------- | --------------------------------------------| 1489| 62980111| If the operation invalid. | 1490| 62980115| If the image parameter invalid. | 1491 1492**示例：** 1493 1494```ts 1495import { sendableImage } from '@kit.ImageKit'; 1496import { colorSpaceManager } from '@kit.ArkGraphics2D'; 1497 1498async function Demo(pixelMap : sendableImage.PixelMap) { 1499 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 1500 let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 1501 if (pixelMap != undefined) { 1502 pixelMap.setColorSpace(csm); 1503 } 1504} 1505``` 1506 1507### applyColorSpace 1508 1509applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void> 1510 1511根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用Promise形式返回。 1512 1513**系统能力：** SystemCapability.Multimedia.Image.Core 1514 1515**参数：** 1516 1517| 参数名 | 类型 | 必填 | 说明 | 1518| ------ | ------------------ | ---- | ----------- | 1519| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 1520 1521**返回值：** 1522 1523| 类型 | 说明 | 1524| -------------- | --------------------------- | 1525| Promise\<void> | Promise实例，异步返回结果。 | 1526 1527**错误码：** 1528 1529以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 1530 1531| 错误码ID | 错误信息 | 1532| ------- | ------------------------------------------| 1533| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1534| 62980104| Failed to initialize the internal object. | 1535| 62980108| Failed to convert the color space. | 1536| 62980115| Invalid image parameter. | 1537 1538**示例：** 1539 1540```ts 1541import { sendableImage } from '@kit.ImageKit'; 1542import { colorSpaceManager } from '@kit.ArkGraphics2D'; 1543import { BusinessError } from '@kit.BasicServicesKit'; 1544 1545async function Demo(pixelMap : sendableImage.PixelMap) { 1546 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 1547 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 1548 pixelMap.applyColorSpace(targetColorSpace).then(() => { 1549 console.info('Succeeded in applying color space for pixelmap object.'); 1550 }).catch((error: BusinessError) => { 1551 console.error(`Failed to apply color space for pixelmap object. code is ${error.code}, message is ${error.message}`); 1552 }) 1553} 1554``` 1555 1556### marshalling 1557 1558marshalling(sequence: rpc.MessageSequence): void 1559 1560将PixelMap序列化后写入MessageSequence。 1561 1562**系统能力：** SystemCapability.Multimedia.Image.Core 1563 1564**参数：** 1565 1566| 参数名 | 类型 | 必填 | 说明 | 1567| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 1568| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 1569 1570**错误码：** 1571 1572以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1573 1574| 错误码ID | 错误信息 | 1575| ------- | --------------------------------------------| 1576| 62980115 | Invalid image parameter. | 1577| 62980097 | IPC error. | 1578 1579**示例：** 1580 1581```ts 1582import { sendableImage } from '@kit.ImageKit'; 1583import { image } from '@kit.ImageKit'; 1584import { rpc } from '@kit.IPCKit'; 1585 1586class MySequence implements rpc.Parcelable { 1587 pixel_map: sendableImage.PixelMap; 1588 constructor(conPixelMap : sendableImage.PixelMap) { 1589 this.pixel_map = conPixelMap; 1590 } 1591 marshalling(messageSequence : rpc.MessageSequence) { 1592 this.pixel_map.marshalling(messageSequence); 1593 console.info('marshalling'); 1594 return true; 1595 } 1596 unmarshalling(messageSequence : rpc.MessageSequence) { 1597 sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: sendableImage.PixelMap) => { 1598 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: sendableImage.PixelMap) => { 1599 this.pixel_map = pixelMap; 1600 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 1601 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 1602 }) 1603 }) 1604 }); 1605 return true; 1606 } 1607} 1608 1609async function Demo() { 1610 const color: ArrayBuffer = new ArrayBuffer(96); 1611 let bufferArr: Uint8Array = new Uint8Array(color); 1612 for (let i = 0; i < bufferArr.length; i++) { 1613 bufferArr[i] = 0x80; 1614 } 1615 let opts: image.InitializationOptions = { 1616 editable: true, 1617 pixelFormat: 4, 1618 size: { height: 4, width: 6 }, 1619 alphaType: 3 1620 } 1621 let pixelMap: sendableImage.PixelMap | undefined = undefined; 1622 await sendableImage.createPixelMap(color, opts).then((srcPixelMap: sendableImage.PixelMap) => { 1623 pixelMap = srcPixelMap; 1624 }) 1625 if (pixelMap != undefined) { 1626 // 序列化。 1627 let parcelable: MySequence = new MySequence(pixelMap); 1628 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 1629 data.writeParcelable(parcelable); 1630 1631 // 反序列化rpc获取到data。 1632 let ret: MySequence = new MySequence(pixelMap); 1633 data.readParcelable(ret); 1634 } 1635} 1636``` 1637 1638### unmarshalling 1639 1640unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap> 1641 1642从MessageSequence中获取PixelMap， 1643如需使用同步方式创建PixelMap可使用：[createPixelMapFromParcel](#sendableimagecreatepixelmapfromparcel)。 1644 1645**系统能力：** SystemCapability.Multimedia.Image.Core 1646 1647**参数：** 1648 1649| 参数名 | 类型 | 必填 | 说明 | 1650| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 1651| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 1652 1653**返回值：** 1654 1655| 类型 | 说明 | 1656| -------------------------------- | --------------------- | 1657| Promise\<[PixelMap](#pixelmap)> | Promise实例，用于异步获取结果，失败时返回错误信息。 | 1658 1659**错误码：** 1660 1661以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1662 1663| 错误码ID | 错误信息 | 1664| ------- | --------------------------------------------| 1665| 62980115 | Invalid image parameter. | 1666| 62980097 | IPC error. | 1667| 62980096 | The operation failed. | 1668 1669**示例：** 1670 1671```ts 1672import { sendableImage } from '@kit.ImageKit'; 1673import { image } from '@kit.ImageKit'; 1674import { rpc } from '@kit.IPCKit'; 1675 1676class MySequence implements rpc.Parcelable { 1677 pixel_map: sendableImage.PixelMap; 1678 constructor(conPixelMap: sendableImage.PixelMap) { 1679 this.pixel_map = conPixelMap; 1680 } 1681 marshalling(messageSequence: rpc.MessageSequence) { 1682 this.pixel_map.marshalling(messageSequence); 1683 console.info('marshalling'); 1684 return true; 1685 } 1686 unmarshalling(messageSequence: rpc.MessageSequence) { 1687 sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : sendableImage.PixelMap) => { 1688 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : sendableImage.PixelMap) => { 1689 this.pixel_map = pixelMap; 1690 pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => { 1691 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 1692 }) 1693 }) 1694 }); 1695 return true; 1696 } 1697} 1698 1699async function Demo() { 1700 const color: ArrayBuffer = new ArrayBuffer(96); 1701 let bufferArr: Uint8Array = new Uint8Array(color); 1702 for (let i = 0; i < bufferArr.length; i++) { 1703 bufferArr[i] = 0x80; 1704 } 1705 let opts: image.InitializationOptions = { 1706 editable: true, 1707 pixelFormat: 4, 1708 size: { height: 4, width: 6 }, 1709 alphaType: 3 1710 } 1711 let pixelMap: sendableImage.PixelMap | undefined = undefined; 1712 await sendableImage.createPixelMap(color, opts).then((srcPixelMap : sendableImage.PixelMap) => { 1713 pixelMap = srcPixelMap; 1714 }) 1715 if (pixelMap != undefined) { 1716 // 序列化。 1717 let parcelable: MySequence = new MySequence(pixelMap); 1718 let data : rpc.MessageSequence = rpc.MessageSequence.create(); 1719 data.writeParcelable(parcelable); 1720 1721 // 反序列化rpc获取到data。 1722 let ret : MySequence = new MySequence(pixelMap); 1723 data.readParcelable(ret); 1724 } 1725} 1726``` 1727 1728### release 1729 1730release():Promise\<void> 1731 1732释放PixelMap对象，使用Promise形式返回释放结果。 1733 1734**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1735 1736**系统能力：** SystemCapability.Multimedia.Image.Core 1737 1738**返回值：** 1739 1740| 类型 | 说明 | 1741| -------------- | ------------------------------- | 1742| Promise\<void> | Promise实例，异步返回释放结果。 | 1743 1744**示例：** 1745 1746```ts 1747import { BusinessError } from '@kit.BasicServicesKit'; 1748import { sendableImage } from '@kit.ImageKit'; 1749 1750async function Demo(pixelMap: sendableImage.PixelMap) { 1751 if (pixelMap != undefined) { 1752 await pixelMap.release().then(() => { 1753 console.info('Succeeded in releasing pixelmap object.'); 1754 }).catch((error: BusinessError) => { 1755 console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`); 1756 }) 1757 } 1758} 1759``` 1760 1761## Size 1762 1763表示图片尺寸。 1764继承自[lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable)。 1765 1766**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1767 1768**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1769 1770**系统能力：** SystemCapability.Multimedia.Image.Core 1771 1772| 名称 | 类型 | 只读 | 可选 | 说明 | 1773| ------ | ------ | ---- | ---- | -------------- | 1774| height | number | 否 | 否 | 输出图片的高，单位：像素。 | 1775| width | number | 否 | 否 | 输出图片的宽，单位：像素。 | 1776 1777## Region 1778 1779表示区域信息。 1780继承自[lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable)。 1781 1782**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1783 1784**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1785 1786**系统能力：** SystemCapability.Multimedia.Image.Core 1787 1788| 名称 | 类型 | 只读 | 可选 | 说明 | 1789| ---- | ------------- | ---- | ---- | ------------ | 1790| size | [Size](#size) | 否 | 否 | 区域大小。 | 1791| x | number | 否 | 否 | 区域横坐标。单位：像素。 | 1792| y | number | 否 | 否 | 区域纵坐标。单位：像素。 | 1793 1794## sendableImage.createImageSource 1795 1796createImageSource(uri: string): ImageSource 1797 1798通过传入的uri创建ImageSource实例。 1799 1800 1801**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1802 1803**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1804 1805**参数：** 1806 1807| 参数名 | 类型 | 必填 | 说明 | 1808| ------ | ------ | ---- | ---------------------------------- | 1809| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng [SVG](arkts-apis-image-f.md#svg标签说明) .ico。 | 1810 1811**返回值：** 1812 1813| 类型 | 说明 | 1814| --------------------------- | -------------------------------------------- | 1815| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 1816 1817**示例：** 1818 1819```ts 1820import { sendableImage } from '@kit.ImageKit'; 1821 1822async function Demo(context : Context) { 1823 const path: string = context.cacheDir + "/test.jpg"; 1824 const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(path); 1825} 1826``` 1827 1828## sendableImage.createImageSource 1829 1830createImageSource(fd: number): ImageSource 1831 1832通过传入文件描述符来创建ImageSource实例。 1833 1834**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1835 1836**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1837 1838**参数：** 1839 1840| 参数名 | 类型 | 必填 | 说明 | 1841| ------ | ------ | ---- | ------------- | 1842| fd | number | 是 | 文件描述符fd。| 1843 1844**返回值：** 1845 1846| 类型 | 说明 | 1847| --------------------------- | -------------------------------------------- | 1848| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 1849 1850**示例：** 1851 1852```ts 1853import { sendableImage } from '@kit.ImageKit'; 1854import { fileIo as fs } from '@kit.CoreFileKit'; 1855 1856async function Demo(context : Context) { 1857 const path: string = context.cacheDir + "/test.jpg"; 1858 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 1859 const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(file.fd); 1860} 1861``` 1862 1863## sendableImage.createImageSource 1864 1865createImageSource(buf: ArrayBuffer): ImageSource 1866 1867通过缓冲区创建ImageSource实例。 1868 1869**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1870 1871**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1872 1873**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1874 1875**参数：** 1876 1877| 参数名 | 类型 | 必填 | 说明 | 1878| ------ | ----------- | ---- | ---------------- | 1879| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 1880 1881**返回值：** 1882 1883| 类型 | 说明 | 1884| --------------------------- | -------------------------------------------- | 1885| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 1886 1887**示例：** 1888 1889```ts 1890import { sendableImage } from '@kit.ImageKit'; 1891 1892async function Demo() { 1893 const buf: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1894 const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(buf); 1895} 1896``` 1897 1898## sendableImage.createImageReceiver 1899 1900createImageReceiver(size: image.Size, format: image.ImageFormat, capacity: number): ImageReceiver 1901 1902通过图片大小、图片格式、容量创建ImageReceiver实例。 1903 1904**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 1905 1906**参数：** 1907 1908| 参数名 | 类型 | 必填 | 说明 | 1909| -------- | ------ | ---- | ---------------------- | 1910| size | [image.Size](./arkts-apis-image-i.md#size) | 是 | 图像的默认大小。 | 1911| format | [image.ImageFormat](./arkts-apis-image-e.md#imageformat9) | 是 | 图像格式，取值为image.ImageFormat常量，目前仅支持 ImageFormat:JPEG。 | 1912| capacity | number | 是 | 同时访问的最大图像数。该参数仅作为期望值，实际capacity由设备硬件决定。 | 1913 1914**返回值：** 1915 1916| 类型 | 说明 | 1917| -------------------------------- | --------------------------------------- | 1918| [ImageReceiver](#imagereceiver) | 如果操作成功，则返回ImageReceiver实例。 | 1919 1920**错误码：** 1921 1922以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1923 1924| 错误码ID | 错误信息 | 1925| ------- | --------------------------------------------| 1926| 401 | The parameter check failed. | 1927 1928**示例：** 1929 1930```ts 1931import { sendableImage } from '@kit.ImageKit'; 1932import { image } from '@kit.ImageKit'; 1933 1934async function Demo() { 1935 let size: image.Size = { 1936 height: 8192, 1937 width: 8 1938 } 1939 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 1940} 1941``` 1942 1943## ImageSource 1944 1945ImageSource类，用于获取图片相关信息。在调用ImageSource的方法前，需要先通过[createImageSource](#sendableimagecreateimagesource)构建一个ImageSource实例。 1946 1947 1948### createPixelMap 1949 1950createPixelMap(options?: image.DecodingOptions): Promise\<PixelMap> 1951 1952通过图片解码参数创建PixelMap对象。 1953 1954**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1955 1956**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1957 1958**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1959 1960**参数：** 1961 1962| 参数名 | 类型 | 必填 | 说明 | 1963| ------- | ------------------------------------ | ---- | ---------- | 1964| options | [image.DecodingOptions](./arkts-apis-image-i.md#decodingoptions7) | 否 | 解码参数。 | 1965 1966**返回值：** 1967 1968| 类型 | 说明 | 1969| -------------------------------- | --------------------- | 1970| Promise\<[PixelMap]> | Promise实例，用于异步返回创建结果。 | 1971 1972**示例：** 1973 1974```ts 1975import { sendableImage } from '@kit.ImageKit'; 1976import { BusinessError } from '@kit.BasicServicesKit'; 1977 1978async function Demo(context : Context) { 1979 const path: string = context.cacheDir + "/test.jpg"; 1980 const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(path); 1981 sendableImageSourceObj.createPixelMap().then((pixelMap: sendableImage.PixelMap) => { 1982 console.info('Succeeded in creating pixelMap object through image decoding parameters.'); 1983 }).catch((error: BusinessError) => { 1984 console.error(`Failed to create pixelMap object through image decoding parameters. code ${error.code}, message is ${error.message}`); 1985 }) 1986} 1987``` 1988 1989### release 1990 1991release(): Promise\<void> 1992 1993释放ImageSource实例，使用Promise形式返回结果。release是线程不安全的。 1994 1995**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1996 1997**返回值：** 1998 1999| 类型 | 说明 | 2000| -------------- | --------------------------- | 2001| Promise\<void> | Promise实例，异步返回结果。 | 2002 2003**示例：** 2004 2005```ts 2006import { sendableImage } from '@kit.ImageKit'; 2007import { BusinessError } from '@kit.BasicServicesKit'; 2008 2009async function Demo(context : Context) { 2010 const path: string = context.cacheDir + "/test.jpg"; 2011 const sendableImageSourceObj: sendableImage.ImageSource = sendableImage.createImageSource(path); 2012 sendableImageSourceObj.release().then(() => { 2013 console.info('Succeeded in releasing the image source instance.'); 2014 }).catch((error: BusinessError) => { 2015 console.error(`Failed to release the image source instance. code ${error.code}, message is ${error.message}`); 2016 }) 2017} 2018``` 2019 2020## Image 2021 2022提供基本的图像操作，包括获取图像信息、读写图像数据。调用[readNextImage](#readnextimage)和[readLatestImage](#readlatestimage)接口时会返回image。继承自[lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable)。 2023 2024### 属性 2025 2026**系统能力：** SystemCapability.Multimedia.Image.Core 2027 2028| 名称 | 类型 | 只读 | 可选 | 说明 | 2029| -------- | ------------------ | ---- | ---- | -------------------------------------------------- | 2030| clipRect | [Region](#region) | 否 | 否 | 要裁剪的图像区域。 | 2031| size | [Size](#size) | 是 | 否 | 图像大小。如果image对象所存储的是相机预览流数据，即YUV图像数据，那么获取到的size中的宽高分别对应YUV图像的宽高； 如果image对象所存储的是相机拍照流数据，即JPEG图像，由于已经是编码后的文件，size中的宽等于JPEG文件大小，高等于1。image对象所存储的数据是预览流还是拍照流，取决于应用将receiver中的surfaceId传给相机的previewOutput还是captureOutput。相机预览与拍照最佳实践请参考[双路预览(ArkTS)](../../media/camera/camera-dual-channel-preview.md)与[拍照实现方案(ArkTS)](../../media/camera/camera-shooting-case.md)。 | 2032| format | number | 是 | 否 | 图像格式，参考[OH_NativeBuffer_Format](../apis-arkgraphics2d/capi-native-buffer-h.md#oh_nativebuffer_format)。 | 2033| timestamp<sup>12+</sup> | number | 是 | 否 | 图像时间戳。时间戳以纳秒为单位，通常是单调递增的。时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。如果要获取某张照片的生成时间，可以通过[getImageProperty](arkts-apis-image-ImageSource.md#getimageproperty11)接口读取相关的EXIF信息。| 2034 2035### getComponent 2036 2037getComponent(componentType: image.ComponentType): Promise\<image.Component> 2038 2039根据图像的组件类型从图像中获取组件缓存并使用Promise方式返回结果。getComponent是线程不安全的。 2040 2041**系统能力：** SystemCapability.Multimedia.Image.Core 2042 2043**参数：** 2044 2045| 参数名 | 类型 | 必填 | 说明 | 2046| ------------- | -------------------------------- | ---- | ---------------- | 2047| componentType | [image.ComponentType](./arkts-apis-image-e.md#componenttype9) | 是 | 图像的组件类型。 | 2048 2049**返回值：** 2050 2051| 类型 | 说明 | 2052| --------------------------------- | --------------------------------- | 2053| Promise<[image.Component](./arkts-apis-image-i.md#component9)> | Promise实例，用于异步返回组件缓冲区。 | 2054 2055**示例：** 2056 2057```ts 2058import { sendableImage } from '@kit.ImageKit'; 2059import { BusinessError } from '@kit.BasicServicesKit'; 2060import { image } from '@kit.ImageKit'; 2061 2062async function Demo() { 2063 let size: image.Size = { 2064 height: 8192, 2065 width: 8 2066 } 2067 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2068 let img = await receiver.readNextImage(); 2069 img.getComponent(image.ComponentType.JPEG).then((component: image.Component) => { 2070 console.info('getComponent succeeded.'); 2071 }).catch((error: BusinessError) => { 2072 console.error(`getComponent failed code ${error.code}, message is ${error.message}`); 2073 }) 2074} 2075``` 2076 2077### release 2078 2079release(): Promise\<void> 2080 2081释放当前图像并使用Promise方式返回结果。 2082 2083在接收另一个图像前必须先释放对应资源。release是线程不安全的。 2084 2085 2086**系统能力：** SystemCapability.Multimedia.Image.Core 2087 2088**返回值：** 2089 2090| 类型 | 说明 | 2091| -------------- | --------------------- | 2092| Promise\<void> | promise返回操作结果。 | 2093 2094**示例：** 2095 2096```ts 2097import { sendableImage } from '@kit.ImageKit'; 2098import { BusinessError } from '@kit.BasicServicesKit'; 2099import { image } from '@kit.ImageKit'; 2100 2101async function Demo() { 2102 let size: image.Size = { 2103 height: 8192, 2104 width: 8 2105 } 2106 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2107 let img = await receiver.readNextImage(); 2108 img.release().then(() => { 2109 console.info('release succeeded.'); 2110 }).catch((error: BusinessError) => { 2111 console.error(`release failed. code ${error.code}, message is ${error.message}`); 2112 }) 2113} 2114``` 2115 2116## ImageReceiver 2117 2118图像接收类，用于获取组件surface id，接收最新的图片和读取下一张图片，以及释放ImageReceiver实例。 2119 2120在调用以下方法前需要先创建ImageReceiver实例。 2121 2122### 属性 2123 2124**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 2125 2126| 名称 | 类型 | 只读 | 可选 | 说明 | 2127| -------- | ---------------------------- | ---- | ---- | ------------------ | 2128| size | [image.Size](./arkts-apis-image-i.md#size) | 是 | 否 | 图片大小。 | 2129| capacity | number | 是 | 否 | 同时访问的图像数。该参数仅作为期望值，实际capacity由设备硬件决定。 | 2130| format | [image.ImageFormat](./arkts-apis-image-e.md#imageformat9) | 是 | 否 | 图像格式。 | 2131 2132### getReceivingSurfaceId 2133 2134getReceivingSurfaceId(): Promise\<string> 2135 2136用于获取一个surface id供Camera或其他组件使用。使用promise返回结果。 2137 2138**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 2139 2140**返回值：** 2141 2142| 类型 | 说明 | 2143| ---------------- | -------------------- | 2144| Promise\<string> | 异步返回surface id。 | 2145 2146**示例：** 2147 2148```ts 2149import { sendableImage } from '@kit.ImageKit'; 2150import { BusinessError } from '@kit.BasicServicesKit'; 2151import { image } from '@kit.ImageKit'; 2152 2153async function Demo() { 2154 let size: image.Size = { 2155 height: 8192, 2156 width: 8 2157 } 2158 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2159 receiver.getReceivingSurfaceId().then((id: string) => { 2160 console.info('Succeeded in getting the ReceivingSurfaceId.'); 2161 }).catch((error: BusinessError) => { 2162 console.error(`Failed to get the ReceivingSurfaceId.code ${error.code}, message is ${error.message}`); 2163 }) 2164} 2165``` 2166 2167### readLatestImage 2168 2169readLatestImage(): Promise\<Image> 2170 2171从ImageReceiver读取最新的图片，并使用promise返回结果。 2172 2173**注意**：此接口需要在[on](#on)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image)对象使用完毕后需要调用[release](#release-2)方法释放，释放后才可以继续接收新的数据。 2174 2175**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 2176 2177**返回值：** 2178 2179| 类型 | 说明 | 2180| ------------------------- | ------------------ | 2181| Promise<[Image](#image)> | 异步返回最新图片。 | 2182 2183**示例：** 2184 2185```ts 2186import { sendableImage } from '@kit.ImageKit'; 2187import { BusinessError } from '@kit.BasicServicesKit'; 2188import { image } from '@kit.ImageKit'; 2189 2190async function Demo() { 2191 let size: image.Size = { 2192 height: 8192, 2193 width: 8 2194 } 2195 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2196 receiver.readLatestImage().then((img: image.Image) => { 2197 console.info('readLatestImage succeeded.'); 2198 }).catch((error: BusinessError) => { 2199 console.error(`readLatestImage failed. code ${error.code}, message is ${error.message}`); 2200 }) 2201} 2202``` 2203 2204### readNextImage 2205 2206readNextImage(): Promise\<Image> 2207 2208从ImageReceiver读取下一张图片，并使用promise返回结果。 2209 2210**注意**：此接口需要在[on](#on)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image)对象使用完毕后需要调用[release](#release-2)方法释放，释放后才可以继续接收新的数据。 2211 2212**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 2213 2214**返回值：** 2215 2216| 类型 | 说明 | 2217| ------------------------- | -------------------- | 2218| Promise<[Image](#image)> | 异步返回下一张图片。 | 2219 2220**示例：** 2221 2222```ts 2223import { sendableImage } from '@kit.ImageKit'; 2224import { BusinessError } from '@kit.BasicServicesKit'; 2225import { image } from '@kit.ImageKit'; 2226 2227async function Demo() { 2228 let size: image.Size = { 2229 height: 8192, 2230 width: 8 2231 } 2232 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2233 receiver.readNextImage().then((img: image.Image) => { 2234 console.info('readNextImage succeeded.'); 2235 }).catch((error: BusinessError) => { 2236 console.error(`readNextImage failed. code ${error.code}, message is ${error.message}`); 2237 }) 2238} 2239``` 2240 2241### on 2242 2243on(type: 'imageArrival', callback: AsyncCallback\<void>): void 2244 2245接收图片时注册回调。 2246 2247**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 2248 2249**参数：** 2250 2251| 参数名 | 类型 | 必填 | 说明 | 2252| -------- | -------------------- | ---- | ------------------------------------------------------ | 2253| type | string | 是 | 注册事件的类型，固定为'imageArrival'，接收图片时触发。 | 2254| callback | AsyncCallback\<void> | 是 | 注册的事件回调。 | 2255 2256**示例：** 2257 2258```ts 2259import { sendableImage } from '@kit.ImageKit'; 2260import { image } from '@kit.ImageKit'; 2261 2262async function Demo() { 2263 let size: image.Size = { 2264 height: 8192, 2265 width: 8 2266 } 2267 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2268 receiver.on('imageArrival', () => { 2269 // 接收到图片，实现回调函数逻辑。 2270 }) 2271} 2272``` 2273 2274### release 2275 2276release(): Promise\<void> 2277 2278释放ImageReceiver实例并使用promise返回结果。release是线程不安全的。 2279 2280**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 2281 2282**返回值：** 2283 2284| 类型 | 说明 | 2285| -------------- | ------------------ | 2286| Promise\<void> | 异步返回操作结果。 | 2287 2288**示例：** 2289 2290```ts 2291import { sendableImage } from '@kit.ImageKit'; 2292import { BusinessError } from '@kit.BasicServicesKit'; 2293import { image } from '@kit.ImageKit'; 2294 2295async function Demo() { 2296 let size: image.Size = { 2297 height: 8192, 2298 width: 8 2299 } 2300 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2301 receiver.release().then(() => { 2302 console.info('release succeeded.'); 2303 }).catch((error: BusinessError) => { 2304 console.error(`release failed. code ${error.code}, message is ${error.message}`); 2305 }) 2306} 2307``` 2308
