1# @ohos.multimedia.image (图片处理) 2 3> **说明：** 4> 5> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6> 7> - 从API version 12开始，本模块接口支持在ArkTS卡片中使用。 8 9本模块提供图片的解码、编码、编辑、元数据处理和图片接收等能力。 10 11本模块包含以下基础类： 12 13- [ImageSource](#imagesource)类，提供获取[图片信息](#imageinfo)、将图片解码为PixelMap或Picture、读取和修改[图片属性](#propertykey7)的能力。[支持解码的图片格式](#属性-2)包括png、jpeg、bmp、gif、webp、dng、heic<sup>12+</sup>。 14 15- [ImagePacker](#imagepacker)类，提供将图片编码为压缩后的数据流或文件的能力。编码前需获取图片的ImageSource、PixelMap或Picture作为输入。[支持编码的图片格式](#属性-3)包括jpeg、webp、png、heic<sup>12+</sup>、gif<sup>18+</sup>。 16 17- [PixelMap](#pixelmap7)类，位图对象，包含像素数据以及[图片信息](#imageinfo)。可用于读取或写入像素数据，进行裁剪、缩放、平移、旋转、镜像等操作，并可直接传给[Image组件](../apis-arkui/arkui-ts/ts-basic-components-image.md)用于显示。还提供了获取和设置图片色域、HDR元数据的方法。 18 19- [Picture](#picture13)类，多图对象，由主图、辅助图和元数据组成。其中，主图包含了主要图像信息；辅助图用于存储与主图相关的附加信息；元数据用于存储与图片相关的其他信息。Picture提供获取主图、合成HDR图、获取辅助图、设置辅助图、获取元数据、设置元数据等方法。 20 21- [AuxiliaryPicture](#auxiliarypicture13)类，辅助图一般用于辅助主图进行特殊信息的展示，使图像包含更丰富的信息。目前支持的辅助图的类型可参考[AuxiliaryPictureType](#auxiliarypicturetype13)。 22 23- [Metadata](#metadata13)类，用于存储图像的元数据。目前支持的元数据类型可参考[MetadataType](#metadatatype13)。包含EXIF元数据和水印裁剪图元数据，它们都是以Key-Value的形式存储的，EXIF元数据的Key可参考[PropertyKey](#propertykey7)，水印裁剪图元数据的Key可参考[FragmentPropertyKey](#fragmentmappropertykey13)。 24 25- [ImageReceiver](#imagereceiver9)类，作为图片的消费者，用于从Surface中接收、读取图片。 26 27- [ImageCreator](#imagecreator9)类，作于图片的生产者，用于将图片写入到Surface中。 28 29- [Image](#image9)类，供ImageReceiver和ImageCreator使用，用于传输图片对象，它的实际内容由生产者决定。如相机预览流提供的Image对象存储了YUV数据，相机拍照提供的Image对象存储了JPEG文件。 30 31## 导入模块 32 33```ts 34import { image } from '@kit.ImageKit'; 35``` 36 37## image.createPicture<sup>13+</sup> 38 39createPicture(mainPixelmap : PixelMap): Picture 40 41通过主图的pixelmap创建一个Picture对象。 42 43**系统能力：** SystemCapability.Multimedia.Image.Core 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| ------------ | ------------------- | ---- | ---------------- | 49| mainPixelmap | [PixelMap](#pixelmap7) | 是 | 主图的pixelmap。 | 50 51**返回值：** 52 53| 类型 | 说明 | 54| ------------------ | ----------------- | 55| [Picture](#picture13) | 返回Picture对象。 | 56 57**错误码：** 58 59以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 60 61| 错误码ID | 错误信息 | 62| -------- | ------------------------------------------------------------ | 63| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. | 64 65**示例：** 66 67```ts 68import { image } from '@kit.ImageKit'; 69 70async function CreatePicture(context: Context) { 71 const resourceMgr = context.resourceManager; 72 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 73 let ops: image.SourceOptions = { 74 sourceDensity: 98, 75 } 76 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 77 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 78 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 79 if (pictureObj != null) { 80 console.info('Create picture succeeded'); 81 } else { 82 console.error('Create picture failed'); 83 } 84} 85``` 86 87## image.createPictureFromParcel<sup>13+</sup> 88 89createPictureFromParcel(sequence: rpc.MessageSequence): Picture 90 91从MessageSequence中获取Picture。 92 93**系统能力：** SystemCapability.Multimedia.Image.Core 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| -------- | ------------------------------------------------------------------- | ---- | ------------------------------------ | 99| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有Picture信息的MessageSequence。 | 100 101**返回值：** 102 103| 类型 | 说明 | 104| ------------------ | ----------------- | 105| [Picture](#picture13) | 返回Picture对象。 | 106 107**错误码：** 108 109以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 110 111| 错误码ID | 错误信息 | 112| -------- | ------------------------------------------------------------ | 113| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. | 114| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory. | 115 116**示例：** 117 118```ts 119import { rpc } from '@kit.IPCKit'; 120import { BusinessError } from '@kit.BasicServicesKit'; 121import { image } from '@kit.ImageKit'; 122 123class MySequence implements rpc.Parcelable { 124 picture: image.Picture | null = null; 125 constructor(conPicture: image.Picture) { 126 this.picture = conPicture; 127 } 128 marshalling(messageSequence: rpc.MessageSequence) { 129 if(this.picture != null) { 130 this.picture.marshalling(messageSequence); 131 console.info('Marshalling success !'); 132 return true; 133 } else { 134 console.error('Marshalling failed !'); 135 return false; 136 } 137 } 138 unmarshalling(messageSequence : rpc.MessageSequence) { 139 this.picture = image.createPictureFromParcel(messageSequence); 140 this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => { 141 console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 142 }).catch((error: BusinessError) => { 143 console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}'); 144 }); 145 return true; 146 } 147} 148 149async function Marshalling_UnMarshalling(context: Context) { 150 const resourceMgr = context.resourceManager; 151 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 152 let ops: image.SourceOptions = { 153 sourceDensity: 98, 154 } 155 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 156 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 157 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 158 if (pictureObj != null) { 159 let parcelable: MySequence = new MySequence(pictureObj); 160 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 161 // marshalling. 162 data.writeParcelable(parcelable); 163 let ret: MySequence = new MySequence(pictureObj); 164 // unmarshalling. 165 data.readParcelable(ret); 166 } else { 167 console.error('PictureObj is null'); 168 } 169} 170``` 171 172## image.createPixelMap<sup>8+</sup> 173 174createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise\<PixelMap> 175 176通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过Promise返回结果。 177 178**系统能力：** SystemCapability.Multimedia.Image.Core 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 184| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 185| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 186 187**返回值：** 188 189| 类型 | 说明 | 190| -------------------------------- | ----------------------------------------------------------------------- | 191| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。<br>当创建的pixelMap大小超过原图大小时，返回原图pixelMap大小。| 192 193**示例：** 194 195```ts 196import { BusinessError } from '@kit.BasicServicesKit'; 197 198async function CreatePixelMap() { 199 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 200 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 201 image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 202 console.info('Succeeded in creating pixelmap.'); 203 }).catch((error: BusinessError) => { 204 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 205 }) 206} 207``` 208 209## image.createPixelMap<sup>8+</sup> 210 211createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback\<PixelMap>): void 212 213通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过callback返回结果。 214 215**系统能力：** SystemCapability.Multimedia.Image.Core 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| -------- | ------------------------------------------------ | ---- | -------------------------- | 221| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 222| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度、尺寸、缩略值、像素格式和是否可编辑。 | 223| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 224 225**示例：** 226 227```ts 228import { BusinessError } from '@kit.BasicServicesKit'; 229 230async function CreatePixelMap() { 231 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 232 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 233 image.createPixelMap(color, opts, (error: BusinessError, pixelMap: image.PixelMap) => { 234 if(error) { 235 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 236 return; 237 } else { 238 console.info('Succeeded in creating pixelmap.'); 239 } 240 }) 241} 242``` 243 244## image.createPixelMapUsingAllocator<sup>20+</sup> 245 246createPixelMapUsingAllocator(colors: ArrayBuffer, options: InitializationOptions, allocatorType?: AllocatorType): Promise\<PixelMap> 247 248通过属性创建以及指定内存类型创建PixelMap，默认采用BGRA_8888格式处理数据。使用Promise异步回调。 249 250**系统能力：** SystemCapability.Multimedia.Image.Core 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| -------- | ------------------------------------------------ | ---- | -------------------------- | 256| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 257| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度、尺寸、缩略值、像素格式和是否可编辑。 | 258| allocatorType | [AllocatorType](#allocatortype15) | 否 | 指定创建pixelmap的内存类型，默认内存类型是AllocatorType.AUTO。<br> 1. image.AllocatorType.AUTO：不支持该内存类型的格式有UNKNOWN、YCBCR_P010、YCRCB_P010和ASTC_4x4。RGBA_1010102默认申请DMA内存。其他格式（RGB_565、RGBA_8888、BGRA_8888和RGBAF_16）尺寸大于512*512默认申请DMA内存，否则申请共享内存。<br>2. image.AllocatorType.DMA：RGBA_1010102、RGB_565、RGBA_8888、BGRA_8888和RGBAF_16支持DMA内存类型，其余格式不支持。<br>3. image.AllocatorType.SHARED：UNKNOWN、RGBA_1010102、YCBCR_P010、YCRCB_P010和ASTC_4x4不支持共享内存，其余格式支持。| 259 260**返回值：** 261 262| 类型 | 说明 | 263| -------------------------------- | ----------------------------------------------------------------------- | 264| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。| 265 266**错误码：** 267 268以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 269 270| 错误码ID | 错误信息 | 271| ------- | --------------------------------------------| 272| 7600201 | Unsupported operation. e.g.,1. The picture does not has a gainmap. 2. MainPixelMap's allocator type is not DMA. | 273| 7600301 | Memory alloc failed. | 274| 7600302 | Memory copy failed. | 275 276**示例：** 277 278```ts 279import { BusinessError } from '@kit.BasicServicesKit'; 280 281async function CreatePixelMapUseAllocator() { 282 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 283 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 284 image.createPixelMapUsingAllocator(color, opts, image.AllocatorType.AUTO).then((pixelMap: image.PixelMap) => { 285 console.info('Succeeded in creating pixelmap.'); 286 }).catch((error: BusinessError) => { 287 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 288 }) 289} 290``` 291 292## image.createPixelMapFromParcel<sup>11+</sup> 293 294createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap 295 296从MessageSequence中获取PixelMap。 297 298**系统能力：** SystemCapability.Multimedia.Image.Core 299 300**参数：** 301 302| 参数名 | 类型 | 必填 | 说明 | 303| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 304| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 305 306**返回值：** 307 308| 类型 | 说明 | 309| -------------------------------- | --------------------- | 310| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 311 312**错误码：** 313 314以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 315 316| 错误码ID | 错误信息 | 317| ------- | --------------------------------------------| 318| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory.| 319| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory.| 320| 62980115 | Invalid input parameter.| 321| 62980105 | Failed to get the data.| 322| 62980177 | Abnormal API environment.| 323| 62980178 | Failed to create the PixelMap.| 324| 62980179 | Abnormal buffer size.| 325| 62980180 | FD mapping failed. Possible cause: 1. Size and address does not match. 2. Memory map in memalloc failed.| 326| 62980246 | Failed to read the PixelMap.| 327 328**示例：** 329 330```ts 331import { image } from '@kit.ImageKit'; 332import { rpc } from '@kit.IPCKit'; 333import { BusinessError } from '@kit.BasicServicesKit'; 334 335class MySequence implements rpc.Parcelable { 336 pixel_map: image.PixelMap; 337 constructor(conPixelmap: image.PixelMap) { 338 this.pixel_map = conPixelmap; 339 } 340 marshalling(messageSequence: rpc.MessageSequence) { 341 this.pixel_map.marshalling(messageSequence); 342 return true; 343 } 344 unmarshalling(messageSequence: rpc.MessageSequence) { 345 try { 346 this.pixel_map = image.createPixelMapFromParcel(messageSequence); 347 } catch(e) { 348 let error = e as BusinessError; 349 console.error(`createPixelMapFromParcel error. code is ${error.code}, message is ${error.message}`); 350 return false; 351 } 352 return true; 353 } 354} 355async function CreatePixelMapFromParcel() { 356 const color: ArrayBuffer = new ArrayBuffer(96); 357 let bufferArr: Uint8Array = new Uint8Array(color); 358 for (let i = 0; i < bufferArr.length; i++) { 359 bufferArr[i] = 0x80; 360 } 361 let opts: image.InitializationOptions = { 362 editable: true, 363 pixelFormat: image.PixelMapFormat.BGRA_8888, 364 size: { height: 4, width: 6 }, 365 alphaType: image.AlphaType.UNPREMUL 366 } 367 let pixelMap: image.PixelMap | undefined = undefined; 368 image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 369 pixelMap = srcPixelMap; 370 }) 371 if (pixelMap != undefined) { 372 // 序列化。 373 let parcelable: MySequence = new MySequence(pixelMap); 374 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 375 data.writeParcelable(parcelable); 376 377 // 反序列化 rpc获取到data。 378 let ret: MySequence = new MySequence(pixelMap); 379 data.readParcelable(ret); 380 381 // 获取到pixelmap。 382 let unmarshPixelmap = ret.pixel_map; 383 } 384} 385``` 386 387## image.createPixelMapFromSurface<sup>11+</sup> 388 389createPixelMapFromSurface(surfaceId: string, region: Region): Promise\<PixelMap> 390 391根据Surface id和区域信息，创建一个PixelMap对象。该区域的大小由[Region](#region8).size指定。使用Promise形式返回。 392 393> **说明：** 394> 当开发设备为折叠屏，折叠状态切换时，可能因Surface自带旋转角度导致接口创建失败，需将宽高适配旋转角度。推荐使用[image.createPixelMapFromSurface](#imagecreatepixelmapfromsurface15) 395 396**系统能力：** SystemCapability.Multimedia.Image.Core 397 398**参数：** 399 400| 参数名 | 类型 | 必填 | 说明 | 401| ---------------------- | ------------- | ---- | ---------------------------------------- | 402| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 403| region | [Region](#region8) | 是 | 区域信息。[Region](#region8).size的宽高需和设置的预览流大小保持一致。 | 404 405**返回值：** 406| 类型 | 说明 | 407| -------------------------------- | --------------------- | 408| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 409 410**错误码：** 411 412以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 413 414| 错误码ID | 错误信息 | 415| ------- | --------------------------------------------| 416| 62980115 | If the image parameter invalid.| 417| 62980105 | Failed to get the data.| 418| 62980178 | Failed to create the PixelMap.| 419 420**示例：** 421 422```ts 423import { BusinessError } from '@kit.BasicServicesKit'; 424 425async function CreatePixelMapFromSurface(surfaceId: string) { 426 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 427 image.createPixelMapFromSurface(surfaceId, region).then(() => { 428 console.info('Succeeded in creating pixelmap from Surface'); 429 }).catch((error: BusinessError) => { 430 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 431 }); 432} 433``` 434 435## image.createPixelMapFromSurfaceSync<sup>12+</sup> 436 437createPixelMapFromSurfaceSync(surfaceId: string, region: Region): PixelMap 438 439以同步方式，根据Surface id和区域信息，创建一个PixelMap对象。该区域的大小由[Region](#region8).size指定。 440 441> **说明：** 442> 当开发设备为折叠屏，折叠状态切换时，可能因Surface自带旋转角度导致接口创建失败，需将宽高适配旋转角度。推荐使用[image.createPixelMapFromSurfaceSync](#imagecreatepixelmapfromsurfacesync15)。 443 444**系统能力：** SystemCapability.Multimedia.Image.Core 445 446**参数：** 447 448| 参数名 | 类型 | 必填 | 说明 | 449| ---------------------- | ------------- | ---- | ---------------------------------------- | 450| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 451| region | [Region](#region8) | 是 | 区域信息。[Region](#region8).size的宽高需和设置的预览流大小保持一致。 | 452 453**返回值：** 454| 类型 | 说明 | 455| -------------------------------- | --------------------- | 456| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 457 458**错误码：** 459 460以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 461 462| 错误码ID | 错误信息 | 463| ------- | --------------------------------------------| 464| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 465| 62980105 | Failed to get the data.| 466| 62980178 | Failed to create the PixelMap.| 467 468**示例：** 469 470```ts 471import { BusinessError } from '@kit.BasicServicesKit'; 472 473async function Demo(surfaceId: string) { 474 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 475 let pixelMap : image.PixelMap = image.createPixelMapFromSurfaceSync(surfaceId, region); 476 return pixelMap; 477} 478``` 479 480## image.createPixelMapFromSurface<sup>15+</sup> 481 482createPixelMapFromSurface(surfaceId: string): Promise\<PixelMap> 483 484从Surface id创建一个PixelMap对象。使用Promise异步回调，返回PixelMap。 485 486**系统能力：** SystemCapability.Multimedia.Image.Core 487 488**参数：** 489 490| 参数名 | 类型 | 必填 | 说明 | 491| ---------------------- | ------------- | ---- | ---------------------------------------- | 492| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 493 494**返回值：** 495| 类型 | 说明 | 496| -------------------------------- | --------------------- | 497| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 498 499**错误码：** 500 501以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 502 503| 错误码ID | 错误信息 | 504| ------- | --------------------------------------------| 505| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 506| 62980105 | Failed to get the data| 507| 62980178 | Failed to create the PixelMap| 508 509**示例：** 510 511```ts 512import { BusinessError } from '@kit.BasicServicesKit'; 513 514async function Demo(surfaceId: string) { 515 image.createPixelMapFromSurface(surfaceId).then(() => { 516 console.info('Succeeded in creating pixelmap from Surface'); 517 }).catch((error: BusinessError) => { 518 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 519 }); 520} 521``` 522 523## image.createPixelMapFromSurfaceSync<sup>15+</sup> 524 525createPixelMapFromSurfaceSync(surfaceId: string): PixelMap 526 527从Surface id创建一个pixelMap对象，同步返回PixelMap结果。 528 529**系统能力：** SystemCapability.Multimedia.Image.Core 530 531**参数：** 532 533| 参数名 | 类型 | 必填 | 说明 | 534| ---------------------- | ------------- | ---- | ---------------------------------------- | 535| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 536 537**返回值：** 538| 类型 | 说明 | 539| -------------------------------- | --------------------- | 540| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 541 542**错误码：** 543 544以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 545 546| 错误码ID | 错误信息 | 547| ------- | --------------------------------------------| 548| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 549| 62980105 | Failed to get the data| 550| 62980178 | Failed to create the PixelMap| 551 552**示例：** 553 554```ts 555import { BusinessError } from '@kit.BasicServicesKit'; 556 557async function Demo(surfaceId: string) { 558 let pixelMap : image.PixelMap = image.createPixelMapFromSurfaceSync(surfaceId); 559 return pixelMap; 560} 561``` 562## image.createPixelMapSync<sup>12+</sup> 563 564createPixelMapSync(colors: ArrayBuffer, options: InitializationOptions): PixelMap 565 566通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，同步返回结果。 567 568**系统能力：** SystemCapability.Multimedia.Image.Core 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 574| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 575| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 576 577**返回值：** 578| 类型 | 说明 | 579| -------------------------------- | --------------------- | 580| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 581 582**错误码：** 583 584以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 585 586| 错误码ID | 错误信息 | 587| ------- | --------------------------------------------| 588| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 589 590**示例：** 591 592```ts 593import { BusinessError } from '@kit.BasicServicesKit'; 594 595async function CreatePixelMapSync() { 596 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 597 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 598 let pixelMap : image.PixelMap = image.createPixelMapSync(color, opts); 599 return pixelMap; 600} 601``` 602 603## image.createPixelMapSync<sup>12+</sup> 604 605createPixelMapSync(options: InitializationOptions): PixelMap 606 607通过属性创建PixelMap，同步返回PixelMap结果。 608 609**系统能力：** SystemCapability.Multimedia.Image.Core 610 611**参数：** 612 613| 参数名 | 类型 | 必填 | 说明 | 614| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 615| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 616 617**返回值：** 618| 类型 | 说明 | 619| -------------------------------- | --------------------- | 620| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 621 622**错误码：** 623 624以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 625 626| 错误码ID | 错误信息 | 627| ------- | --------------------------------------------| 628| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 629 630**示例：** 631 632```ts 633import { BusinessError } from '@kit.BasicServicesKit'; 634 635async function CreatePixelMapSync() { 636 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 637 let pixelMap : image.PixelMap = image.createPixelMapSync(opts); 638 return pixelMap; 639} 640``` 641 642## image.createPixelMapUsingAllocatorSync<sup>20+</sup> 643 644createPixelMapUsingAllocatorSync(colors: ArrayBuffer, options: InitializationOptions, allocatorType?: AllocatorType): PixelMap 645 646通过指定属性以及内存类型创建PixelMap，默认采用BGRA_8888格式处理数据，同步返回结果。 647 648**系统能力：** SystemCapability.Multimedia.Image.Core 649 650**参数：** 651 652| 参数名 | 类型 | 必填 | 说明 | 653| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 654| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 655| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度、尺寸、缩略值、像素格式和是否可编辑。 | 656| allocatorType | [AllocatorType](#allocatortype15) | 否 | 指定创建pixelmap的内存类型，默认内存类型是AllocatorType.AUTO。<br> 1. image.AllocatorType.AUTO：不支持该内存类型的格式有UNKNOWN、YCBCR_P010、YCRCB_P010和ASTC_4x4。RGBA_1010102默认申请DMA内存。其他格式（RGB_565、RGBA_8888、BGRA_8888和RGBAF_16）尺寸大于512*512默认申请DMA内存，否则申请共享内存。<br>2. image.AllocatorType.DMA：RGBA_1010102、RGB_565、RGBA_8888、BGRA_8888和RGBAF_16支持DMA内存类型，其余格式不支持。<br>3. image.AllocatorType.SHARED：UNKNOWN、RGBA_1010102、YCBCR_P010、YCRCB_P010和ASTC_4x4不支持共享内存，其余格式支持。| 657 658**返回值：** 659| 类型 | 说明 | 660| -------------------------------- | --------------------- | 661| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 662 663**错误码：** 664 665以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 666 667| 错误码ID | 错误信息 | 668| ------- | --------------------------------------------| 669| 7600201 | Unsupported operation. e.g.,1. The picture does not has a gainmap. 2. MainPixelMap's allocator type is not DMA. | 670| 7600301 | Memory alloc failed. | 671| 7600302 | Memory copy failed. | 672 673**示例：** 674 675```ts 676import { BusinessError } from '@kit.BasicServicesKit'; 677 678async function CreatePixelMapSync() { 679 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 680 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 681 let pixelMap : image.PixelMap = image.createPixelMapUsingAllocatorSync(color, opts, image.AllocatorType.AUTO); 682 return pixelMap; 683} 684``` 685 686## image.createPixelMapUsingAllocatorSync<sup>20+</sup> 687 688createPixelMapUsingAllocatorSync(options: InitializationOptions, allocatorType?: AllocatorType): PixelMap 689 690通过属性创建PixelMap，同步返回PixelMap结果。 691 692**系统能力：** SystemCapability.Multimedia.Image.Core 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 698| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度、尺寸、缩略值、像素格式和是否可编辑。 | 699| allocatorType | [AllocatorType](#allocatortype15) | 否 | 指定创建pixelmap的内存类型，默认内存类型是AllocatorType.AUTO。<br> 1. image.AllocatorType.AUTO：不支持该内存类型的格式有UNKNOWN和ASTC_4x4。RGBA_1010102、YCBCR_P010、YCRCB_P010格式默认申请DMA内存。其他格式（RGB_565, RGBA_8888, BGRA_8888, RGBAF_16）尺寸大于512*512默认申请DMA内存，否则申请共享内存。<br>2. image.AllocatorType.DMA：RGB_565、RGBA_8888、BGRA_8888、RGBAF_16、RGBA_1010102、YCBCR_P010和YCRCB_P010支持DMA内存类型，其余格式不支持。<br>3. image.AllocatorType.SHARED：UNKNOWN、RGBA_1010102、YCBCR_P010、YCRCB_P010和ASTC_4x4不支持共享内存，其余格式支持。| 700 701**返回值：** 702| 类型 | 说明 | 703| -------------------------------- | --------------------- | 704| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 705 706**错误码：** 707 708以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 709 710| 错误码ID | 错误信息 | 711| ------- | --------------------------------------------| 712| 7600201 | Unsupported operation. e.g.,1. The picture does not has a gainmap. 2. MainPixelMap's allocator type is not DMA. | 713| 7600301 | Memory alloc failed. | 714 715**示例：** 716 717```ts 718import { BusinessError } from '@kit.BasicServicesKit'; 719 720async function CreatePixelMapSync() { 721 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 722 let pixelMap : image.PixelMap = image.createPixelMapUsingAllocatorSync(opts, image.AllocatorType.AUTO); 723 return pixelMap; 724} 725``` 726 727## image.createPremultipliedPixelMap<sup>12+</sup> 728 729createPremultipliedPixelMap(src: PixelMap, dst: PixelMap, callback: AsyncCallback\<void>): void 730 731将PixelMap的透明通道非预乘模式转变为预乘模式，转换后的数据存入目标PixelMap，通过回调函数返回结果。 732 733**系统能力：** SystemCapability.Multimedia.Image.Core 734 735**参数：** 736 737| 参数名 | 类型 | 必填 | 说明 | 738| -------- | ------------------------------------------------ | ---- | -------------------------- | 739| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 740| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 741|callback | AsyncCallback\<void> | 是 | 回调函数，当创建PixelMap成功，err为undefined，否则为错误对象。 | 742 743**错误码：** 744 745以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 746 747| 错误码ID | 错误信息 | 748| ------- | --------------------------------------------| 749| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 750| 62980103 | The image data is not supported | 751| 62980246 | Failed to read the pixelMap | 752| 62980248 | Pixelmap not allow modify | 753 754**示例：** 755 756```ts 757import { BusinessError } from '@kit.BasicServicesKit'; 758 759async function CreatePremultipliedPixelMap() { 760 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 761 let bufferArr = new Uint8Array(color); 762 for (let i = 0; i < bufferArr.length; i += 4) { 763 bufferArr[i] = 255; 764 bufferArr[i+1] = 255; 765 bufferArr[i+2] = 122; 766 bufferArr[i+3] = 122; 767 } 768 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 769 let srcPixelmap = image.createPixelMapSync(color, optsForUnpre); 770 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 771 let dstPixelMap = image.createPixelMapSync(optsForPre); 772 image.createPremultipliedPixelMap(srcPixelmap, dstPixelMap, (error: BusinessError) => { 773 if(error) { 774 console.error(`Failed to convert pixelmap, error code is ${error}`); 775 return; 776 } else { 777 console.info('Succeeded in converting pixelmap.'); 778 } 779 }) 780} 781``` 782 783## image.createPremultipliedPixelMap<sup>12+</sup> 784 785createPremultipliedPixelMap(src: PixelMap, dst: PixelMap): Promise\<void> 786 787将PixelMap数据按照透明度非预乘格式转为预乘格式，转换后的数据存入另一个PixelMap，通过Promise返回结果。 788 789**系统能力：** SystemCapability.Multimedia.Image.Core 790 791**参数：** 792 793| 参数名 | 类型 | 必填 | 说明 | 794| -------- | ------------------------------------------------ | ---- | -------------------------- | 795| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 796| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 797 798**返回值：** 799 800| 类型 | 说明 | 801| -------------------------------- | ----------------------------------------------------------------------- | 802| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 803 804**错误码：** 805 806以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 807 808| 错误码ID | 错误信息 | 809| ------- | --------------------------------------------| 810| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 811| 62980103 | The image data is not supported | 812| 62980246 | Failed to read the pixelMap | 813| 62980248 | Pixelmap not allow modify | 814 815**示例：** 816 817```ts 818import { BusinessError } from '@kit.BasicServicesKit'; 819 820async function CreatePremultipliedPixelMap() { 821 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 822 let bufferArr = new Uint8Array(color); 823 for (let i = 0; i < bufferArr.length; i += 4) { 824 bufferArr[i] = 255; 825 bufferArr[i+1] = 255; 826 bufferArr[i+2] = 122; 827 bufferArr[i+3] = 122; 828 } 829 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 830 let srcPixelmap = image.createPixelMapSync(color, optsForUnpre); 831 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 832 let dstPixelMap = image.createPixelMapSync(optsForPre); 833 image.createPremultipliedPixelMap(srcPixelmap, dstPixelMap).then(() => { 834 console.info('Succeeded in converting pixelmap.'); 835 }).catch((error: BusinessError) => { 836 console.error(`Failed to convert pixelmap, error code is ${error}`); 837 }) 838} 839``` 840 841## image.createUnpremultipliedPixelMap<sup>12+</sup> 842 843createUnpremultipliedPixelMap(src: PixelMap, dst: PixelMap, callback: AsyncCallback\<void>): void 844 845将PixelMap的透明通道预乘模式转变为非预乘模式，转换后的数据存入目标PixelMap，通过回调函数返回结果。 846 847**系统能力：** SystemCapability.Multimedia.Image.Core 848 849**参数：** 850 851| 参数名 | 类型 | 必填 | 说明 | 852| -------- | ------------------------------------------------ | ---- | -------------------------- | 853| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 854| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。| 855|callback | AsyncCallback\<void> | 是 | 回调函数，当创建PixelMap成功，err为undefined，否则为错误对象。| 856 857**错误码：** 858 859以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 860 861| 错误码ID | 错误信息 | 862| ------- | --------------------------------------------| 863| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 864| 62980103 | The image data is not supported | 865| 62980246 | Failed to read the pixelMap | 866| 62980248 | Pixelmap not allow modify | 867 868**示例：** 869 870```ts 871import { BusinessError } from '@kit.BasicServicesKit'; 872 873async function CreateUnpremultipliedPixelMap() { 874 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 875 let bufferArr = new Uint8Array(color); 876 for (let i = 0; i < bufferArr.length; i += 4) { 877 bufferArr[i] = 255; 878 bufferArr[i+1] = 255; 879 bufferArr[i+2] = 122; 880 bufferArr[i+3] = 122; 881 } 882 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 883 let srcPixelmap = image.createPixelMapSync(color, optsForPre); 884 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 885 let dstPixelMap = image.createPixelMapSync(optsForUnpre); 886 image.createUnpremultipliedPixelMap(srcPixelmap, dstPixelMap, (error: BusinessError) => { 887 if(error) { 888 console.error(`Failed to convert pixelmap, error code is ${error}`); 889 return; 890 } else { 891 console.info('Succeeded in converting pixelmap.'); 892 } 893 }) 894} 895``` 896 897## image.createUnpremultipliedPixelMap<sup>12+</sup> 898 899createUnpremultipliedPixelMap(src: PixelMap, dst: PixelMap): Promise\<void> 900 901将PixelMap的透明通道预乘模式转变为非预乘模式，转换后的数据存入目标PixelMap，通过Promise返回结果。 902 903**系统能力：** SystemCapability.Multimedia.Image.Core 904 905**参数：** 906 907| 参数名 | 类型 | 必填 | 说明 | 908| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 909| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 910| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 911 912**返回值：** 913 914| 类型 | 说明 | 915| -------------------------------- | ----------------------------------------------------------------------- | 916| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 917 918**错误码：** 919 920以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 921 922| 错误码ID | 错误信息 | 923| ------- | --------------------------------------------| 924| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 925| 62980103 | The image data is not supported. | 926| 62980246 | Failed to read the pixelMap. | 927| 62980248 | Pixelmap not allow modify. | 928 929**示例：** 930 931```ts 932import { BusinessError } from '@kit.BasicServicesKit'; 933 934async function CreateUnpremultipliedPixelMap() { 935 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 936 let bufferArr = new Uint8Array(color); 937 for (let i = 0; i < bufferArr.length; i += 4) { 938 bufferArr[i] = 255; 939 bufferArr[i+1] = 255; 940 bufferArr[i+2] = 122; 941 bufferArr[i+3] = 122; 942 } 943 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 944 let srcPixelmap = image.createPixelMapSync(color, optsForPre); 945 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 946 let dstPixelMap = image.createPixelMapSync(optsForUnpre); 947 image.createUnpremultipliedPixelMap(srcPixelmap, dstPixelMap).then(() => { 948 console.info('Succeeded in converting pixelmap.'); 949 }).catch((error: BusinessError) => { 950 console.error(`Failed to convert pixelmap, error code is ${error}`); 951 }) 952} 953``` 954 955 956## Picture<sup>13+</sup> 957 958一些包含特殊信息的图片可以解码为多图对象，多图对象一般包含主图、辅助图和元数据。其中主图包含图像的大部分信息，主要用于显示图像内容；辅助图用于存储与主图相关但不同的数据，展示图像更丰富的信息；元数据一般用来存储关于图像文件的信息。多图对象类用于读取或写入多图对象。在调用Picture的方法前，需要先通过[createPicture](#imagecreatepicture13)创建一个Picture实例。 959 960### 属性 961 962**系统能力：** SystemCapability.Multimedia.Image.Core 963 964### getMainPixelmap<sup>13+</sup> 965 966getMainPixelmap(): PixelMap 967 968获取主图的pixelmap。 969 970**系统能力：** SystemCapability.Multimedia.Image.Core 971 972**返回值：** 973 974| 类型 | 说明 | 975| ------------------- | ---------------------- | 976| [PixelMap](#pixelmap7) | 同步返回PixelMap对象。 | 977 978**示例：** 979 980```ts 981import { BusinessError } from '@kit.BasicServicesKit'; 982import { image } from '@kit.ImageKit'; 983 984async function GetMainPixelmap() { 985 let funcName = "getMainPixelmap"; 986 if (pictureObj != null) { 987 let mainPixelmap: image.PixelMap = pictureObj.getMainPixelmap(); 988 if (mainPixelmap != null) { 989 mainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 990 if (imageInfo != null) { 991 console.info('GetMainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 992 } 993 }).catch((error: BusinessError) => { 994 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 995 }); 996 } 997 } else { 998 console.error('PictureObj is null'); 999 } 1000} 1001``` 1002 1003### getHdrComposedPixelmap<sup>13+</sup> 1004 1005getHdrComposedPixelmap(): Promise\<PixelMap> 1006 1007合成hdr图并获取hdr图的pixelmap，使用Promise形式返回结果。 1008 1009**系统能力：** SystemCapability.Multimedia.Image.Core 1010 1011**返回值：** 1012 1013| 类型 | 说明 | 1014| ----------------------------- | --------------------------- | 1015| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 1016 1017**错误码：** 1018 1019以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1020 1021| 错误码ID | 错误信息 | 1022| -------- | ---------------------- | 1023| 7600901 | Inner unknown error. Please check the logs for detailed information. | 1024| 7600201 | Unsupported operation. e.g.,1. The picture does not has a gainmap. 2. MainPixelMap's allocator type is not DMA. | 1025 1026**示例：** 1027 1028```ts 1029import { BusinessError } from '@kit.BasicServicesKit'; 1030import { image } from '@kit.ImageKit'; 1031 1032async function GetHdrComposedPixelmap() { 1033 let funcName = "getHdrComposedPixelmap"; 1034 if (pictureObj != null) { //图片包含Hdr图。 1035 let hdrComposedPixelmap: image.PixelMap = await pictureObj.getHdrComposedPixelmap(); 1036 if (hdrComposedPixelmap != null) { 1037 hdrComposedPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 1038 if (imageInfo != null) { 1039 console.info('GetHdrComposedPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 1040 } 1041 }).catch((error: BusinessError) => { 1042 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 1043 }); 1044 } 1045 } else { 1046 console.error('PictureObj is null'); 1047 } 1048} 1049``` 1050 1051### getGainmapPixelmap<sup>13+</sup> 1052 1053getGainmapPixelmap(): PixelMap | null 1054 1055获取增益图的pixelmap。 1056 1057**系统能力：** SystemCapability.Multimedia.Image.Core 1058 1059**返回值：** 1060 1061| 类型 | 说明 | 1062| ------------------------- | -------------------------------------- | 1063| [PixelMap](#pixelmap7) \| null | 返回Pixelmap对象，如果没有则返回null。 | 1064 1065**示例：** 1066 1067```ts 1068import { BusinessError } from '@kit.BasicServicesKit'; 1069import { image } from '@kit.ImageKit'; 1070 1071async function GetGainmapPixelmap() { 1072 let funcName = "getGainmapPixelmap"; 1073 if (pictureObj != null) { //图片包含增益图。 1074 let gainPixelmap: image.PixelMap | null = pictureObj.getGainmapPixelmap(); 1075 if (gainPixelmap != null) { 1076 gainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 1077 if (imageInfo != null) { 1078 console.info('GetGainmapPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 1079 } else { 1080 console.error('GainPixelmap is null'); 1081 } 1082 }).catch((error: BusinessError) => { 1083 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 1084 }); 1085 } else { 1086 console.info('GainPixelmap is null'); 1087 } 1088 } else { 1089 console.error('PictureObj is null'); 1090 } 1091} 1092``` 1093 1094### setAuxiliaryPicture<sup>13+</sup> 1095 1096setAuxiliaryPicture(type: AuxiliaryPictureType, auxiliaryPicture: AuxiliaryPicture): void 1097 1098设置辅助图。 1099 1100**系统能力：** SystemCapability.Multimedia.Image.Core 1101 1102**参数：** 1103 1104| 参数名 | 类型 | 必填 | 说明 | 1105| ---------------- | -------------------- | ---- | ------------ | 1106| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 1107| auxiliaryPicture | [AuxiliaryPicture](#auxiliarypicture13) | 是 | 辅助图对象。 | 1108 1109**错误码：** 1110 1111以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1112 1113| 错误码ID | 错误信息 | 1114| -------- | ------------------------------------------------------------ | 1115| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1116 1117**示例：** 1118 1119```ts 1120import { image } from '@kit.ImageKit'; 1121 1122async function SetAuxiliaryPicture(context: Context) { 1123 const resourceMgr = context.resourceManager; 1124 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg");//需要支持hdr的图片。 1125 let ops: image.SourceOptions = { 1126 sourceDensity: 98, 1127 } 1128 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 1129 let pixelMap: image.PixelMap = await imageSource.createPixelMap(); 1130 let auxPicture: image.Picture = image.createPicture(pixelMap); 1131 if (auxPicture != null) { 1132 console.info('Create picture succeeded'); 1133 } else { 1134 console.error('Create picture failed'); 1135 } 1136 1137 if (pictureObj != null) { 1138 let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 1139 let auxPictureObj: image.AuxiliaryPicture | null = await auxPicture.getAuxiliaryPicture(type); 1140 if (auxPictureObj != null) { 1141 pictureObj.setAuxiliaryPicture(type, auxPictureObj); 1142 } 1143 } 1144} 1145``` 1146 1147### getAuxiliaryPicture<sup>13+</sup> 1148 1149getAuxiliaryPicture(type: AuxiliaryPictureType): AuxiliaryPicture | null 1150 1151根据类型获取辅助图。 1152 1153**系统能力：** SystemCapability.Multimedia.Image.Core 1154 1155**参数：** 1156 1157| 参数名 | 类型 | 必填 | 说明 | 1158| ------ | -------------------- | ---- | ------------ | 1159| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 1160 1161**返回值：** 1162 1163| 类型 | 说明 | 1164| ---------------------- | ---------------------------------------------- | 1165| [AuxiliaryPicture](#auxiliarypicture13) \| null | 返回AuxiliaryPicture对象，如果没有则返回null。 | 1166 1167**错误码：** 1168 1169以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1170 1171| 错误码ID | 错误信息 | 1172| -------- | ------------------------------------------------------------ | 1173| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1174 1175**示例：** 1176 1177```ts 1178import { image } from '@kit.ImageKit'; 1179 1180async function GetAuxiliaryPicture() { 1181 if (pictureObj != null) { 1182 let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 1183 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(type); 1184 } 1185} 1186``` 1187 1188### setMetadata<sup>13+</sup> 1189 1190setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void> 1191 1192设置主图的元数据。 1193 1194**系统能力：** SystemCapability.Multimedia.Image.Core 1195 1196**参数：** 1197 1198| 参数名 | 类型 | 必填 | 说明 | 1199| ------------ | ------------ | ---- | ------------ | 1200| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型。 | 1201| metadata | [Metadata](#metadata13) | 是 | 元数据对象。 | 1202 1203**返回值：** 1204 1205| 类型 | 说明 | 1206| -------------- | -------------------------------------- | 1207| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1208 1209**错误码：** 1210 1211以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1212 1213| 错误码ID | 错误信息 | 1214| -------- | ------------------------------------------------------------ | 1215| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1216| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 1217 1218**示例：** 1219 1220```ts 1221import { BusinessError } from '@kit.BasicServicesKit'; 1222import { image } from '@kit.ImageKit'; 1223 1224async function SetPictureObjMetadata(exifContext: Context) { 1225 const exifResourceMgr = exifContext.resourceManager; 1226 const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");//含有exif metadata的图片。 1227 let exifOps: image.SourceOptions = { 1228 sourceDensity: 98, 1229 } 1230 let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps); 1231 let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap(); 1232 let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap); 1233 if (exifPictureObj != null) { 1234 console.info('Create picture succeeded'); 1235 } else { 1236 console.error('Create picture failed'); 1237 } 1238 1239 if (pictureObj != null) { 1240 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 1241 let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType); 1242 pictureObj.setMetadata(metadataType, exifMetaData).then(() => { 1243 console.info('Set metadata success'); 1244 }).catch((error: BusinessError) => { 1245 console.error('Failed to set metadata. error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 1246 }); 1247 } else { 1248 console.error('PictureObj is null'); 1249 } 1250} 1251``` 1252 1253### getMetadata<sup>13+</sup> 1254 1255getMetadata(metadataType: MetadataType): Promise\<Metadata> 1256 1257获取主图的元数据。 1258 1259**系统能力：** SystemCapability.Multimedia.Image.Core 1260 1261**参数：** 1262 1263| 参数名 | 类型 | 必填 | 说明 | 1264| ------------ | ------------ | ---- | ------------ | 1265| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型。 | 1266 1267**返回值：** 1268 1269| 类型 | 说明 | 1270| ------------------ | ------------------------- | 1271| Promise\<[Metadata](#metadata13)> | Promise对象。返回元数据。 | 1272 1273**错误码：** 1274 1275以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1276 1277| 错误码ID | 错误信息 | 1278| -------- | ------------------------------------------------------------ | 1279| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1280| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 1281 1282**示例：** 1283 1284```ts 1285import { image } from '@kit.ImageKit'; 1286 1287async function GetPictureObjMetadataProperties() { 1288 if (pictureObj != null) { 1289 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 1290 let pictureObjMetaData: image.Metadata = await pictureObj.getMetadata(metadataType); 1291 if (pictureObjMetaData != null) { 1292 console.info('get picture metadata success'); 1293 } else { 1294 console.error('get picture metadata is failed'); 1295 } 1296 } else { 1297 console.error(" pictureObj is null"); 1298 } 1299} 1300``` 1301 1302### marshalling<sup>13+</sup> 1303 1304marshalling(sequence: rpc.MessageSequence): void 1305 1306将picture序列化后写入MessageSequence。 1307 1308**系统能力：** SystemCapability.Multimedia.Image.Core 1309 1310**参数：** 1311 1312| 参数名 | 类型 | 必填 | 说明 | 1313| -------- | ------------------------------------------------------------------- | ---- | ------------------------- | 1314| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 1315 1316**错误码：** 1317 1318以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1319 1320| 错误码ID | 错误信息 | 1321| -------- | ------------------------------------------------------------ | 1322| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1323| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory. | 1324 1325**示例：** 1326 1327```ts 1328import { BusinessError } from '@kit.BasicServicesKit'; 1329import { image } from '@kit.ImageKit'; 1330import { rpc } from '@kit.IPCKit'; 1331 1332class MySequence implements rpc.Parcelable { 1333 picture: image.Picture | null = null; 1334 constructor(conPicture: image.Picture) { 1335 this.picture = conPicture; 1336 } 1337 marshalling(messageSequence: rpc.MessageSequence) { 1338 if(this.picture != null) { 1339 this.picture.marshalling(messageSequence); 1340 console.info('Marshalling success !'); 1341 return true; 1342 } else { 1343 console.error('Marshalling failed !'); 1344 return false; 1345 } 1346 } 1347 unmarshalling(messageSequence : rpc.MessageSequence) { 1348 this.picture = image.createPictureFromParcel(messageSequence); 1349 this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => { 1350 console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 1351 }).catch((error: BusinessError) => { 1352 console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}'); 1353 }); 1354 return true; 1355 } 1356} 1357 1358async function Marshalling_UnMarshalling() { 1359 if (pictureObj != null) { 1360 let parcelable: MySequence = new MySequence(pictureObj); 1361 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 1362 // marshalling. 1363 data.writeParcelable(parcelable); 1364 let ret: MySequence = new MySequence(pictureObj); 1365 // unmarshalling. 1366 data.readParcelable(ret); 1367 } else { 1368 console.error('PictureObj is null'); 1369 } 1370} 1371``` 1372 1373### release<sup>13+</sup> 1374 1375release(): void 1376 1377释放picture对象。 1378 1379**系统能力：** SystemCapability.Multimedia.Image.Core 1380 1381**示例：** 1382 1383```ts 1384import { image } from '@kit.ImageKit'; 1385 1386async function Release() { 1387 let funcName = "Release"; 1388 if (pictureObj != null) { 1389 pictureObj.release(); 1390 if (pictureObj.getMainPixelmap() == null) { 1391 console.info(funcName, 'Success !'); 1392 } else { 1393 console.error(funcName, 'Failed !'); 1394 } 1395 } else { 1396 console.error('PictureObj is null'); 1397 } 1398} 1399``` 1400 1401## PixelMap<sup>7+</sup> 1402 1403图像像素类，用于读取或写入图像数据以及获取图像信息。在调用PixelMap的方法前，需要先通过[createPixelMap](#imagecreatepixelmap8)创建一个PixelMap实例。目前pixelmap序列化大小最大128MB，超过会送显失败。大小计算方式为(宽\*高\*每像素占用字节数)。 1404 1405从API version 11开始，PixelMap支持通过worker跨线程调用。当PixelMap通过[Worker](../apis-arkts/js-apis-worker.md)跨线程后，原线程的PixelMap的所有接口均不能调用，否则将报错501 服务器不具备完成请求的功能。 1406 1407在调用PixelMap的方法前，需要先通过[image.createPixelMap](#imagecreatepixelmap8)构建一个PixelMap对象。 1408 1409开发原子化服务请通过[ImageSoure](#imagesource)构建PixelMap对象。 1410 1411### 属性 1412 1413**系统能力：** SystemCapability.Multimedia.Image.Core 1414 1415| 名称 | 类型 | 只读 | 可选 | 说明 | 1416| -----------------| ------- | ---- | ---- | -------------------------- | 1417| isEditable | boolean | 是 | 否 | true表示图像像素可被编辑，false表示不可被编辑。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 1418| isStrideAlignment<sup>11+</sup> | boolean | 是 | 否 | true表示图像内存为DMA内存，false表示非DMA内存。 | 1419 1420### readPixelsToBuffer<sup>7+</sup> 1421 1422readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 1423 1424按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用Promise形式返回。 1425 1426**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1427 1428**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1429 1430**系统能力：** SystemCapability.Multimedia.Image.Core 1431 1432**参数：** 1433 1434| 参数名 | 类型 | 必填 | 说明 | 1435| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 1436| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1437 1438**返回值：** 1439 1440| 类型 | 说明 | 1441| -------------- | ----------------------------------------------- | 1442| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1443 1444**示例：** 1445 1446```ts 1447import { BusinessError } from '@kit.BasicServicesKit'; 1448import { image } from '@kit.ImageKit'; 1449 1450async function ReadPixelsToBuffer(pixelMap : image.PixelMap) { 1451 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1452 if (pixelMap != undefined) { 1453 pixelMap.readPixelsToBuffer(readBuffer).then(() => { 1454 console.info('Succeeded in reading image pixel data.'); // 符合条件则进入。 1455 }).catch((error: BusinessError) => { 1456 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1457 }) 1458 } 1459} 1460``` 1461 1462### readPixelsToBuffer<sup>7+</sup> 1463 1464readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback\<void>): void 1465 1466按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用callback形式返回。 1467 1468**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1469 1470**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1471 1472**系统能力：** SystemCapability.Multimedia.Image.Core 1473 1474**参数：** 1475 1476| 参数名 | 类型 | 必填 | 说明 | 1477| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 1478| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1479| callback | AsyncCallback\<void> | 是 | 回调函数。当读取像素数据到ArrayBuffer成功，err为undefined，否则为错误对象。 | 1480 1481**示例：** 1482 1483```ts 1484import { BusinessError } from '@kit.BasicServicesKit'; 1485import { image } from '@kit.ImageKit'; 1486 1487async function ReadPixelsToBuffer(pixelMap : image.PixelMap) { 1488 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1489 if (pixelMap != undefined) { 1490 pixelMap.readPixelsToBuffer(readBuffer, (error: BusinessError, res: void) => { 1491 if(error) { 1492 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1493 return; 1494 } else { 1495 console.info('Succeeded in reading image pixel data.'); //符合条件则进入。 1496 } 1497 }) 1498 } 1499} 1500``` 1501 1502### readPixelsToBufferSync<sup>12+</sup> 1503 1504readPixelsToBufferSync(dst: ArrayBuffer): void 1505 1506按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，同步返回结果。 1507 1508**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1509 1510**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1511 1512**系统能力：** SystemCapability.Multimedia.Image.Core 1513 1514**参数：** 1515 1516| 参数名 | 类型 | 必填 | 说明 | 1517| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 1518| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1519 1520**错误码：** 1521 1522以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1523 1524| 错误码ID | 错误信息 | 1525| ------- | --------------------------------------------| 1526| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1527| 501 | Resource Unavailable | 1528 1529**示例：** 1530 1531```ts 1532import { BusinessError } from '@kit.BasicServicesKit'; 1533import { image } from '@kit.ImageKit'; 1534 1535async function ReadPixelsToBufferSync(pixelMap : image.PixelMap) { 1536 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1537 if (pixelMap != undefined) { 1538 pixelMap.readPixelsToBufferSync(readBuffer); 1539 } 1540} 1541``` 1542 1543### readPixels<sup>7+</sup> 1544 1545readPixels(area: PositionArea): Promise\<void> 1546 1547固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，使用Promise形式返回。 1548 1549可用公式计算PositionArea需要申请的内存大小。 1550 1551YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1552 1553RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1554 1555**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1556 1557**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1558 1559**系统能力：** SystemCapability.Multimedia.Image.Core 1560 1561**参数：** 1562 1563| 参数名 | 类型 | 必填 | 说明 | 1564| ------ | ------------------------------ | ---- | ------------------------ | 1565| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1566 1567**返回值：** 1568 1569| 类型 | 说明 | 1570| :------------- | :-------------------------------------------------- | 1571| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1572 1573**示例：** 1574 1575```ts 1576import { BusinessError } from '@kit.BasicServicesKit'; 1577import { image } from '@kit.ImageKit'; 1578 1579async function ReadPixelsRGBA(pixelMap : image.PixelMap) { 1580 const area: image.PositionArea = { 1581 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1582 offset: 0, 1583 stride: 8, 1584 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1585 }; 1586 if (pixelMap != undefined) { 1587 pixelMap.readPixels(area).then(() => { 1588 console.info('Succeeded in reading the image data in the area.'); //符合条件则进入。 1589 }).catch((error: BusinessError) => { 1590 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1591 }) 1592 } 1593} 1594 1595async function ReadPixelsYUV(pixelMap : image.PixelMap) { 1596 const area: image.PositionArea = { 1597 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1598 offset: 0, 1599 stride: 8, 1600 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1601 }; 1602 if (pixelMap != undefined) { 1603 pixelMap.readPixels(area).then(() => { 1604 console.info('Succeeded in reading the image data in the area.'); //符合条件则进入。 1605 }).catch((error: BusinessError) => { 1606 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1607 }) 1608 } 1609} 1610``` 1611 1612### readPixels<sup>7+</sup> 1613 1614readPixels(area: PositionArea, callback: AsyncCallback\<void>): void 1615 1616固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，使用callback形式返回。 1617 1618可用公式计算PositionArea需要申请的内存大小。 1619 1620YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1621 1622RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1623 1624**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1625 1626**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1627 1628**系统能力：** SystemCapability.Multimedia.Image.Core 1629 1630**参数：** 1631 1632| 参数名 | 类型 | 必填 | 说明 | 1633| -------- | ------------------------------ | ---- | ------------------------------ | 1634| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1635| callback | AsyncCallback\<void> | 是 | 回调函数。当读取区域内的图片数据成功，err为undefined，否则为错误对象。 | 1636 1637**示例：** 1638 1639```ts 1640import { BusinessError } from '@kit.BasicServicesKit'; 1641import { image } from '@kit.ImageKit'; 1642 1643async function ReadPixelsRGBA(pixelMap : image.PixelMap) { 1644 const area: image.PositionArea = { 1645 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1646 offset: 0, 1647 stride: 8, 1648 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1649 }; 1650 if (pixelMap != undefined) { 1651 pixelMap.readPixels(area, (error: BusinessError) => { 1652 if (error) { 1653 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 1654 return; 1655 } else { 1656 console.info('Succeeded in reading pixelmap from the specified area.'); 1657 } 1658 }) 1659 } 1660} 1661 1662async function ReadPixelsYUV(pixelMap : image.PixelMap) { 1663 const area: image.PositionArea = { 1664 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1665 offset: 0, 1666 stride: 8, 1667 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1668 }; 1669 if (pixelMap != undefined) { 1670 pixelMap.readPixels(area, (error: BusinessError) => { 1671 if (error) { 1672 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 1673 return; 1674 } else { 1675 console.info('Succeeded in reading pixelmap from the specified area.'); 1676 } 1677 }) 1678 } 1679} 1680``` 1681 1682### readPixelsSync<sup>12+</sup> 1683 1684readPixelsSync(area: PositionArea): void 1685 1686固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，同步返回结果。 1687 1688**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1689 1690**系统能力：** SystemCapability.Multimedia.Image.Core 1691 1692**参数：** 1693 1694| 参数名 | 类型 | 必填 | 说明 | 1695| ------ | ------------------------------ | ---- | ------------------------ | 1696| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1697 1698**错误码：** 1699 1700以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1701 1702| 错误码ID | 错误信息 | 1703| ------- | --------------------------------------------| 1704| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1705| 501 | Resource Unavailable | 1706 1707**示例：** 1708 1709```ts 1710import { BusinessError } from '@kit.BasicServicesKit'; 1711 1712async function ReadPixelsSync(pixelMap : image.PixelMap) { 1713 const area : image.PositionArea = { 1714 pixels: new ArrayBuffer(8), 1715 offset: 0, 1716 stride: 8, 1717 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1718 }; 1719 if (pixelMap != undefined) { 1720 pixelMap.readPixelsSync(area); 1721 } 1722} 1723``` 1724 1725### writePixels<sup>7+</sup> 1726 1727writePixels(area: PositionArea): Promise\<void> 1728 1729固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，使用Promise形式返回。 1730 1731可用公式计算PositionArea需要申请的内存大小。 1732 1733YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1734 1735RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1736 1737**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1738 1739**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1740 1741**系统能力：** SystemCapability.Multimedia.Image.Core 1742 1743**参数：** 1744 1745| 参数名 | 类型 | 必填 | 说明 | 1746| ------ | ------------------------------ | ---- | -------------------- | 1747| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1748 1749**返回值：** 1750 1751| 类型 | 说明 | 1752| :------------- | :-------------------------------------------------- | 1753| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1754 1755**示例：** 1756 1757```ts 1758import { BusinessError } from '@kit.BasicServicesKit'; 1759 1760async function WritePixelsRGBA() { 1761 const area: image.PositionArea = { 1762 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1763 offset: 0, 1764 stride: 8, 1765 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1766 }; 1767 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1768 for (let i = 0; i < bufferArr.length; i++) { 1769 bufferArr[i] = i + 1; 1770 } 1771 if (pixelMap != undefined) { 1772 pixelMap.writePixels(area).then(() => { 1773 console.info('Succeeded in writing pixelmap into the specified area.'); 1774 }).catch((error: BusinessError) => { 1775 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1776 }) 1777 } 1778} 1779 1780async function WritePixelsYUV() { 1781 const area: image.PositionArea = { 1782 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1783 offset: 0, 1784 stride: 8, 1785 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1786 }; 1787 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1788 for (let i = 0; i < bufferArr.length; i++) { 1789 bufferArr[i] = i + 1; 1790 } 1791 if (pixelMap != undefined) { 1792 pixelMap.writePixels(area).then(() => { 1793 console.info('Succeeded in writing pixelmap into the specified area.'); 1794 }).catch((error: BusinessError) => { 1795 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1796 }) 1797 } 1798} 1799``` 1800 1801### writePixels<sup>7+</sup> 1802 1803writePixels(area: PositionArea, callback: AsyncCallback\<void>): void 1804 1805固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，使用callback形式返回。 1806 1807可用公式计算PositionArea需要申请的内存大小。 1808 1809YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1810 1811RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1812 1813**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1814 1815**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1816 1817**系统能力：** SystemCapability.Multimedia.Image.Core 1818 1819**参数：** 1820 1821| 参数名 | 类型 | 必填 | 说明 | 1822| --------- | ------------------------------ | ---- | ------------------------------ | 1823| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1824| callback | AsyncCallback\<void> | 是 | 回调函数，当写入成功，err为undefined，否则为错误对象。 | 1825 1826**示例：** 1827 1828```ts 1829import { BusinessError } from '@kit.BasicServicesKit'; 1830 1831async function WritePixelsRGBA() { 1832 const area: image.PositionArea = { pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1833 offset: 0, 1834 stride: 8, 1835 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1836 }; 1837 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1838 for (let i = 0; i < bufferArr.length; i++) { 1839 bufferArr[i] = i + 1; 1840 } 1841 if (pixelMap != undefined) { 1842 pixelMap.writePixels(area, (error : BusinessError) => { 1843 if (error) { 1844 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1845 return; 1846 } else { 1847 console.info('Succeeded in writing pixelmap into the specified area.'); 1848 } 1849 }) 1850 } 1851} 1852 1853async function WritePixelsYUV() { 1854 const area: image.PositionArea = { pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1855 offset: 0, 1856 stride: 8, 1857 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1858 }; 1859 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1860 for (let i = 0; i < bufferArr.length; i++) { 1861 bufferArr[i] = i + 1; 1862 } 1863 if (pixelMap != undefined) { 1864 pixelMap.writePixels(area, (error : BusinessError) => { 1865 if (error) { 1866 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1867 return; 1868 } else { 1869 console.info('Succeeded in writing pixelmap into the specified area.'); 1870 } 1871 }) 1872 } 1873} 1874``` 1875 1876### writePixelsSync<sup>12+</sup> 1877 1878writePixelsSync(area: PositionArea): void 1879 1880固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，同步返回结果。 1881 1882**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1883 1884**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1885 1886**系统能力：** SystemCapability.Multimedia.Image.Core 1887 1888**参数：** 1889 1890| 参数名 | 类型 | 必填 | 说明 | 1891| ------ | ------------------------------ | ---- | -------------------- | 1892| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1893 1894**错误码：** 1895 1896以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1897 1898| 错误码ID | 错误信息 | 1899| ------- | --------------------------------------------| 1900| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1901| 501 | Resource Unavailable | 1902 1903**示例：** 1904 1905```ts 1906import { BusinessError } from '@kit.BasicServicesKit'; 1907 1908async function WritePixelsSync() { 1909 const area: image.PositionArea = { 1910 pixels: new ArrayBuffer(8), 1911 offset: 0, 1912 stride: 8, 1913 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1914 }; 1915 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1916 for (let i = 0; i < bufferArr.length; i++) { 1917 bufferArr[i] = i + 1; 1918 } 1919 if (pixelMap != undefined) { 1920 pixelMap.writePixelsSync(area); 1921 } 1922} 1923``` 1924 1925### writeBufferToPixels<sup>7+</sup> 1926 1927writeBufferToPixels(src: ArrayBuffer): Promise\<void> 1928 1929按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用Promise形式返回。 1930 1931**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1932 1933**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1934 1935**系统能力：** SystemCapability.Multimedia.Image.Core 1936 1937**参数：** 1938 1939| 参数名 | 类型 | 必填 | 说明 | 1940| ------ | ----------- | ---- | -------------- | 1941| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1942 1943**返回值：** 1944 1945| 类型 | 说明 | 1946| -------------- | ----------------------------------------------- | 1947| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1948 1949**示例：** 1950 1951```ts 1952import { BusinessError } from '@kit.BasicServicesKit'; 1953 1954async function WriteBufferToPixels() { 1955 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1956 let bufferArr: Uint8Array = new Uint8Array(color); 1957 for (let i = 0; i < bufferArr.length; i++) { 1958 bufferArr[i] = i + 1; 1959 } 1960 if (pixelMap != undefined) { 1961 pixelMap.writeBufferToPixels(color).then(() => { 1962 console.info("Succeeded in writing data from a buffer to a PixelMap."); 1963 }).catch((error: BusinessError) => { 1964 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 1965 }) 1966 } 1967} 1968``` 1969 1970### writeBufferToPixels<sup>7+</sup> 1971 1972writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback\<void>): void 1973 1974按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用callback形式返回。 1975 1976**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1977 1978**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1979 1980**系统能力：** SystemCapability.Multimedia.Image.Core 1981 1982**参数：** 1983 1984| 参数名 | 类型 | 必填 | 说明 | 1985| -------- | -------------------- | ---- | ------------------------------ | 1986| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1987| callback | AsyncCallback\<void> | 是 | 回调函数。当缓冲区中的图像像素数据写入PixelMap成功，err为undefined，否则为错误对象。 | 1988 1989**示例：** 1990 1991```ts 1992import { BusinessError } from '@kit.BasicServicesKit'; 1993 1994async function WriteBufferToPixels() { 1995 const color: ArrayBuffer = new ArrayBuffer(96); //96为需要创建的像素buffer大小，取值为：height * width *4。 1996 let bufferArr: Uint8Array = new Uint8Array(color); 1997 for (let i = 0; i < bufferArr.length; i++) { 1998 bufferArr[i] = i + 1; 1999 } 2000 if (pixelMap != undefined) { 2001 pixelMap.writeBufferToPixels(color, (error: BusinessError) => { 2002 if (error) { 2003 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 2004 return; 2005 } else { 2006 console.info("Succeeded in writing data from a buffer to a PixelMap."); 2007 } 2008 }) 2009 } 2010} 2011``` 2012 2013### writeBufferToPixelsSync<sup>12+</sup> 2014 2015writeBufferToPixelsSync(src: ArrayBuffer): void 2016 2017按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，同步返回结果。 2018 2019**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2020 2021**系统能力：** SystemCapability.Multimedia.Image.Core 2022 2023**参数：** 2024 2025| 参数名 | 类型 | 必填 | 说明 | 2026| ------ | ----------- | ---- | -------------- | 2027| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 2028 2029**错误码：** 2030 2031以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2032 2033| 错误码ID | 错误信息 | 2034| ------- | --------------------------------------------| 2035| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2036| 501 | Resource Unavailable | 2037 2038**示例：** 2039 2040```ts 2041import { BusinessError } from '@kit.BasicServicesKit'; 2042 2043async function WriteBufferToPixelsSync() { 2044 const color : ArrayBuffer = new ArrayBuffer(96); //96为需要创建的像素buffer大小，取值为：height * width *4。 2045 let bufferArr : Uint8Array = new Uint8Array(color); 2046 for (let i = 0; i < bufferArr.length; i++) { 2047 bufferArr[i] = i + 1; 2048 } 2049 if (pixelMap != undefined) { 2050 pixelMap.writeBufferToPixelsSync(color); 2051 } 2052} 2053``` 2054 2055 2056### getImageInfo<sup>7+</sup> 2057 2058getImageInfo(): Promise\<ImageInfo> 2059 2060获取图像像素信息，使用Promise形式返回获取的图像像素信息。 2061 2062**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2063 2064**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2065 2066**系统能力：** SystemCapability.Multimedia.Image.Core 2067 2068**返回值：** 2069 2070| 类型 | 说明 | 2071| --------------------------------- | ----------------------------------------------------------- | 2072| Promise\<[ImageInfo](#imageinfo)> | Promise对象，返回图像像素信息。 | 2073 2074**示例：** 2075 2076```ts 2077import { BusinessError } from '@kit.BasicServicesKit'; 2078 2079async function GetImageInfo() { 2080 if (pixelMap != undefined) { 2081 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 2082 if (imageInfo != undefined) { 2083 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 2084 } 2085 }).catch((error: BusinessError) => { 2086 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 2087 }) 2088 } 2089} 2090``` 2091 2092### getImageInfo<sup>7+</sup> 2093 2094getImageInfo(callback: AsyncCallback\<ImageInfo>): void 2095 2096获取图像像素信息，使用callback形式返回获取的图像像素信息。 2097 2098**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2099 2100**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2101 2102**系统能力：** SystemCapability.Multimedia.Image.Core 2103 2104**参数：** 2105 2106| 参数名 | 类型 | 必填 | 说明 | 2107| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 2108| callback | AsyncCallback\<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图像像素信息成功，err为undefined，data为获取到的图像像素信息；否则为错误对象。 | 2109 2110**示例:** 2111 2112```ts 2113import { BusinessError } from '@kit.BasicServicesKit'; 2114 2115async function GetImageInfo() { 2116 if (pixelMap != undefined) { 2117 pixelMap.getImageInfo((error: BusinessError, imageInfo: image.ImageInfo) => { 2118 if (error) { 2119 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 2120 return; 2121 } else { 2122 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 2123 } 2124 }) 2125 } 2126} 2127``` 2128 2129### getImageInfoSync<sup>12+</sup> 2130 2131getImageInfoSync(): ImageInfo 2132 2133以同步方法获取图像像素信息。 2134 2135**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2136 2137**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2138 2139**系统能力：** SystemCapability.Multimedia.Image.ImageSource 2140 2141**返回值：** 2142 2143| 类型 | 说明 | 2144| --------------------------------- | ----------------------------------------------------------- | 2145| [ImageInfo](#imageinfo) | 图像像素信息。 | 2146 2147**错误码：** 2148 2149以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2150 2151| 错误码ID | 错误信息 | 2152| ------- | --------------------------------------------| 2153| 501 | Resource Unavailable | 2154 2155**示例：** 2156 2157```ts 2158import { BusinessError } from '@kit.BasicServicesKit'; 2159 2160async function GetImageInfoSync() { 2161 if (pixelMap != undefined) { 2162 let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync(); 2163 return imageInfo; 2164 } 2165 return undefined; 2166} 2167``` 2168 2169### getBytesNumberPerRow<sup>7+</sup> 2170 2171getBytesNumberPerRow(): number 2172 2173获取图像像素每行字节数。 2174 2175**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2176 2177**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2178 2179**系统能力：** SystemCapability.Multimedia.Image.Core 2180 2181**返回值：** 2182 2183| 类型 | 说明 | 2184| ------ | -------------------- | 2185| number | 图像像素的行字节数。 | 2186 2187**示例：** 2188 2189```ts 2190let rowCount: number = pixelMap.getBytesNumberPerRow(); 2191``` 2192 2193### getPixelBytesNumber<sup>7+</sup> 2194 2195getPixelBytesNumber(): number 2196 2197获取图像像素的总字节数。 2198 2199**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2200 2201**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2202 2203**系统能力：** SystemCapability.Multimedia.Image.Core 2204 2205**返回值：** 2206 2207| 类型 | 说明 | 2208| ------ | -------------------- | 2209| number | 图像像素的总字节数。 | 2210 2211**示例：** 2212 2213```ts 2214let pixelBytesNumber: number = pixelMap.getPixelBytesNumber(); 2215``` 2216 2217### getDensity<sup>9+</sup> 2218 2219getDensity():number 2220 2221获取当前图像像素的密度。 2222 2223**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2224 2225**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2226 2227**系统能力：** SystemCapability.Multimedia.Image.Core 2228 2229**返回值：** 2230 2231| 类型 | 说明 | 2232| ------ | --------------- | 2233| number | 图像像素的密度，单位为ppi。| 2234 2235**示例：** 2236 2237```ts 2238let getDensity: number = pixelMap.getDensity(); 2239``` 2240 2241### opacity<sup>9+</sup> 2242 2243opacity(rate: number, callback: AsyncCallback\<void>): void 2244 2245通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用callback形式返回。 2246 2247**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2248 2249**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2250 2251**系统能力：** SystemCapability.Multimedia.Image.Core 2252 2253**参数：** 2254 2255| 参数名 | 类型 | 必填 | 说明 | 2256| -------- | -------------------- | ---- | ------------------------------ | 2257| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 2258| callback | AsyncCallback\<void> | 是 | 回调函数。当设置透明比率成功，err为undefined，否则为错误对象。 | 2259 2260**示例：** 2261 2262```ts 2263import { BusinessError } from '@kit.BasicServicesKit'; 2264 2265async function Opacity() { 2266 let rate: number = 0.5; 2267 if (pixelMap != undefined) { 2268 pixelMap.opacity(rate, (err: BusinessError) => { 2269 if (err) { 2270 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 2271 return; 2272 } else { 2273 console.info("Succeeded in setting opacity."); 2274 } 2275 }) 2276 } 2277} 2278``` 2279 2280### opacity<sup>9+</sup> 2281 2282opacity(rate: number): Promise\<void> 2283 2284通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用Promise形式返回。 2285 2286**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2287 2288**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2289 2290**系统能力：** SystemCapability.Multimedia.Image.Core 2291 2292**参数：** 2293 2294| 参数名 | 类型 | 必填 | 说明 | 2295| ------ | ------ | ---- | --------------------------- | 2296| rate | number | 是 | 透明比率的值，取值范围是(0,1]。| 2297 2298**返回值：** 2299 2300| 类型 | 说明 | 2301| -------------- | ----------------------------------------------- | 2302| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2303 2304**示例：** 2305 2306```ts 2307import { BusinessError } from '@kit.BasicServicesKit'; 2308 2309async function Opacity() { 2310 let rate: number = 0.5; 2311 if (pixelMap != undefined) { 2312 pixelMap.opacity(rate).then(() => { 2313 console.info('Succeeded in setting opacity.'); 2314 }).catch((err: BusinessError) => { 2315 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 2316 }) 2317 } 2318} 2319``` 2320 2321### opacitySync<sup>12+</sup> 2322 2323opacitySync(rate: number): void 2324 2325设置PixelMap的透明比率，yuv图片不支持设置透明度，初始化PixelMap并同步返回结果。 2326 2327**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2328 2329**系统能力：** SystemCapability.Multimedia.Image.Core 2330 2331**参数：** 2332 2333| 参数名 | 类型 | 必填 | 说明 | 2334| -------- | -------------------- | ---- | ------------------------------ | 2335| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 2336 2337**错误码：** 2338 2339以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2340 2341| 错误码ID | 错误信息 | 2342| ------- | --------------------------------------------| 2343| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2344| 501 | Resource Unavailable | 2345 2346**示例：** 2347 2348```ts 2349import { BusinessError } from '@kit.BasicServicesKit'; 2350 2351async function OpacitySync() { 2352 let rate : number = 0.5; 2353 if (pixelMap != undefined) { 2354 pixelMap.opacitySync(rate); 2355 } 2356} 2357``` 2358 2359### createAlphaPixelmap<sup>9+</sup> 2360 2361createAlphaPixelmap(): Promise\<PixelMap> 2362 2363根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用Promise形式返回。 2364 2365**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2366 2367**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2368 2369**系统能力：** SystemCapability.Multimedia.Image.Core 2370 2371**返回值：** 2372 2373| 类型 | 说明 | 2374| -------------------------------- | --------------------------- | 2375| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 2376 2377**示例：** 2378 2379```ts 2380import { BusinessError } from '@kit.BasicServicesKit'; 2381 2382async function CreateAlphaPixelmap() { 2383 if (pixelMap != undefined) { 2384 pixelMap.createAlphaPixelmap().then((alphaPixelMap: image.PixelMap) => { 2385 console.info('Succeeded in creating alpha pixelmap.'); 2386 }).catch((error: BusinessError) => { 2387 console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`); 2388 }) 2389 } 2390} 2391``` 2392 2393### createAlphaPixelmap<sup>9+</sup> 2394 2395createAlphaPixelmap(callback: AsyncCallback\<PixelMap>): void 2396 2397根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用callback形式返回。 2398 2399**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2400 2401**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2402 2403**系统能力：** SystemCapability.Multimedia.Image.Core 2404 2405**参数：** 2406 2407| 参数名 | 类型 | 必填 | 说明 | 2408| -------- | ------------------------ | ---- | ------------------------ | 2409| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 2410 2411**示例：** 2412 2413```ts 2414import { BusinessError } from '@kit.BasicServicesKit'; 2415 2416async function CreateAlphaPixelmap() { 2417 if (pixelMap != undefined) { 2418 pixelMap.createAlphaPixelmap((err: BusinessError, alphaPixelMap: image.PixelMap) => { 2419 if (alphaPixelMap == undefined) { 2420 console.error(`Failed to obtain new pixel map. code is ${err.code}, message is ${err.message}`); 2421 return; 2422 } else { 2423 console.info('Succeeded in obtaining new pixel map.'); 2424 } 2425 }) 2426 } 2427} 2428``` 2429 2430### createAlphaPixelmapSync<sup>12+</sup> 2431 2432createAlphaPixelmapSync(): PixelMap 2433 2434根据Alpha通道的信息，生成一个仅包含Alpha通道信息的PixelMap，可用于阴影效果，yuv格式不支持此接口，同步返回PixelMap类型的结果。 2435 2436**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2437 2438**系统能力：** SystemCapability.Multimedia.Image.Core 2439 2440**返回值：** 2441 2442| 类型 | 说明 | 2443| -------------------------------- | --------------------- | 2444| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2445 2446**错误码：** 2447 2448以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2449 2450| 错误码ID | 错误信息 | 2451| ------- | --------------------------------------------| 2452| 401 | Parameter error. Possible causes: 1.Parameter verification failed | 2453| 501 | Resource Unavailable | 2454 2455**示例：** 2456 2457```ts 2458import { BusinessError } from '@kit.BasicServicesKit'; 2459 2460async function CreateAlphaPixelmapSync() { 2461 if (pixelMap != undefined) { 2462 let pixelmap : image.PixelMap = pixelMap.createAlphaPixelmapSync(); 2463 return pixelmap; 2464 } 2465 return undefined; 2466} 2467``` 2468 2469### scale<sup>9+</sup> 2470 2471scale(x: number, y: number, callback: AsyncCallback\<void>): void 2472 2473根据输入的宽高的缩放倍数对图片进行缩放，使用callback形式返回。 2474 2475> **说明：** 2476> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2477> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2478 2479**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2480 2481**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2482 2483**系统能力：** SystemCapability.Multimedia.Image.Core 2484 2485**参数：** 2486 2487| 参数名 | 类型 | 必填 | 说明 | 2488| -------- | -------------------- | ---- | ------------------------------- | 2489| x | number | 是 | 宽度的缩放倍数。| 2490| y | number | 是 | 高度的缩放倍数。| 2491| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行缩放成功，err为undefined，否则为错误对象。 | 2492 2493**示例：** 2494 2495```ts 2496import { BusinessError } from '@kit.BasicServicesKit'; 2497 2498async function Scale() { 2499 let scaleX: number = 2.0; 2500 let scaleY: number = 1.0; 2501 if (pixelMap != undefined) { 2502 pixelMap.scale(scaleX, scaleY, (err: BusinessError) => { 2503 if (err) { 2504 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2505 return; 2506 } else { 2507 console.info("Succeeded in scaling pixelmap."); 2508 } 2509 }) 2510 } 2511} 2512``` 2513 2514### scale<sup>9+</sup> 2515 2516scale(x: number, y: number): Promise\<void> 2517 2518根据输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 2519 2520> **说明：** 2521> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2522> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2523 2524**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2525 2526**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2527 2528**系统能力：** SystemCapability.Multimedia.Image.Core 2529 2530**参数：** 2531 2532| 参数名 | 类型 | 必填 | 说明 | 2533| ------ | ------ | ---- | ------------------------------- | 2534| x | number | 是 | 宽度的缩放倍数。| 2535| y | number | 是 | 高度的缩放倍数。| 2536 2537**返回值：** 2538 2539| 类型 | 说明 | 2540| -------------- | --------------------------- | 2541| Promise\<void> | Promise对象。无返回结果的Promise对象。| 2542 2543**示例：** 2544 2545```ts 2546import { BusinessError } from '@kit.BasicServicesKit'; 2547 2548async function Scale() { 2549 let scaleX: number = 2.0; 2550 let scaleY: number = 1.0; 2551 if (pixelMap != undefined) { 2552 pixelMap.scale(scaleX, scaleY).then(() => { 2553 console.info('Succeeded in scaling pixelmap.'); 2554 }).catch((err: BusinessError) => { 2555 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2556 2557 }) 2558 } 2559} 2560``` 2561 2562### scaleSync<sup>12+</sup> 2563 2564scaleSync(x: number, y: number): void 2565 2566根据输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 2567 2568> **说明：** 2569> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2570> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2571 2572**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2573 2574**系统能力：** SystemCapability.Multimedia.Image.Core 2575 2576**参数：** 2577 2578| 参数名 | 类型 | 必填 | 说明 | 2579| ------ | ------ | ---- | ------------------------------- | 2580| x | number | 是 | 宽度的缩放倍数。| 2581| y | number | 是 | 高度的缩放倍数。| 2582 2583**错误码：** 2584 2585以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2586 2587| 错误码ID | 错误信息 | 2588| ------- | --------------------------------------------| 2589| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2590| 501 | Resource Unavailable | 2591 2592**示例：** 2593 2594```ts 2595import { BusinessError } from '@kit.BasicServicesKit'; 2596 2597async function ScaleSync() { 2598 let scaleX: number = 2.0; 2599 let scaleY: number = 1.0; 2600 if (pixelMap != undefined) { 2601 pixelMap.scaleSync(scaleX, scaleY); 2602 } 2603} 2604``` 2605 2606### scale<sup>12+</sup> 2607 2608scale(x: number, y: number, level: AntiAliasingLevel): Promise\<void> 2609 2610根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 2611 2612> **说明：** 2613> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2614> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2615 2616**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2617 2618**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2619 2620**系统能力：** SystemCapability.Multimedia.Image.Core 2621 2622**参数：** 2623 2624| 参数名 | 类型 | 必填 | 说明 | 2625| ------ | ------ | ---- | ------------------------------- | 2626| x | number | 是 | 宽度的缩放倍数。| 2627| y | number | 是 | 高度的缩放倍数。| 2628| level | [AntiAliasingLevel](#antialiasinglevel12) | 是 | 采用的缩放算法。| 2629 2630**返回值：** 2631 2632| 类型 | 说明 | 2633| -------------- | --------------------------- | 2634| Promise\<void> | Promise对象。无返回结果的Promise对象。| 2635 2636**错误码：** 2637 2638以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2639 2640| 错误码ID | 错误信息 | 2641| ------- | --------------------------------------------| 2642| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2643| 501 | Resource Unavailable | 2644 2645**示例：** 2646 2647```ts 2648import { BusinessError } from '@kit.BasicServicesKit'; 2649 2650async function Scale() { 2651 let scaleX: number = 2.0; 2652 let scaleY: number = 1.0; 2653 if (pixelMap != undefined) { 2654 pixelMap.scale(scaleX, scaleY, image.AntiAliasingLevel.LOW).then(() => { 2655 console.info('Succeeded in scaling pixelmap.'); 2656 }).catch((err: BusinessError) => { 2657 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2658 2659 }) 2660 } 2661} 2662``` 2663 2664### scaleSync<sup>12+</sup> 2665 2666scaleSync(x: number, y: number, level: AntiAliasingLevel): void 2667 2668根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 2669 2670> **说明：** 2671> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2672> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2673 2674**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2675 2676**系统能力：** SystemCapability.Multimedia.Image.Core 2677 2678**参数：** 2679 2680| 参数名 | 类型 | 必填 | 说明 | 2681| ------ | ------ | ---- | ------------------------------- | 2682| x | number | 是 | 宽度的缩放倍数。| 2683| y | number | 是 | 高度的缩放倍数。| 2684| level | [AntiAliasingLevel](#antialiasinglevel12) | 是 | 采用的缩放算法。| 2685 2686**错误码：** 2687 2688以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2689 2690| 错误码ID | 错误信息 | 2691| ------- | --------------------------------------------| 2692| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2693| 501 | Resource Unavailable | 2694 2695**示例：** 2696 2697```ts 2698import { BusinessError } from '@kit.BasicServicesKit'; 2699 2700async function ScaleSync() { 2701 let scaleX: number = 2.0; 2702 let scaleY: number = 1.0; 2703 if (pixelMap != undefined) { 2704 pixelMap.scaleSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 2705 } 2706} 2707``` 2708 2709### createScaledPixelMap<sup>18+</sup> 2710 2711createScaledPixelMap(x: number, y: number, level?: AntiAliasingLevel): Promise\<PixelMap> 2712 2713根据指定的缩放算法和输入的宽高的缩放倍数，创建一个新的缩放后的图片，使用Promise形式返回。 2714 2715**系统能力：** SystemCapability.Multimedia.Image.Core 2716 2717**参数：** 2718 2719| 参数名 | 类型 | 必填 | 说明 | 2720| ------ | ------ | ---- | ------------------------------- | 2721| x | number | 是 | 宽度的缩放倍数。| 2722| y | number | 是 | 高度的缩放倍数。| 2723| level | [AntiAliasingLevel](#antialiasinglevel12) | 否 | 采用的缩放算法。| 2724 2725**返回值：** 2726 2727| 类型 | 说明 | 2728| -------------- | --------------------------- | 2729| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 2730 2731**错误码：** 2732 2733以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2734 2735| 错误码ID | 错误信息 | 2736| ------- | --------------------------------------------| 2737| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2738| 501 | Resource Unavailable | 2739 2740**示例：** 2741 2742```ts 2743import { BusinessError } from '@kit.BasicServicesKit'; 2744 2745async function CreateScaledPixelMap() { 2746 let scaleX: number = 2.0; 2747 let scaleY: number = 1.0; 2748 if (pixelMap != undefined) { 2749 pixelMap.createScaledPixelMap(scaleX, scaleY, image.AntiAliasingLevel.LOW).then((scaledPixelMap: image.PixelMap) => { 2750 console.info('Succeeded in creating scaledPixelMap.'); 2751 }).catch((error: BusinessError) => { 2752 console.error(`Failed to create scaledPixelMap. Error code is ${error.code}, error message is ${error.message}`); 2753 }) 2754 } 2755} 2756``` 2757 2758### createScaledPixelMapSync<sup>18+</sup> 2759 2760createScaledPixelMapSync(x: number, y: number, level?: AntiAliasingLevel): PixelMap 2761 2762根据指定的缩放算法和输入的宽高的缩放倍数，创建一个新的缩放后的图片，同步返回结果。 2763 2764**系统能力：** SystemCapability.Multimedia.Image.Core 2765 2766**参数：** 2767 2768| 参数名 | 类型 | 必填 | 说明 | 2769| ------ | ------ | ---- | ------------------------------- | 2770| x | number | 是 | 宽度的缩放倍数。| 2771| y | number | 是 | 高度的缩放倍数。| 2772| level | [AntiAliasingLevel](#antialiasinglevel12) | 否 | 采用的缩放算法。| 2773 2774**返回值：** 2775 2776| 类型 | 说明 | 2777| -------------------------------- | --------------------- | 2778| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2779 2780**错误码：** 2781 2782以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2783 2784| 错误码ID | 错误信息 | 2785| ------- | --------------------------------------------| 2786| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2787| 501 | Resource Unavailable | 2788 2789**示例：** 2790 2791```ts 2792import { BusinessError } from '@kit.BasicServicesKit'; 2793 2794async function CreateScaledPixelMapSync() { 2795 let scaleX: number = 2.0; 2796 let scaleY: number = 1.0; 2797 if (pixelMap != undefined) { 2798 let scaledPixelMap = pixelMap.createScaledPixelMapSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 2799 } 2800} 2801``` 2802 2803### clone<sup>18+</sup> 2804 2805clone(): Promise\<PixelMap> 2806 2807拷贝一份当前Pixelmap对象，使用Promise形式返回。 2808 2809**系统能力：**: SystemCapability.Multimedia.Image.Core 2810 2811**返回值：** 2812 2813| 类型 | 说明 | 2814| -------------------------------- | --------------------------- | 2815| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。| 2816 2817**错误码：** 2818 2819以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2820 2821| 错误码ID | 错误信息 | 2822| ------- | --------------------------------------------| 2823| 501 | Resource unavailable. | 2824| 62980102 | Image malloc abnormal. This status code is thrown when an error occurs during the process of copying data. | 2825| 62980103 | Image YUV And ASTC types are not supported. | 2826| 62980104 | Image initialization abnormal. This status code is thrown when an error occurs during the process of createing empty pixelmap. | 2827| 62980106 | The image data is to large. This status code is thrown when an error occurs during the process of checking size. | 2828 2829**示例：** 2830 2831```ts 2832import { BusinessError } from '@kit.BasicServicesKit'; 2833 2834async function Demo() { 2835 if (pixelMap != undefined) { 2836 pixelMap.clone().then((clonePixelMap: image.PixelMap) => { 2837 console.info('Succeeded clone pixelmap.'); 2838 }).catch((error: BusinessError) => { 2839 console.error(`Failed to clone pixelmap. code is ${error.code}, message is ${error.message}`); 2840 }) 2841 } 2842} 2843``` 2844 2845### cloneSync<sup>18+</sup> 2846 2847cloneSync(): PixelMap 2848 2849拷贝一份当前Pixelmap对象, 同步返回结果。 2850 2851**系统能力：**: SystemCapability.Multimedia.Image.Core 2852 2853**返回值：** 2854 2855| 类型 | 说明 | 2856| -------------------------------- | --------------------------- | 2857| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2858 2859**错误码：** 2860 2861以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2862 2863| 错误码ID | 错误信息 | 2864| ------- | --------------------------------------------| 2865| 501 | Resource unavailable. | 2866| 62980102 | Image malloc abnormal. This status code is thrown when an error occurs during the process of copying data. | 2867| 62980103 | Image YUV And ASTC types are not supported. | 2868| 62980104 | Image initialization abnormal. This status code is thrown when an error occurs during the process of createing empty pixelmap. | 2869| 62980106 | The image data is to large. This status code is thrown when an error occurs during the process of checking size. | 2870 2871**示例：** 2872 2873```ts 2874import { BusinessError } from '@kit.BasicServicesKit'; 2875 2876async function Demo(pixelMap: image.PixelMap) { 2877 if (pixelMap != undefined) { 2878 try { 2879 let clonedPixelMap = pixelMap.cloneSync(); 2880 } catch(e) { 2881 let error = e as BusinessError; 2882 console.error(`clone pixelmap error. code is ${error.code}, message is ${error.message}`); 2883 } 2884 } 2885} 2886``` 2887 2888### translate<sup>9+</sup> 2889 2890translate(x: number, y: number, callback: AsyncCallback\<void>): void 2891 2892根据输入的坐标对图片进行位置变换，使用callback形式返回。 2893 2894translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2895 2896**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2897 2898**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2899 2900**系统能力：** SystemCapability.Multimedia.Image.Core 2901 2902**参数：** 2903 2904| 参数名 | 类型 | 必填 | 说明 | 2905| -------- | -------------------- | ---- | ----------------------------- | 2906| x | number | 是 | 区域横坐标。单位：像素。 | 2907| y | number | 是 | 区域纵坐标。单位：像素。 | 2908| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行位置变换成功，err为undefined，否则为错误对象。| 2909 2910**示例：** 2911 2912```ts 2913import { BusinessError } from '@kit.BasicServicesKit'; 2914 2915async function Translate() { 2916 let translateX: number = 50.0; 2917 let translateY: number = 10.0; 2918 if (pixelMap != undefined) { 2919 pixelMap.translate(translateX, translateY, (err: BusinessError) => { 2920 if (err) { 2921 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 2922 return; 2923 } else { 2924 console.info("Succeeded in translating pixelmap."); 2925 } 2926 }) 2927 } 2928} 2929``` 2930 2931### translate<sup>9+</sup> 2932 2933translate(x: number, y: number): Promise\<void> 2934 2935根据输入的坐标对图片进行位置变换，使用Promise形式返回。 2936 2937translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2938 2939**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2940 2941**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2942 2943**系统能力：** SystemCapability.Multimedia.Image.Core 2944 2945**参数：** 2946 2947| 参数名 | 类型 | 必填 | 说明 | 2948| ------ | ------ | ---- | ----------- | 2949| x | number | 是 | 区域横坐标。单位：像素。 | 2950| y | number | 是 | 区域纵坐标。单位：像素。 | 2951 2952**返回值：** 2953 2954| 类型 | 说明 | 2955| -------------- | --------------------------- | 2956| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2957 2958**示例：** 2959 2960```ts 2961import { BusinessError } from '@kit.BasicServicesKit'; 2962 2963async function Translate() { 2964 let translateX: number = 50.0; 2965 let translateY: number = 10.0; 2966 if (pixelMap != undefined) { 2967 pixelMap.translate(translateX, translateY).then(() => { 2968 console.info('Succeeded in translating pixelmap.'); 2969 }).catch((err: BusinessError) => { 2970 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 2971 }) 2972 } 2973} 2974``` 2975 2976### translateSync<sup>12+</sup> 2977 2978translateSync(x: number, y: number): void 2979 2980根据输入的坐标对图片进行位置变换，同步返回结果。 2981 2982translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2983 2984**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2985 2986**系统能力：** SystemCapability.Multimedia.Image.Core 2987 2988**参数：** 2989 2990| 参数名 | 类型 | 必填 | 说明 | 2991| -------- | -------------------- | ---- | ------------------------------- | 2992| x | number | 是 | 区域横坐标。单位：像素。 | 2993| y | number | 是 | 区域纵坐标。单位：像素。 | 2994 2995**错误码：** 2996 2997以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2998 2999| 错误码ID | 错误信息 | 3000| ------- | --------------------------------------------| 3001| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3002| 501 | Resource Unavailable | 3003 3004**示例：** 3005 3006```ts 3007import { BusinessError } from '@kit.BasicServicesKit'; 3008 3009async function TranslateSync() { 3010 let translateX : number = 50.0; 3011 let translateY : number = 10.0; 3012 if (pixelMap != undefined) { 3013 pixelMap.translateSync(translateX, translateY); 3014 } 3015} 3016``` 3017 3018### rotate<sup>9+</sup> 3019 3020rotate(angle: number, callback: AsyncCallback\<void>): void 3021 3022根据输入的角度对图片进行旋转，使用callback形式返回。 3023 3024> **说明：** 3025> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 3026> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 3027 3028**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3029 3030**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3031 3032**系统能力：** SystemCapability.Multimedia.Image.Core 3033 3034**参数：** 3035 3036| 参数名 | 类型 | 必填 | 说明 | 3037| -------- | -------------------- | ---- | ----------------------------- | 3038| angle | number | 是 | 图片旋转的角度。 | 3039| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行旋转成功，err为undefined，否则为错误对象。| 3040 3041**示例：** 3042 3043```ts 3044import { BusinessError } from '@kit.BasicServicesKit'; 3045 3046async function Rotate() { 3047 let angle: number = 90.0; 3048 if (pixelMap != undefined) { 3049 pixelMap.rotate(angle, (err: BusinessError) => { 3050 if (err) { 3051 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 3052 return; 3053 } else { 3054 console.info("Succeeded in rotating pixelmap."); 3055 } 3056 }) 3057 } 3058} 3059``` 3060 3061### rotate<sup>9+</sup> 3062 3063rotate(angle: number): Promise\<void> 3064 3065根据输入的角度对图片进行旋转，使用Promise形式返回。 3066 3067> **说明：** 3068> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 3069> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 3070 3071**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3072 3073**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3074 3075**系统能力：** SystemCapability.Multimedia.Image.Core 3076 3077**参数：** 3078 3079| 参数名 | 类型 | 必填 | 说明 | 3080| ------ | ------ | ---- | ----------------------------- | 3081| angle | number | 是 | 图片旋转的角度。 | 3082 3083**返回值：** 3084 3085| 类型 | 说明 | 3086| -------------- | --------------------------- | 3087| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3088 3089**示例：** 3090 3091```ts 3092import { BusinessError } from '@kit.BasicServicesKit'; 3093 3094async function Rotate() { 3095 let angle: number = 90.0; 3096 if (pixelMap != undefined) { 3097 pixelMap.rotate(angle).then(() => { 3098 console.info('Succeeded in rotating pixelmap.'); 3099 }).catch((err: BusinessError) => { 3100 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 3101 }) 3102 } 3103} 3104``` 3105 3106### rotateSync<sup>12+</sup> 3107 3108rotateSync(angle: number): void 3109 3110根据输入的角度对图片进行旋转，同步返回结果。 3111 3112> **说明：** 3113> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 3114> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 3115 3116**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3117 3118**系统能力：** SystemCapability.Multimedia.Image.Core 3119 3120**参数：** 3121 3122| 参数名 | 类型 | 必填 | 说明 | 3123| -------- | -------------------- | ---- | ----------------------------- | 3124| angle | number | 是 | 图片旋转的角度。 | 3125 3126**错误码：** 3127 3128以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3129 3130| 错误码ID | 错误信息 | 3131| ------- | --------------------------------------------| 3132| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3133| 501 | Resource Unavailable | 3134 3135**示例：** 3136 3137```ts 3138import { BusinessError } from '@kit.BasicServicesKit'; 3139 3140async function RotateSync() { 3141 let angle : number = 90.0; 3142 if (pixelMap != undefined) { 3143 pixelMap.rotateSync(angle); 3144 } 3145} 3146``` 3147 3148### flip<sup>9+</sup> 3149 3150flip(horizontal: boolean, vertical: boolean, callback: AsyncCallback\<void>): void 3151 3152根据输入的条件对图片进行翻转，使用callback形式返回。 3153 3154**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3155 3156**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3157 3158**系统能力：** SystemCapability.Multimedia.Image.Core 3159 3160**参数：** 3161 3162| 参数名 | 类型 | 必填 | 说明 | 3163| ---------- | -------------------- | ---- | ----------------------------- | 3164| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 3165| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 3166| callback | AsyncCallback\<void> | 是 | 回调函数，当对图片翻转成功，err为undefined，否则为错误对象。| 3167 3168**示例：** 3169 3170```ts 3171import { BusinessError } from '@kit.BasicServicesKit'; 3172 3173async function Flip() { 3174 let horizontal: boolean = true; 3175 let vertical: boolean = false; 3176 if (pixelMap != undefined) { 3177 pixelMap.flip(horizontal, vertical, (err: BusinessError) => { 3178 if (err) { 3179 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 3180 return; 3181 } else { 3182 console.info("Succeeded in flipping pixelmap."); 3183 } 3184 }) 3185 } 3186} 3187``` 3188 3189### flip<sup>9+</sup> 3190 3191flip(horizontal: boolean, vertical: boolean): Promise\<void> 3192 3193根据输入的条件对图片进行翻转，使用Promise形式返回。 3194 3195**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3196 3197**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3198 3199**系统能力：** SystemCapability.Multimedia.Image.Core 3200 3201**参数：** 3202 3203| 参数名 | 类型 | 必填 | 说明 | 3204| ---------- | ------- | ---- | --------- | 3205| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 3206| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 3207 3208**返回值：** 3209 3210| 类型 | 说明 | 3211| -------------- | --------------------------- | 3212| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3213 3214**示例：** 3215 3216```ts 3217import { BusinessError } from '@kit.BasicServicesKit'; 3218 3219async function Flip() { 3220 let horizontal: boolean = true; 3221 let vertical: boolean = false; 3222 if (pixelMap != undefined) { 3223 pixelMap.flip(horizontal, vertical).then(() => { 3224 console.info('Succeeded in flipping pixelmap.'); 3225 }).catch((err: BusinessError) => { 3226 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 3227 }) 3228 } 3229} 3230``` 3231 3232### flipSync<sup>12+</sup> 3233 3234flipSync(horizontal: boolean, vertical: boolean): void 3235 3236根据输入的条件对图片进行翻转并同步返回结果。 3237 3238**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3239 3240**系统能力：** SystemCapability.Multimedia.Image.Core 3241 3242**参数：** 3243 3244| 参数名 | 类型 | 必填 | 说明 | 3245| ---------- | -------------------- | ---- | ----------------------------- | 3246| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 3247| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 3248 3249**错误码：** 3250 3251以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3252 3253| 错误码ID | 错误信息 | 3254| ------- | --------------------------------------------| 3255| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3256| 501 | Resource Unavailable | 3257 3258**示例：** 3259 3260```ts 3261import { BusinessError } from '@kit.BasicServicesKit'; 3262 3263async function FlipSync() { 3264 let horizontal : boolean = true; 3265 let vertical : boolean = false; 3266 if (pixelMap != undefined) { 3267 pixelMap.flipSync(horizontal, vertical); 3268 } 3269} 3270``` 3271 3272### crop<sup>9+</sup> 3273 3274crop(region: Region, callback: AsyncCallback\<void>): void 3275 3276根据输入的尺寸对图片进行裁剪，使用callback形式返回。 3277 3278**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3279 3280**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3281 3282**系统能力：** SystemCapability.Multimedia.Image.Core 3283 3284**参数：** 3285 3286| 参数名 | 类型 | 必填 | 说明 | 3287| -------- | -------------------- | ---- | ----------------------------- | 3288| region | [Region](#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 3289| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行裁剪成功，err为undefined，否则为错误对象。| 3290 3291**示例：** 3292 3293```ts 3294import { BusinessError } from '@kit.BasicServicesKit'; 3295 3296async function Crop() { 3297 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3298 if (pixelMap != undefined) { 3299 pixelMap.crop(region, (err: BusinessError) => { 3300 if (err) { 3301 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 3302 return; 3303 } else { 3304 console.info("Succeeded in cropping pixelmap."); 3305 } 3306 }) 3307 } 3308} 3309``` 3310 3311### crop<sup>9+</sup> 3312 3313crop(region: Region): Promise\<void> 3314 3315根据输入的尺寸对图片进行裁剪，使用Promise形式返回。 3316 3317**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3318 3319**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3320 3321**系统能力：** SystemCapability.Multimedia.Image.Core 3322 3323**参数：** 3324 3325| 参数名 | 类型 | 必填 | 说明 | 3326| ------ | ------------------ | ---- | ----------- | 3327| region | [Region](#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 3328 3329**返回值：** 3330 3331| 类型 | 说明 | 3332| -------------- | --------------------------- | 3333| Promise\<void> | Promise对象。无返回结果的Promise对象。| 3334 3335**示例：** 3336 3337```ts 3338import { BusinessError } from '@kit.BasicServicesKit'; 3339 3340async function Crop() { 3341 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3342 if (pixelMap != undefined) { 3343 pixelMap.crop(region).then(() => { 3344 console.info('Succeeded in cropping pixelmap.'); 3345 }).catch((err: BusinessError) => { 3346 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 3347 3348 }); 3349 } 3350} 3351``` 3352 3353### cropSync<sup>12+</sup> 3354 3355cropSync(region: Region): void 3356 3357根据输入的尺寸裁剪图片。 3358 3359**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3360 3361**系统能力：** SystemCapability.Multimedia.Image.Core 3362 3363**参数：** 3364 3365| 参数名 | 类型 | 必填 | 说明 | 3366| -------- | -------------------- | ---- | ----------------------------- | 3367| region | [Region](#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 3368 3369**错误码：** 3370 3371以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3372 3373| 错误码ID | 错误信息 | 3374| ------- | --------------------------------------------| 3375| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3376| 501 | Resource Unavailable | 3377 3378**示例：** 3379 3380```ts 3381import { BusinessError } from '@kit.BasicServicesKit'; 3382 3383async function CropSync() { 3384 let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3385 if (pixelMap != undefined) { 3386 pixelMap.cropSync(region); 3387 } 3388} 3389``` 3390 3391### getColorSpace<sup>10+</sup> 3392 3393getColorSpace(): colorSpaceManager.ColorSpaceManager 3394 3395获取图像广色域信息。 3396 3397**系统能力：** SystemCapability.Multimedia.Image.Core 3398 3399**返回值：** 3400 3401| 类型 | 说明 | 3402| ----------------------------------- | ---------------- | 3403| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 图像广色域信息。 | 3404 3405**错误码：** 3406 3407以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3408 3409| 错误码ID | 错误信息 | 3410| ------- | --------------------------------------------| 3411| 62980101| If the image data abnormal. | 3412| 62980103| If the image data unsupport. | 3413| 62980115| If the image parameter invalid. | 3414 3415**示例：** 3416 3417```ts 3418async function GetColorSpace() { 3419 if (pixelMap != undefined) { 3420 let csm = pixelMap.getColorSpace(); 3421 } 3422} 3423``` 3424 3425### setColorSpace<sup>10+</sup> 3426 3427setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void 3428 3429设置图像广色域信息。 3430 3431**系统能力：** SystemCapability.Multimedia.Image.Core 3432 3433**参数：** 3434 3435| 参数名 | 类型 | 必填 | 说明 | 3436| ---------- | ----------------------------------- | ---- | --------------- | 3437| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 图像广色域信息。| 3438 3439**错误码：** 3440 3441以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3442 3443| 错误码ID | 错误信息 | 3444| ------- | --------------------------------------------| 3445| 62980111| The image source data is incomplete. | 3446| 62980115| If the image parameter invalid. | 3447 3448**示例：** 3449 3450```ts 3451import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3452async function SetColorSpace() { 3453 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3454 let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3455 if (pixelMap != undefined) { 3456 pixelMap.setColorSpace(csm); 3457 } 3458} 3459``` 3460 3461### applyColorSpace<sup>11+</sup> 3462 3463applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager, callback: AsyncCallback\<void>): void 3464 3465根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用callback形式返回。 3466 3467**系统能力：** SystemCapability.Multimedia.Image.Core 3468 3469**参数：** 3470 3471| 参数名 | 类型 | 必填 | 说明 | 3472| -------- | -------------------- | ---- | ----------------------------- | 3473| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 3474| callback | AsyncCallback\<void> | 是 | 回调函数。当对图像像素颜色进行色彩空间转换成功，err为undefined，否则为错误对象。| 3475 3476**错误码：** 3477 3478以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3479 3480| 错误码ID | 错误信息 | 3481| ------- | ------------------------------------------| 3482| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3483| 62980104| Failed to initialize the internal object. | 3484| 62980108| Failed to convert the color space. | 3485| 62980115| Invalid image parameter. | 3486 3487**示例：** 3488 3489```ts 3490import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3491import { BusinessError } from '@kit.BasicServicesKit'; 3492 3493async function ApplyColorSpace() { 3494 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3495 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3496 if (pixelMap != undefined) { 3497 pixelMap.applyColorSpace(targetColorSpace, (error: BusinessError) => { 3498 if (error) { 3499 console.error(`Failed to apply color space for pixelmap object, error code is ${error}`); 3500 return; 3501 } else { 3502 console.info('Succeeded in applying color space for pixelmap object.'); 3503 } 3504 }) 3505 } 3506} 3507``` 3508 3509### applyColorSpace<sup>11+</sup> 3510 3511applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void> 3512 3513根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用Promise形式返回。 3514 3515**系统能力：** SystemCapability.Multimedia.Image.Core 3516 3517**参数：** 3518 3519| 参数名 | 类型 | 必填 | 说明 | 3520| ------ | ------------------ | ---- | ----------- | 3521| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 3522 3523**返回值：** 3524 3525| 类型 | 说明 | 3526| -------------- | --------------------------- | 3527| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3528 3529**错误码：** 3530 3531以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3532 3533| 错误码ID | 错误信息 | 3534| ------- | ------------------------------------------| 3535| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3536| 62980104| Failed to initialize the internal object. | 3537| 62980108| Failed to convert the color space. | 3538| 62980115| Invalid image parameter. | 3539 3540**示例：** 3541 3542```ts 3543import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3544import { BusinessError } from '@kit.BasicServicesKit'; 3545 3546async function ApplyColorSpace() { 3547 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3548 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3549 if (pixelMap != undefined) { 3550 pixelMap.applyColorSpace(targetColorSpace).then(() => { 3551 console.info('Succeeded in applying color space for pixelmap object.'); 3552 }).catch((error: BusinessError) => { 3553 console.error(`Failed to apply color space for pixelmap object, error code is ${error}`); 3554 }) 3555 } 3556} 3557``` 3558 3559### toSdr<sup>12+<sup> 3560 3561toSdr(): Promise\<void> 3562 3563将HDR的图像内容转换为SDR的图像内容，异步使用Promise形式返回。 3564 3565**系统能力：** SystemCapability.Multimedia.Image.Core 3566 3567**返回值：** 3568 3569| 类型 | 说明 | 3570| -------------- | --------------------------- | 3571| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3572 3573**错误码：** 3574 3575以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3576 3577| 错误码ID | 错误信息 | 3578| ------- | --------------------------------------------| 3579| 62980137 | Invalid image operation. | 3580 3581**示例：** 3582 3583<!--code_no_check--> 3584```ts 3585import image from '@ohos.multimedia.image'; 3586import resourceManager from '@ohos.resourceManager'; 3587import { BusinessError } from '@kit.BasicServicesKit'; 3588import { common } from '@kit.AbilityKit'; 3589 3590// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 3591let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 3592//此处'hdr.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3593let img = context.resourceManager.getMediaContentSync($r('app.media.hdr')); 3594let imageSource = image.createImageSource(img.buffer.slice(0)); 3595let decodingOptions: image.DecodingOptions = { 3596 desiredDynamicRange: image.DecodingDynamicRange.AUTO 3597}; 3598let pixelmap = imageSource.createPixelMapSync(decodingOptions); 3599if (pixelmap != undefined) { 3600 console.info('Succeeded in creating pixelMap object.'); 3601 pixelmap.toSdr().then(() => { 3602 let imageInfo = pixelmap.getImageInfoSync(); 3603 console.info("after toSdr ,imageInfo isHdr:" + imageInfo.isHdr); 3604 }).catch((err: BusinessError) => { 3605 console.error(`Failed to set sdr. code is ${err.code}, message is ${err.message}`); 3606 }); 3607} else { 3608 console.error('Failed to create pixelMap.'); 3609} 3610``` 3611 3612### getMetadata<sup>12+</sup> 3613 3614getMetadata(key: HdrMetadataKey): HdrMetadataValue 3615 3616从PixelMap中获取元数据。 3617 3618**系统能力：** SystemCapability.Multimedia.Image.Core 3619 3620**参数：** 3621 3622| 参数名 | 类型 | 必填 | 说明 | 3623| ------------- | -------------------------------- | ---- | ---------------- | 3624| key | [HdrMetadataKey](#hdrmetadatakey12) | 是 | HDR元数据的关键字，可用于查询对应值。 | 3625 3626**返回值：** 3627 3628| 类型 | 说明 | 3629| --------------------------------- | --------------------------------- | 3630| [HdrMetadataValue](#hdrmetadatavalue12) | 返回元数据的值。 | 3631 3632**错误码：** 3633 3634以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3635 3636| 错误码ID | 错误信息 | 3637| ------- | --------------------------------------------| 3638| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 3639| 501 | Resource unavailable. | 3640| 62980173 | The DMA memory does not exist. | 3641| 62980302 | Memory copy failed. Possibly caused by invalid metadata value. | 3642 3643**示例：** 3644 3645<!--code_no_check--> 3646```ts 3647import { BusinessError } from '@kit.BasicServicesKit'; 3648import { common } from '@kit.AbilityKit'; 3649import image from '@ohos.multimedia.image'; 3650 3651// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 3652let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 3653// 'app.media.test'需要替换为本地hdr图片。 3654let img = context.resourceManager.getMediaContentSync($r('app.media.test')); 3655let imageSource = image.createImageSource(img.buffer.slice(0)); 3656let decodingOptions: image.DecodingOptions = { 3657 desiredDynamicRange: image.DecodingDynamicRange.AUTO 3658}; 3659let pixelmap = imageSource.createPixelMapSync(decodingOptions); 3660if (pixelmap != undefined) { 3661 console.info('Succeeded in creating pixelMap object.'); 3662 try { 3663 let staticMetadata = pixelmap.getMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA); 3664 console.info("getmetadata:" + JSON.stringify(staticMetadata)); 3665 } catch (e) { 3666 console.error('pixelmap create failed' + e); 3667 } 3668} else { 3669 console.error('Failed to create pixelMap.'); 3670} 3671``` 3672 3673### setMetadata<sup>12+</sup> 3674 3675setMetadata(key: HdrMetadataKey, value: HdrMetadataValue): Promise\<void> 3676 3677设置PixelMap元数据。 3678 3679**系统能力：** SystemCapability.Multimedia.Image.Core 3680 3681**参数：** 3682 3683| 参数名 | 类型 | 必填 | 说明 | 3684| ------------- | -------------------------------- | ---- | ---------------- | 3685| key | [HdrMetadataKey](#hdrmetadatakey12) | 是 | HDR元数据的关键字，用于设置对应值。 | 3686| value | [HdrMetadataValue](#hdrmetadatavalue12) | 是 | 元数据的值。 | 3687 3688**返回值：** 3689 3690| 类型 | 说明 | 3691| -------------- | --------------------- | 3692| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3693 3694**错误码：** 3695 3696以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3697 3698| 错误码ID | 错误信息 | 3699| ------- | --------------------------------------------| 3700| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 3701| 501 | Resource unavailable. | 3702| 62980173 | The DMA memory does not exist. | 3703| 62980302 | Memory copy failed. Possibly caused by invalid metadata value. | 3704 3705**示例：** 3706 3707```ts 3708import image from '@ohos.multimedia.image'; 3709import { BusinessError } from '@kit.BasicServicesKit'; 3710 3711let staticMetadata: image.HdrStaticMetadata = { 3712 displayPrimariesX: [1.1, 1.1, 1.1], 3713 displayPrimariesY: [1.2, 1.2, 1.2], 3714 whitePointX: 1.1, 3715 whitePointY: 1.2, 3716 maxLuminance: 2.1, 3717 minLuminance: 1.0, 3718 maxContentLightLevel: 2.1, 3719 maxFrameAverageLightLevel: 2.1, 3720}; 3721const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 3722let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } }; 3723image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 3724 pixelMap.setMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA, staticMetadata).then(() => { 3725 console.info('Succeeded in setting pixelMap metadata.'); 3726 }).catch((error: BusinessError) => { 3727 console.error(`Failed to set the metadata.code ${error.code},message is ${error.message}`); 3728 }) 3729}).catch((error: BusinessError) => { 3730 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 3731}) 3732 3733``` 3734 3735### setTransferDetached<sup>12+<sup> 3736 3737setTransferDetached(detached: boolean): void 3738 3739pixelmap在跨线程传输时，断开原线程的引用。适用于需立即释放pixelmap的场景。 3740 3741**系统能力：** SystemCapability.Multimedia.Image.Core 3742 3743**参数：** 3744 3745| 参数名 | 类型 | 必填 | 说明 | 3746| ------- | ------------------ | ---- | ----------------------------- | 3747| detached | boolean | 是 | true表示断开原线程引用，false表示不断开原线程引用。 | 3748 3749**错误码：** 3750 3751以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3752 3753| 错误码ID | 错误信息 | 3754| ------- | --------------------------------------------| 3755| 501 | Resource Unavailable | 3756 3757**示例：** 3758 3759```ts 3760import { BusinessError } from '@kit.BasicServicesKit'; 3761import { common } from '@kit.AbilityKit'; 3762import image from '@ohos.multimedia.image'; 3763import taskpool from '@ohos.taskpool'; 3764 3765@Concurrent 3766// 子线程方法。 3767async function loadPixelMap(rawFileDescriptor: number): Promise<PixelMap> { 3768 // 创建imageSource。 3769 const imageSource = image.createImageSource(rawFileDescriptor); 3770 // 创建pixelMap。 3771 const pixelMap = imageSource.createPixelMapSync(); 3772 // 释放imageSource。 3773 imageSource.release(); 3774 // 使pixelMap在跨线程传输完成后，断开原线程的引用。 3775 pixelMap.setTransferDetached(true); 3776 // 返回pixelMap给主线程。 3777 return pixelMap; 3778} 3779 3780@Component 3781struct Demo { 3782 @State pixelMap: PixelMap | undefined = undefined; 3783 // 主线程方法。 3784 private loadImageFromThread(): void { 3785 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 3786 const resourceMgr = context.resourceManager; 3787 // 此处‘example.jpg’仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3788 resourceMgr.getRawFd('example.jpg').then(rawFileDescriptor => { 3789 taskpool.execute(loadPixelMap, rawFileDescriptor).then(pixelMap => { 3790 if (pixelMap) { 3791 this.pixelMap = pixelMap as PixelMap; 3792 console.log('Succeeded in creating pixelMap.'); 3793 // 主线程释放pixelMap。由于子线程返回pixelMap时已调用setTransferDetached，所以此处能够立即释放pixelMap。 3794 this.pixelMap.release(); 3795 } else { 3796 console.error('Failed to create pixelMap.'); 3797 } 3798 }); 3799 }); 3800 } 3801 build() { 3802 // ... 3803 } 3804} 3805``` 3806 3807### marshalling<sup>10+</sup> 3808 3809marshalling(sequence: rpc.MessageSequence): void 3810 3811将PixelMap序列化后写入MessageSequence。 3812 3813**系统能力：** SystemCapability.Multimedia.Image.Core 3814 3815**参数：** 3816 3817| 参数名 | 类型 | 必填 | 说明 | 3818| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 3819| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 3820 3821**错误码：** 3822 3823以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3824 3825| 错误码ID | 错误信息 | 3826| ------- | --------------------------------------------| 3827| 62980115 | Invalid image parameter. | 3828| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory. | 3829 3830**示例：** 3831 3832```ts 3833import { image } from '@kit.ImageKit'; 3834import { rpc } from '@kit.IPCKit'; 3835 3836class MySequence implements rpc.Parcelable { 3837 pixel_map: image.PixelMap; 3838 constructor(conPixelMap : image.PixelMap) { 3839 this.pixel_map = conPixelMap; 3840 } 3841 marshalling(messageSequence : rpc.MessageSequence) { 3842 this.pixel_map.marshalling(messageSequence); 3843 console.info('marshalling'); 3844 return true; 3845 } 3846 unmarshalling(messageSequence : rpc.MessageSequence) { 3847 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: image.PixelMap) => { 3848 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: image.PixelMap) => { 3849 this.pixel_map = pixelMap; 3850 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 3851 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 3852 }) 3853 }) 3854 }); 3855 return true; 3856 } 3857} 3858async function Marshalling() { 3859 const color: ArrayBuffer = new ArrayBuffer(96); 3860 let bufferArr: Uint8Array = new Uint8Array(color); 3861 for (let i = 0; i < bufferArr.length; i++) { 3862 bufferArr[i] = 0x80; 3863 } 3864 let opts: image.InitializationOptions = { 3865 editable: true, 3866 pixelFormat: image.PixelMapFormat.BGRA_8888, 3867 size: { height: 4, width: 6 }, 3868 alphaType: image.AlphaType.UNPREMUL 3869 } 3870 let pixelMap: image.PixelMap | undefined = undefined; 3871 image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 3872 pixelMap = srcPixelMap; 3873 }) 3874 if (pixelMap != undefined) { 3875 // 序列化。 3876 let parcelable: MySequence = new MySequence(pixelMap); 3877 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 3878 data.writeParcelable(parcelable); 3879 3880 // 反序列化 rpc获取到data。 3881 let ret: MySequence = new MySequence(pixelMap); 3882 data.readParcelable(ret); 3883 } 3884} 3885``` 3886 3887### unmarshalling<sup>10+</sup> 3888 3889unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap> 3890 3891从MessageSequence中获取PixelMap， 3892如需使用同步方式创建PixelMap可使用：[createPixelMapFromParcel](#imagecreatepixelmapfromparcel11)。 3893 3894**系统能力：** SystemCapability.Multimedia.Image.Core 3895 3896**参数：** 3897 3898| 参数名 | 类型 | 必填 | 说明 | 3899| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 3900| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 3901 3902**返回值：** 3903 3904| 类型 | 说明 | 3905| -------------------------------- | --------------------- | 3906| Promise\<[PixelMap](#pixelmap7)> |Promise对象，返回PixelMap。 | 3907 3908**错误码：** 3909 3910以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3911 3912| 错误码ID | 错误信息 | 3913| ------- | --------------------------------------------| 3914| 62980115 | Invalid image parameter. | 3915| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory. | 3916| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 3917 3918**示例：** 3919 3920```ts 3921import { image } from '@kit.ImageKit'; 3922import { rpc } from '@kit.IPCKit'; 3923 3924class MySequence implements rpc.Parcelable { 3925 pixel_map: image.PixelMap; 3926 constructor(conPixelMap: image.PixelMap) { 3927 this.pixel_map = conPixelMap; 3928 } 3929 marshalling(messageSequence: rpc.MessageSequence) { 3930 this.pixel_map.marshalling(messageSequence); 3931 console.info('marshalling'); 3932 return true; 3933 } 3934 unmarshalling(messageSequence: rpc.MessageSequence) { 3935 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : image.PixelMap) => { 3936 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : image.PixelMap) => { 3937 this.pixel_map = pixelMap; 3938 pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => { 3939 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 3940 }) 3941 }) 3942 }); 3943 return true; 3944 } 3945} 3946async function Unmarshalling() { 3947 const color: ArrayBuffer = new ArrayBuffer(96); 3948 let bufferArr: Uint8Array = new Uint8Array(color); 3949 for (let i = 0; i < bufferArr.length; i++) { 3950 bufferArr[i] = 0x80; 3951 } 3952 let opts: image.InitializationOptions = { 3953 editable: true, 3954 pixelFormat: image.PixelMapFormat.BGRA_8888, 3955 size: { height: 4, width: 6 }, 3956 alphaType: image.AlphaType.UNPREMUL 3957 } 3958 let pixelMap: image.PixelMap | undefined = undefined; 3959 image.createPixelMap(color, opts).then((srcPixelMap : image.PixelMap) => { 3960 pixelMap = srcPixelMap; 3961 }) 3962 if (pixelMap != undefined) { 3963 // 序列化。 3964 let parcelable: MySequence = new MySequence(pixelMap); 3965 let data : rpc.MessageSequence = rpc.MessageSequence.create(); 3966 data.writeParcelable(parcelable); 3967 3968 // 反序列化 rpc获取到data。 3969 let ret : MySequence = new MySequence(pixelMap); 3970 data.readParcelable(ret); 3971 } 3972} 3973``` 3974 3975### release<sup>7+</sup> 3976 3977release():Promise\<void> 3978 3979释放PixelMap对象，使用Promise形式返回释放结果。 3980 3981ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 3982 3983**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3984 3985**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3986 3987**系统能力：** SystemCapability.Multimedia.Image.Core 3988 3989**返回值：** 3990 3991| 类型 | 说明 | 3992| -------------- | ------------------------------- | 3993| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3994 3995**示例：** 3996 3997```ts 3998import { BusinessError } from '@kit.BasicServicesKit'; 3999 4000async function Release() { 4001 if (pixelMap != undefined) { 4002 pixelMap.release().then(() => { 4003 console.info('Succeeded in releasing pixelmap object.'); 4004 }).catch((error: BusinessError) => { 4005 console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`); 4006 }) 4007 } 4008} 4009``` 4010 4011### release<sup>7+</sup> 4012 4013release(callback: AsyncCallback\<void>): void 4014 4015释放PixelMap对象，使用callback形式返回释放结果。 4016 4017ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 4018 4019**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4020 4021**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4022 4023**系统能力：** SystemCapability.Multimedia.Image.Core 4024 4025**参数：** 4026 4027| 参数名 | 类型 | 必填 | 说明 | 4028| -------- | -------------------- | ---- | ------------------ | 4029| callback | AsyncCallback\<void> | 是 | 回调函数。当对PixelMap对象释放成功，err为undefined，否则为错误对象。 | 4030 4031**示例：** 4032 4033```ts 4034import { BusinessError } from '@kit.BasicServicesKit'; 4035 4036async function Release() { 4037 if (pixelMap != undefined) { 4038 pixelMap.release((err: BusinessError) => { 4039 if (err) { 4040 console.error(`Failed to release pixelmap object. code is ${err.code}, message is ${err.message}`); 4041 return; 4042 } else { 4043 console.info('Succeeded in releasing pixelmap object.'); 4044 } 4045 }) 4046 } 4047} 4048``` 4049 4050### convertPixelFormat<sup>12+</sup> 4051 4052convertPixelFormat(targetPixelFormat: PixelMapFormat): Promise\<void> 4053 4054YUV和RGB类型互转，目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转。 4055 4056从API18开始，可用于ASTC_4x4类型转为RGBA_8888类型，目前仅支持ASTC_4x4转为RGBA_8888。 4057 4058> **注意：** 4059> 仅在ASTC_4x4格式的图像需要进行像素访问时，建议调用此接口将ASTC_4x4类型转为RGBA_8888类型。由于使用ASTC_4x4反解为RGBA_8888时延较高，其余情况下不推荐使用。 4060 4061**系统能力：** SystemCapability.Multimedia.Image.Core 4062 4063**参数：** 4064 4065| 参数名 | 类型 | 必填 | 说明 | 4066| -------- | -------------------- | ---- | ------------------ | 4067| targetPixelFormat | [PixelMapFormat](#pixelmapformat7) | 是 | 目标像素格式，用于YUV和RGB类型互转，或者ASTC_4x4类型转为RGBA_8888类型。目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转，ASTC_4x4转为RGBA_8888。 | 4068 4069**返回值：** 4070 4071| 类型 | 说明 | 4072| -------------- | ------------------------------- | 4073| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4074 4075**错误码：** 4076 4077以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4078 4079| 错误码ID | 错误信息 | 4080| ------- | --------------------------------------------| 4081| 62980111 | The image source data is incomplete. | 4082| 62980115 | Invalid input parameter. | 4083| 62980178 | Failed to create the pixelmap. | 4084| 62980274 | The conversion failed | 4085| 62980276 | The type to be converted is an unsupported target pixel format| 4086 4087**示例：** 4088 4089```ts 4090import { BusinessError } from '@kit.BasicServicesKit'; 4091 4092if (pixelMap != undefined) { 4093 // 设置目标像素格式为NV12。 4094 let targetPixelFormat = image.PixelMapFormat.NV12; 4095 pixelMap.convertPixelFormat(targetPixelFormat).then(() => { 4096 // pixelMap转换成NV12格式成功。 4097 console.info('PixelMapFormat convert Succeeded'); 4098 }).catch((error: BusinessError) => { 4099 // pixelMap转换成NV12格式失败。 4100 console.error(`PixelMapFormat convert Failed. code is ${error.code}, message is ${error.message}`); 4101 }) 4102} 4103``` 4104 4105### setMemoryNameSync<sup>13+</sup> 4106 4107setMemoryNameSync(name: string): void 4108 4109设置PixelMap内存标识符。 4110 4111**系统能力：** SystemCapability.Multimedia.Image.Core 4112 4113**参数：** 4114 4115| 参数名 | 类型 | 必填 | 说明 | 4116| ------------- | -------------------------------- | ---- | ---------------- | 4117| name | string | 是 | pixelmap内存标识符，只允许DMA和ASHMEM内存形式的piexelmap设置，支持1-31位长度。 | 4118 4119**错误码：** 4120 4121以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4122 4123| 错误码ID | 错误信息 | 4124| ------- | --------------------------------------------| 4125| 401 | Parameter error. Possible causes: 1.The length of the input parameter is too long. 2.Parameter verification failed. | 4126| 501 | Resource unavailable. | 4127| 62980286 | Memory format not supported. | 4128 4129**示例：** 4130 4131```ts 4132import { BusinessError } from '@ohos.base'; 4133 4134async function SetMemoryNameSync() { 4135 if (pixelMap != undefined) { 4136 try { 4137 pixelMap.setMemoryNameSync("PixelMapName Test"); 4138 } catch(e) { 4139 let error = e as BusinessError; 4140 console.error(`setMemoryNameSync error. code is ${error.code}, message is ${error.message}`); 4141 } 4142 } 4143} 4144``` 4145 4146## image.createImageSource 4147 4148createImageSource(uri: string): ImageSource 4149 4150通过传入的uri创建ImageSource实例。 4151 4152 4153**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4154 4155**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4156 4157**参数：** 4158 4159| 参数名 | 类型 | 必填 | 说明 | 4160| ------ | ------ | ---- | ---------------------------------- | 4161| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng .heic<sup>12+</sup>（不同硬件设备支持情况不同） [.svg<sup>10+</sup>](#svg标签说明) .ico<sup>11+</sup>。 | 4162 4163**返回值：** 4164 4165| 类型 | 说明 | 4166| --------------------------- | -------------------------------------------- | 4167| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4168 4169**示例：** 4170 4171<!--code_no_check--> 4172```ts 4173import { common } from '@kit.AbilityKit'; 4174 4175// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4176let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4177//此处'test.jpg'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 4178const path: string = context.filesDir + "/test.jpg"; 4179const imageSourceApi: image.ImageSource = image.createImageSource(path); 4180``` 4181 4182## image.createImageSource<sup>9+</sup> 4183 4184createImageSource(uri: string, options: SourceOptions): ImageSource 4185 4186通过传入的uri创建ImageSource实例。 4187 4188**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4189 4190**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4191 4192**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4193 4194**参数：** 4195 4196| 参数名 | 类型 | 必填 | 说明 | 4197| ------- | ------------------------------- | ---- | ----------------------------------- | 4198| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng .heic<sup>12+</sup>（不同硬件设备支持情况不同）[.svg<sup>10+</sup>](#svg标签说明) .ico<sup>11+</sup>。 | 4199| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。| 4200 4201**返回值：** 4202 4203| 类型 | 说明 | 4204| --------------------------- | -------------------------------------------- | 4205| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4206 4207**示例：** 4208 4209<!--code_no_check--> 4210```ts 4211import { common } from '@kit.AbilityKit'; 4212 4213let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 4214// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4215let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4216//此处'test.png'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 4217const path: string = context.filesDir + "/test.png"; 4218let imageSourceApi: image.ImageSource = image.createImageSource(path, sourceOptions); 4219``` 4220 4221## image.createImageSource<sup>7+</sup> 4222 4223createImageSource(fd: number): ImageSource 4224 4225通过传入文件描述符来创建ImageSource实例。 4226 4227**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4228 4229**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4230 4231**参数：** 4232 4233| 参数名 | 类型 | 必填 | 说明 | 4234| ------ | ------ | ---- | ------------- | 4235| fd | number | 是 | 文件描述符fd。| 4236 4237**返回值：** 4238 4239| 类型 | 说明 | 4240| --------------------------- | -------------------------------------------- | 4241| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4242 4243**示例：** 4244 4245<!--code_no_check--> 4246```ts 4247import { fileIo as fs } from '@kit.CoreFileKit'; 4248import { common } from '@kit.AbilityKit'; 4249 4250// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4251let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4252//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 4253let filePath: string = context.filesDir + "/test.jpg"; 4254let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 4255const imageSourceApi: image.ImageSource = image.createImageSource(file.fd); 4256``` 4257 4258## image.createImageSource<sup>9+</sup> 4259 4260createImageSource(fd: number, options: SourceOptions): ImageSource 4261 4262通过传入文件描述符来创建ImageSource实例。 4263 4264**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4265 4266**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4267 4268**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4269 4270**参数：** 4271 4272| 参数名 | 类型 | 必填 | 说明 | 4273| ------- | ------------------------------- | ---- | ----------------------------------- | 4274| fd | number | 是 | 文件描述符fd。 | 4275| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。| 4276 4277**返回值：** 4278 4279| 类型 | 说明 | 4280| --------------------------- | -------------------------------------------- | 4281| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4282 4283**示例：** 4284 4285<!--code_no_check--> 4286```ts 4287import { fileIo as fs } from '@kit.CoreFileKit'; 4288import { common } from '@kit.AbilityKit'; 4289 4290let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 4291// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4292let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4293//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4294const filePath: string = context.filesDir + "/test.jpg"; 4295let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 4296const imageSourceApi: image.ImageSource = image.createImageSource(file.fd, sourceOptions); 4297``` 4298 4299## image.createImageSource<sup>9+</sup> 4300 4301createImageSource(buf: ArrayBuffer): ImageSource 4302 4303通过缓冲区创建ImageSource实例。buf数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用[image.createPixelMapSync](#createpixelmapsync12)这一类接口。 4304 4305**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4306 4307**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4308 4309**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4310 4311**参数：** 4312 4313| 参数名 | 类型 | 必填 | 说明 | 4314| ------ | ----------- | ---- | ---------------- | 4315| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 4316 4317**返回值：** 4318 4319| 类型 | 说明 | 4320| --------------------------- | -------------------------------------------- | 4321| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4322 4323 4324**示例：** 4325 4326```ts 4327const buf: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 4328const imageSourceApi: image.ImageSource = image.createImageSource(buf); 4329``` 4330 4331## image.createImageSource<sup>9+</sup> 4332 4333createImageSource(buf: ArrayBuffer, options: SourceOptions): ImageSource 4334 4335通过缓冲区创建ImageSource实例。buf数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用[image.createPixelMapSync](#createpixelmapsync12)这一类接口。 4336 4337**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4338 4339**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4340 4341**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4342 4343**参数：** 4344 4345| 参数名 | 类型 | 必填 | 说明 | 4346| ------ | -------------------------------- | ---- | ------------------------------------ | 4347| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 4348| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4349 4350**返回值：** 4351 4352| 类型 | 说明 | 4353| --------------------------- | -------------------------------------------- | 4354| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4355 4356**示例：** 4357 4358```ts 4359const data: ArrayBuffer = new ArrayBuffer(112); 4360let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 4361const imageSourceApi: image.ImageSource = image.createImageSource(data, sourceOptions); 4362``` 4363 4364## image.createImageSource<sup>11+</sup> 4365 4366createImageSource(rawfile: resourceManager.RawFileDescriptor, options?: SourceOptions): ImageSource 4367 4368通过图像资源文件的RawFileDescriptor创建ImageSource实例。 4369 4370**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4371 4372**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4373 4374**参数：** 4375 4376| 参数名 | 类型 | 必填 | 说明 | 4377| ------ | -------------------------------- | ---- | ------------------------------------ | 4378| rawfile | [resourceManager.RawFileDescriptor](../apis-localization-kit/js-apis-resource-manager.md#rawfiledescriptor9) | 是 | 图像资源文件的RawFileDescriptor。 | 4379| options | [SourceOptions](#sourceoptions9) | 否 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4380 4381**返回值：** 4382 4383| 类型 | 说明 | 4384| --------------------------- | -------------------------------------------- | 4385| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4386 4387**示例：** 4388 4389<!--code_no_check--> 4390```ts 4391import { resourceManager } from '@kit.LocalizationKit'; 4392import { common } from '@kit.AbilityKit'; 4393 4394// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4395let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4396// 获取resourceManager资源管理器。 4397const resourceMgr: resourceManager.ResourceManager = context.resourceManager; 4398//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4399resourceMgr.getRawFd('test.jpg').then((rawFileDescriptor: resourceManager.RawFileDescriptor) => { 4400 const imageSourceApi: image.ImageSource = image.createImageSource(rawFileDescriptor); 4401}).catch((error: BusinessError) => { 4402 console.error(`Failed to get RawFileDescriptor.code is ${error.code}, message is ${error.message}`); 4403}) 4404``` 4405 4406## image.CreateIncrementalSource<sup>9+</sup> 4407 4408CreateIncrementalSource(buf: ArrayBuffer): ImageSource 4409 4410通过缓冲区以增量的方式创建ImageSource实例，IncrementalSource不支持读写Exif信息。 4411 4412以增量方式创建的ImageSource实例，仅支持使用以下功能，同步、异步callback、异步Promise均支持。 4413- 获取图片信息：指定序号-[getImageInfo](#getimageinfo)、直接获取-[getImageInfo](#getimageinfo-1) 4414- 获取图片中给定索引处图像的指定属性键的值：[getImageProperty](#getimageproperty11) 4415- 批量获取图片中的指定属性键的值：[getImageProperties](#getimageproperties12) 4416- 更新增量数据：[updateData](#updatedata9) 4417- 创建PixelMap对象：通过图片解码参数创建-[createPixelMap](#createpixelmap7)、通过默认参数创建-[createPixelMap](#createpixelmap7-1) 、通过图片解码参数-[createPixelMap](#createpixelmap7-2) 4418- 释放ImageSource实例：[release](#release) 4419 4420**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4421 4422**参数：** 4423 4424| 参数名 | 类型 | 必填 | 说明 | 4425| ------- | ------------| ---- | ----------| 4426| buf | ArrayBuffer | 是 | 增量数据。| 4427 4428**返回值：** 4429 4430| 类型 | 说明 | 4431| --------------------------- | --------------------------------- | 4432| [ImageSource](#imagesource) | 返回ImageSource，失败时返回undefined。 | 4433 4434**示例：** 4435 4436<!--code_no_check--> 4437```ts 4438import { common } from '@kit.AbilityKit'; 4439 4440// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4441let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4442let imageArray = context.resourceManager.getMediaContentSync($r('app.media.startIcon')); // 获取图像资源。 4443// 此处'app.media.startIcon'仅作示例，请开发者自行替换，否则imageArray创建失败会导致后续无法正常执行。 4444let splitBuff1 = imageArray.slice(0, imageArray.byteLength / 2); // 分片。 4445let splitBuff2 = imageArray.slice(imageArray.byteLength / 2); 4446const imageSourceIncrementalSApi: image.ImageSource = image.CreateIncrementalSource(new ArrayBuffer(imageArray.byteLength)); 4447imageSourceIncrementalSApi.updateData(splitBuff1, false, 0, splitBuff1.byteLength).then(() => { 4448 imageSourceIncrementalSApi.updateData(splitBuff2, true, 0, splitBuff2.byteLength).then(() => { 4449 let pixelMap = imageSourceIncrementalSApi.createPixelMapSync(); 4450 let imageInfo = pixelMap.getImageInfoSync(); 4451 console.info('Succeeded in creating pixelMap'); 4452 }).catch((error : BusinessError) => { 4453 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4454 }) 4455}).catch((error : BusinessError) => { 4456 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4457}) 4458``` 4459 4460## image.CreateIncrementalSource<sup>9+</sup> 4461 4462CreateIncrementalSource(buf: ArrayBuffer, options?: SourceOptions): ImageSource 4463 4464通过缓冲区以增量的方式创建ImageSource实例，IncrementalSource不支持读写Exif信息。 4465 4466此接口支持的功能与[CreateIncrementalSource(buf: ArrayBuffer): ImageSource](#imagecreateincrementalsource9)所生成的实例支持的功能相同。 4467 4468**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4469 4470**参数：** 4471 4472| 参数名 | 类型 | 必填 | 说明 | 4473| ------- | ------------------------------- | ---- | ------------------------------------ | 4474| buf | ArrayBuffer | 是 | 增量数据。 | 4475| options | [SourceOptions](#sourceoptions9) | 否 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4476 4477**返回值：** 4478 4479| 类型 | 说明 | 4480| --------------------------- | --------------------------------- | 4481| [ImageSource](#imagesource) | 返回ImageSource，失败时返回undefined。 | 4482 4483**示例：** 4484 4485<!--code_no_check--> 4486```ts 4487import { common } from '@kit.AbilityKit'; 4488 4489// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4490let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4491let imageArray = context.resourceManager.getMediaContentSync($r('app.media.startIcon')) // 获取图像资源。 4492// 此处'app.media.startIcon'仅作示例，请开发者自行替换，否则imageArray创建失败会导致后续无法正常执行。 4493let splitBuff1 = imageArray.slice(0, imageArray.byteLength / 2); // 分片。 4494let splitBuff2 = imageArray.slice(imageArray.byteLength / 2); 4495let sourceOptions: image.SourceOptions = { sourceDensity: 120}; 4496 4497const imageSourceIncrementalSApi: image.ImageSource = image.CreateIncrementalSource(new ArrayBuffer(imageArray.byteLength), sourceOptions); 4498imageSourceIncrementalSApi.updateData(splitBuff1, false, 0, splitBuff1.byteLength).then(() => { 4499 imageSourceIncrementalSApi.updateData(splitBuff2, true, 0, splitBuff2.byteLength).then(() => { 4500 let pixelMap = imageSourceIncrementalSApi.createPixelMapSync(); 4501 let imageInfo = pixelMap.getImageInfoSync(); 4502 console.info('Succeeded in creating pixelMap'); 4503 }).catch((error : BusinessError) => { 4504 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4505 }) 4506}).catch((error : BusinessError) => { 4507 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4508}) 4509``` 4510 4511## ImageSource 4512 4513ImageSource类，用于获取图片相关信息。在调用ImageSource的方法前，需要先通过[createImageSource](#imagecreateimagesource)构建一个ImageSource实例。 4514 4515### 属性 4516 4517**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4518 4519| 名称 | 类型 | 只读 | 可选 | 说明 | 4520| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 4521| supportedFormats | Array\<string> | 是 | 否 | 支持的图片格式，包括：png，jpeg，bmp，gif，webp，dng，heic<sup>12+</sup>（不同硬件设备支持情况不同）。 | 4522 4523### getImageInfo 4524 4525getImageInfo(index: number, callback: AsyncCallback\<ImageInfo>): void 4526 4527获取指定序号的图片信息，使用callback形式返回图片信息。 4528 4529**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4530 4531**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4532 4533**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4534 4535**参数：** 4536 4537| 参数名 | 类型 | 必填 | 说明 | 4538| -------- | -------------------------------------- | ---- | ---------------------------------------- | 4539| index | number | 是 | 创建ImageSource时的序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。 | 4540| callback | AsyncCallback<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图片信息成功，err为undefined，data为获取到的图片信息；否则为错误对象。 | 4541 4542**示例：** 4543 4544```ts 4545import { BusinessError } from '@kit.BasicServicesKit'; 4546 4547imageSourceApi.getImageInfo(0, (error: BusinessError, imageInfo: image.ImageInfo) => { 4548 if (error) { 4549 console.error(`Failed to obtain the image information.code is ${error.code}, message is ${error.message}`); 4550 } else { 4551 console.info('Succeeded in obtaining the image information.'); 4552 } 4553}) 4554``` 4555 4556### getImageInfo 4557 4558getImageInfo(callback: AsyncCallback\<ImageInfo>): void 4559 4560获取图片信息，使用callback形式返回图片信息。 4561 4562**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4563 4564**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4565 4566**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4567 4568**参数：** 4569 4570| 参数名 | 类型 | 必填 | 说明 | 4571| -------- | -------------------------------------- | ---- | ---------------------------------------- | 4572| callback | AsyncCallback<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图片信息成功，err为undefined，data为获取到的图片信息；否则为错误对象。 | 4573 4574**示例：** 4575 4576```ts 4577import { BusinessError } from '@kit.BasicServicesKit'; 4578 4579imageSourceApi.getImageInfo((err: BusinessError, imageInfo: image.ImageInfo) => { 4580 if (err) { 4581 console.error(`Failed to obtain the image information.code is ${err.code}, message is ${err.message}`); 4582 } else { 4583 console.info('Succeeded in obtaining the image information.'); 4584 } 4585}) 4586``` 4587 4588### getImageInfo 4589 4590getImageInfo(index?: number): Promise\<ImageInfo> 4591 4592获取图片信息，使用Promise形式返回图片信息。 4593 4594**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4595 4596**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4597 4598**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4599 4600**参数：** 4601 4602| 参数名| 类型 | 必填 | 说明 | 4603| ----- | ------ | ---- | ------------------------------------- | 4604| index | number | 否 | 创建ImageSource时的序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。 | 4605 4606**返回值：** 4607 4608| 类型 | 说明 | 4609| -------------------------------- | ---------------------- | 4610| Promise<[ImageInfo](#imageinfo)> | Promise对象，返回获取到的图片信息。 | 4611 4612**示例：** 4613 4614```ts 4615import { BusinessError } from '@kit.BasicServicesKit'; 4616 4617imageSourceApi.getImageInfo(0) 4618 .then((imageInfo: image.ImageInfo) => { 4619 console.info('Succeeded in obtaining the image information.'); 4620 }).catch((error: BusinessError) => { 4621 console.error(`Failed to obtain the image information.code is ${error.code}, message is ${error.message}`); 4622 }) 4623``` 4624 4625### getImageInfoSync<sup>12+</sup> 4626 4627getImageInfoSync(index?: number): ImageInfo 4628 4629获取指定序号的图片信息，使用同步形式返回图片信息。 4630 4631**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4632 4633**参数：** 4634 4635| 参数名| 类型 | 必填 | 说明 | 4636| ----- | ------ | ---- | ------------------------------------- | 4637| index | number | 否 | 创建ImageSource时的序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。 | 4638 4639**返回值：** 4640 4641| 类型 | 说明 | 4642| -------------------------------- | ---------------------- | 4643| [ImageInfo](#imageinfo) | 同步返回获取到的图片信息。 | 4644 4645**示例：** 4646 4647<!--code_no_check--> 4648```ts 4649import { common } from '@kit.AbilityKit'; 4650import { image } from '@kit.ImageKit'; 4651 4652// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4653let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4654//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4655let filePath: string = context.filesDir + "/test.jpg"; 4656let imageSource = image.createImageSource(filePath); 4657let imageInfo = imageSource.getImageInfoSync(0); 4658if (imageInfo == undefined) { 4659 console.error('Failed to obtain the image information.'); 4660} else { 4661 console.info('Succeeded in obtaining the image information.'); 4662 console.info('imageInfo.size.height:' + imageInfo.size.height); 4663 console.info('imageInfo.size.width:' + imageInfo.size.width); 4664} 4665``` 4666 4667### getImageProperty<sup>11+</sup> 4668 4669getImageProperty(key:PropertyKey, options?: ImagePropertyOptions): Promise\<string> 4670 4671获取图片中给定索引处图像的指定属性键的值，用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4672 4673**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4674 4675**参数：** 4676 4677| 参数名 | 类型 | 必填 | 说明 | 4678| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4679| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4680| options | [ImagePropertyOptions](#imagepropertyoptions11) | 否 | 图片属性，包括图片序号与默认属性值。 | 4681 4682**返回值：** 4683 4684| 类型 | 说明 | 4685| ---------------- | ----------------------------------------------------------------- | 4686| Promise\<string> | Promise对象，返回图片属性值，如获取失败则返回属性默认值。 | 4687 4688**错误码：** 4689 4690以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4691 4692| 错误码ID | 错误信息 | 4693| ------- | --------------------------------------------| 4694| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4695| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 4696| 62980103 | The image data is not supported. | 4697| 62980110 | The image source data is incorrect. | 4698| 62980111 | The image source data is incomplete. | 4699| 62980112 | The image format does not match. | 4700| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 4701| 62980115 | Invalid image parameter. | 4702| 62980116| Failed to decode the image. | 4703| 62980118 | Failed to create the image plugin. | 4704| 62980122 | Failed to decode the image header. | 4705| 62980123| The image does not support EXIF decoding. | 4706| 62980135| The EXIF value is invalid. | 4707 4708**示例：** 4709 4710```ts 4711import { BusinessError } from '@kit.BasicServicesKit'; 4712 4713let options: image.ImagePropertyOptions = { index: 0, defaultValue: '9999' } 4714imageSourceApi.getImageProperty(image.PropertyKey.BITS_PER_SAMPLE, options) 4715.then((data: string) => { 4716 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4717}).catch((error: BusinessError) => { 4718 console.error('Failed to get the value of the specified attribute key of the image.'); 4719}) 4720``` 4721 4722### getImageProperty<sup>(deprecated)</sup> 4723 4724getImageProperty(key:string, options?: GetImagePropertyOptions): Promise\<string> 4725 4726获取图片中给定索引处图像的指定属性键的值，用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4727 4728> **说明：** 4729> 4730> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4731 4732**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4733 4734**参数：** 4735 4736| 参数名 | 类型 | 必填 | 说明 | 4737| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4738| key | string | 是 | 图片属性名。 | 4739| options | [GetImagePropertyOptions](#getimagepropertyoptionsdeprecated) | 否 | 图片属性，包括图片序号与默认属性值。 | 4740 4741**返回值：** 4742 4743| 类型 | 说明 | 4744| ---------------- | ----------------------------------------------------------------- | 4745| Promise\<string> | Promise对象，返回图片属性值，如获取失败则返回属性默认值。 | 4746 4747**示例：** 4748 4749```ts 4750import { BusinessError } from '@kit.BasicServicesKit'; 4751 4752imageSourceApi.getImageProperty("BitsPerSample") 4753 .then((data: string) => { 4754 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4755 }).catch((error: BusinessError) => { 4756 console.error('Failed to get the value of the specified attribute key of the image.'); 4757 }) 4758``` 4759 4760### getImageProperty<sup>(deprecated)</sup> 4761 4762getImageProperty(key:string, callback: AsyncCallback\<string>): void 4763 4764获取图片中给定索引处图像的指定属性键的值，用callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4765 4766> **说明：** 4767> 4768> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4769 4770**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4771 4772**参数：** 4773 4774| 参数名 | 类型 | 必填 | 说明 | 4775| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4776| key | string | 是 | 图片属性名。 | 4777| callback | AsyncCallback\<string> | 是 | 回调函数，当获取图片属性值成功，err为undefined，data为获取到的图片属性值；否则为错误对象。 | 4778 4779**示例：** 4780 4781```ts 4782import { BusinessError } from '@kit.BasicServicesKit'; 4783 4784imageSourceApi.getImageProperty("BitsPerSample", (error: BusinessError, data: string) => { 4785 if (error) { 4786 console.error('Failed to get the value of the specified attribute key of the image.'); 4787 } else { 4788 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4789 } 4790}) 4791``` 4792 4793### getImageProperty<sup>(deprecated)</sup> 4794 4795getImageProperty(key:string, options: GetImagePropertyOptions, callback: AsyncCallback\<string>): void 4796 4797获取图片指定属性键的值，callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4798 4799> **说明：** 4800> 4801> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4802 4803**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4804 4805**参数：** 4806 4807| 参数名 | 类型 | 必填 | 说明 | 4808| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------- | 4809| key | string | 是 | 图片属性名。 | 4810| options | [GetImagePropertyOptions](#getimagepropertyoptionsdeprecated) | 是 | 图片属性，包括图片序号与默认属性值。 | 4811| callback | AsyncCallback\<string> | 是 | 回调函数，当获取图片属性值成功，err为undefined，data为获取到的图片属性值；否则为错误对象。| 4812 4813**示例：** 4814 4815```ts 4816import { BusinessError } from '@kit.BasicServicesKit'; 4817 4818let property: image.GetImagePropertyOptions = { index: 0, defaultValue: '9999' } 4819imageSourceApi.getImageProperty("BitsPerSample", property, (error: BusinessError, data: string) => { 4820 if (error) { 4821 console.error('Failed to get the value of the specified attribute key of the image.'); 4822 } else { 4823 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4824 } 4825}) 4826``` 4827 4828### getImageProperties<sup>12+</sup> 4829 4830getImageProperties(key: Array<PropertyKey>): Promise<Record<PropertyKey, string|null>> 4831 4832批量获取图片中的指定属性键的值，用Promise形式返回结果。仅支持JPEG、PNG和HEIF（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4833 4834**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4835 4836**参数：** 4837 4838| 参数名 | 类型 | 必填 | 说明 | 4839| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4840| key | Array\<[PropertyKey](#propertykey7)> | 是 | 图片属性名的数组。 | 4841 4842**返回值：** 4843 4844| 类型 | 说明 | 4845| ---------------- | ----------------------------------------------------------------- | 4846| Promise\<Record<[PropertyKey](#propertykey7), string \| null>> | Promise对象，返回图片属性值，如获取失败则返回null。 | 4847 4848**错误码：** 4849 4850以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4851 4852| 错误码ID | 错误信息 | 4853| ------- | --------------------------------------------| 4854| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4855| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 4856| 62980110| The image source data is incorrect. | 4857| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 4858| 62980116| Failed to decode the image. | 4859 4860**示例：** 4861 4862```ts 4863import { image } from '@kit.ImageKit'; 4864import { BusinessError } from '@kit.BasicServicesKit'; 4865 4866let key = [image.PropertyKey.IMAGE_WIDTH, image.PropertyKey.IMAGE_LENGTH]; 4867imageSourceApi.getImageProperties(key).then((data) => { 4868 console.info(JSON.stringify(data)); 4869}).catch((err: BusinessError) => { 4870 console.error(JSON.stringify(err)); 4871}); 4872``` 4873 4874### getImagePropertySync<sup>20+</sup> 4875 4876getImagePropertySync(key:PropertyKey): string 4877 4878获取图片exif指定属性键的值，用String形式返回结果。 4879 4880>**说明：** 4881> 4882> 该方法仅支持JPEG、PNG和HEIF（不同硬件设备支持情况不同）文件，且需要包含exif信息。 4883> 4884> exif信息是图片的元数据，包含拍摄时间、相机型号、光圈、焦距、ISO等。 4885 4886 4887**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4888 4889**参数：** 4890 4891| 参数名 | 类型 | 必填 | 说明 | 4892| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4893| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4894 4895**返回值：** 4896 4897| 类型 | 说明 | 4898| ---------------- | ----------------------------------------------------------------- | 4899| string | 返回图片exif中指定属性键的值（如获取失败则返回属性默认值），各个数据值作用请参考[PropertyKey](#propertykey7)。 | 4900 4901**错误码：** 4902 4903以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4904| 错误码ID | 错误信息 | 4905| ------- | --------------------------------------------| 4906| 7700101 | Bad source. e.g.,1. Image has invalid width or height. 2. Image source incomplete. 3. Read image data failed. 4. Codec create failed.| 4907| 7700102 | Unsupported MIME type.| 4908| 7700202 | Unsupported metadata. For example, key is not supported.| 4909 4910**示例：** 4911 4912<!--code_no_check--> 4913```ts 4914import { image } from '@kit.ImageKit'; 4915import { common } from '@kit.AbilityKit'; 4916 4917// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 4918let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4919let resourceMgr = context.resourceManager; 4920if (resourceMgr == null) { 4921 return; 4922} 4923let fd = resourceMgr.getRawFdSync("example.jpg"); 4924 4925const imageSourceApi = image.createImageSource(fd); 4926console.info("getImagePropertySync"); 4927let bits_per_sample = imageSourceApi.getImagePropertySync(image.PropertyKey.BITS_PER_SAMPLE); 4928console.info("bits_per_sample : " + bits_per_sample); 4929``` 4930 4931### modifyImageProperty<sup>11+</sup> 4932 4933modifyImageProperty(key: PropertyKey, value: string): Promise\<void> 4934 4935通过指定的键修改图片属性的值，使用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4936 4937> **说明：** 4938> 4939> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4940 4941**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4942 4943**参数：** 4944 4945| 参数名 | 类型 | 必填 | 说明 | 4946| ------- | ------ | ---- | ------------ | 4947| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4948| value | string | 是 | 属性值。 | 4949 4950**返回值：** 4951 4952| 类型 | 说明 | 4953| -------------- | --------------------------- | 4954| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4955 4956**错误码：** 4957 4958以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4959 4960| 错误码ID | 错误信息 | 4961| ------- | --------------------------------------------| 4962| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 4963| 62980123| The image does not support EXIF decoding. | 4964| 62980133| The EXIF data is out of range. | 4965| 62980135| The EXIF value is invalid. | 4966| 62980146| The EXIF data failed to be written to the file. | 4967 4968**示例：** 4969 4970```ts 4971import { BusinessError } from '@kit.BasicServicesKit'; 4972 4973imageSourceApi.modifyImageProperty(image.PropertyKey.IMAGE_WIDTH, "120").then(() => { 4974 imageSourceApi.getImageProperty(image.PropertyKey.IMAGE_WIDTH).then((width: string) => { 4975 console.info(`ImageWidth is :${width}`); 4976 }).catch((error: BusinessError) => { 4977 console.error('Failed to get the Image Width.'); 4978 }) 4979}).catch((error: BusinessError) => { 4980 console.error('Failed to modify the Image Width'); 4981}) 4982``` 4983 4984### modifyImageProperty<sup>(deprecated)</sup> 4985 4986modifyImageProperty(key: string, value: string): Promise\<void> 4987 4988通过指定的键修改图片属性的值，使用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4989 4990> **说明：** 4991> 4992> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4993> 4994> 从API version 11开始不再维护，建议使用[modifyImageProperty](#modifyimageproperty11)代替。 4995 4996**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4997 4998**参数：** 4999 5000| 参数名 | 类型 | 必填 | 说明 | 5001| ------- | ------ | ---- | ------------ | 5002| key | string | 是 | 图片属性名。 | 5003| value | string | 是 | 属性值。 | 5004 5005**返回值：** 5006 5007| 类型 | 说明 | 5008| -------------- | --------------------------- | 5009| Promise\<void> | Promise对象。无返回结果的Promise对象。| 5010 5011**示例：** 5012 5013```ts 5014import { BusinessError } from '@kit.BasicServicesKit'; 5015 5016imageSourceApi.modifyImageProperty("ImageWidth", "120").then(() => { 5017 imageSourceApi.getImageProperty("ImageWidth").then((width: string) => { 5018 console.info(`ImageWidth is :${width}`); 5019 }).catch((error: BusinessError) => { 5020 console.error('Failed to get the Image Width.'); 5021 }) 5022}).catch((error: BusinessError) => { 5023 console.error('Failed to modify the Image Width'); 5024}) 5025``` 5026 5027### modifyImageProperty<sup>(deprecated)</sup> 5028 5029modifyImageProperty(key: string, value: string, callback: AsyncCallback\<void>): void 5030 5031通过指定的键修改图片属性的值，callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 5032 5033> **说明：** 5034> 5035> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 5036> 5037>从API version 11开始不再维护，建议使用[modifyImageProperty](#modifyimageproperty11)代替。 5038 5039**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5040 5041**参数：** 5042 5043| 参数名 | 类型 | 必填 | 说明 | 5044| -------- | ------------------- | ---- | ------------------------------ | 5045| key | string | 是 | 图片属性名。 | 5046| value | string | 是 | 属性值。 | 5047| callback | AsyncCallback\<void> | 是 | 回调函数，当修改图片属性值成功，err为undefined，否则为错误对象。 | 5048 5049**示例：** 5050 5051```ts 5052import { BusinessError } from '@kit.BasicServicesKit'; 5053 5054imageSourceApi.modifyImageProperty("ImageWidth", "120", (err: BusinessError) => { 5055 if (err) { 5056 console.error(`Failed to modify the Image Width.code is ${err.code}, message is ${err.message}`); 5057 } else { 5058 console.info('Succeeded in modifying the Image Width.'); 5059 } 5060}) 5061``` 5062 5063### modifyImageProperties<sup>12+</sup> 5064 5065modifyImageProperties(records: Record<PropertyKey, string|null>): Promise\<void> 5066 5067批量通过指定的键修改图片属性的值，使用Promise形式返回结果。仅支持JPEG、PNG和HEIF（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 5068 5069> **说明：** 5070> 5071> 调用modifyImageProperties修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperties会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 5072> 5073 5074**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5075 5076**参数：** 5077 5078| 参数名 | 类型 | 必填 | 说明 | 5079| ------- | ------ | ---- | ------------ | 5080| records | Record<[PropertyKey](#propertykey7), string \| null> | 是 | 包含图片属性名和属性值的数组。 | 5081 5082**返回值：** 5083 5084| 类型 | 说明 | 5085| -------------- | --------------------------- | 5086| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 5087 5088**错误码：** 5089 5090以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5091 5092| 错误码ID | 错误信息 | 5093| ------- | --------------------------------------------| 5094| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 5095| 62980123| The image does not support EXIF decoding. | 5096| 62980133| The EXIF data is out of range. | 5097| 62980135| The EXIF value is invalid. | 5098| 62980146| The EXIF data failed to be written to the file. | 5099 5100**示例：** 5101 5102```ts 5103import { image } from '@kit.ImageKit'; 5104import { BusinessError } from '@kit.BasicServicesKit'; 5105 5106let keyValues: Record<PropertyKey, string|null> = { 5107 [image.PropertyKey.IMAGE_WIDTH] : "1024", 5108 [image.PropertyKey.IMAGE_LENGTH] : "1024" 5109}; 5110let checkKey = [image.PropertyKey.IMAGE_WIDTH, image.PropertyKey.IMAGE_LENGTH]; 5111imageSourceApi.modifyImageProperties(keyValues).then(() => { 5112 imageSourceApi.getImageProperties(checkKey).then((data) => { 5113 console.info(JSON.stringify(data)); 5114 }).catch((err: BusinessError) => { 5115 console.error(JSON.stringify(err)); 5116 }); 5117}).catch((err: BusinessError) => { 5118 console.error(JSON.stringify(err)); 5119}); 5120``` 5121 5122### updateData<sup>9+</sup> 5123 5124updateData(buf: ArrayBuffer, isFinished: boolean, offset: number, length: number): Promise\<void> 5125 5126更新增量数据，使用Promise形式返回结果。 5127 5128**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5129 5130**参数：** 5131 5132| 参数名 | 类型 | 必填 | 说明 | 5133| ---------- | ----------- | ---- | ------------ | 5134| buf | ArrayBuffer | 是 | 存放增量数据的buffer。 | 5135| isFinished | boolean | 是 | true表示数据更新完成，当前buffer内存放最后一段数据；false表示数据还未更新完成，需要继续更新。| 5136| offset | number | 是 | 即当前buffer中的数据首地址，相对于整个图片文件首地址的偏移量。单位：字节。 | 5137| length | number | 是 | 当前buffer的长度。单位：字节。 | 5138 5139**返回值：** 5140 5141| 类型 | 说明 | 5142| -------------- | -------------------------- | 5143| Promise\<void> | Promise对象。无返回结果的Promise对象。| 5144 5145**示例：** 5146 5147```ts 5148import { BusinessError } from '@kit.BasicServicesKit'; 5149 5150const array: ArrayBuffer = new ArrayBuffer(100); 5151imageSourceApi.updateData(array, false, 0, 10).then(() => { 5152 console.info('Succeeded in updating data.'); 5153}).catch((err: BusinessError) => { 5154 console.error(`Failed to update data.code is ${err.code},message is ${err.message}`); 5155}) 5156``` 5157 5158 5159### updateData<sup>9+</sup> 5160 5161updateData(buf: ArrayBuffer, isFinished: boolean, offset: number, length: number, callback: AsyncCallback\<void>): void 5162 5163更新增量数据，callback形式返回结果。 5164 5165**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5166 5167**参数：** 5168 5169| 参数名 | 类型 | 必填 | 说明 | 5170| ---------- | ------------------- | ---- | -------------------- | 5171| buf | ArrayBuffer | 是 | 存放增量数据的buffer。 | 5172| isFinished | boolean | 是 | true表示数据更新完成，当前buffer内存放最后一段数据；false表示数据还未更新完成，需要继续更新。| 5173| offset | number | 是 | 即当前buffer中的数据首地址，相对于整个图片文件首地址的偏移量。单位：字节。 | 5174| length | number | 是 | 当前buffer的长度。单位：字节。 | 5175| callback | AsyncCallback\<void> | 是 | 回调函数，当更新增量数据成功，err为undefined，否则为错误对象。 | 5176 5177**示例：** 5178 5179```ts 5180import { BusinessError } from '@kit.BasicServicesKit'; 5181 5182const array: ArrayBuffer = new ArrayBuffer(100); 5183imageSourceApi.updateData(array, false, 0, 10, (err: BusinessError) => { 5184 if (err) { 5185 console.error(`Failed to update data.code is ${err.code},message is ${err.message}`); 5186 } else { 5187 console.info('Succeeded in updating data.'); 5188 } 5189}) 5190``` 5191 5192### createPicture<sup>13+</sup> 5193 5194createPicture(options?: DecodingOptionsForPicture): Promise\<Picture> 5195 5196通过图片解码参数创建Picture对象,使用Promise形式返回。 5197 5198**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5199 5200**参数：** 5201 5202| 参数名 | 类型 | 必填 | 说明 | 5203| ------- | ------------------------------------------------------ | ---- | ---------- | 5204| options | [DecodingOptionsForPicture](#decodingoptionsforpicture13) | 否 | 解码参数。 | 5205 5206**返回值：** 5207 5208| 类型 | 说明 | 5209| ---------------------------- | -------------------------- | 5210| Promise\<[Picture](#picture13)> | Promise对象，返回Picture。 | 5211 5212**错误码：** 5213 5214以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5215 5216| 错误码ID | 错误信息 | 5217| -------- | ------------------------------------------------------------ | 5218| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified.2.Incorrect parameter types; 3.Parameter verification failed. | 5219| 7700301 | Failed to decode image. | 5220 5221**示例：** 5222 5223```ts 5224import { image } from '@kit.ImageKit'; 5225 5226async function CreatePicture() { 5227 let options: image.DecodingOptionsForPicture = { 5228 desiredAuxiliaryPictures: [image.AuxiliaryPictureType.GAINMAP] //GAINMAP为需要解码的辅助图类型。 5229 }; 5230 let pictureObj: image.Picture = await imageSourceApi.createPicture(options); 5231 if (pictureObj != null) { 5232 console.info('Create picture succeeded'); 5233 } else { 5234 console.error('Create picture failed'); 5235 } 5236} 5237``` 5238 5239### createPixelMap<sup>7+</sup> 5240 5241createPixelMap(options?: DecodingOptions): Promise\<PixelMap> 5242 5243通过图片解码参数创建PixelMap对象。 5244 5245从API version 15开始，推荐使用[createPixelMapUsingAllocator](#createpixelmapusingallocator15)，该接口可以指定输出pixelMap的内存类型[AllocatorType](#allocatortype15)，详情请参考[申请图片解码内存(ArkTS)](../../media/image/image-allocator-type.md)。 5246 5247**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 5248 5249**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5250 5251**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5252 5253**参数：** 5254 5255| 参数名 | 类型 | 必填 | 说明 | 5256| ------- | ------------------------------------ | ---- | ---------- | 5257| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5258 5259**返回值：** 5260 5261| 类型 | 说明 | 5262| -------------------------------- | --------------------- | 5263| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 5264 5265**示例：** 5266 5267```ts 5268import { BusinessError } from '@kit.BasicServicesKit'; 5269 5270imageSourceApi.createPixelMap().then((pixelMap: image.PixelMap) => { 5271 console.info('Succeeded in creating pixelMap object through image decoding parameters.'); 5272}).catch((error: BusinessError) => { 5273 console.error('Failed to create pixelMap object through image decoding parameters.'); 5274}) 5275``` 5276 5277### createPixelMap<sup>7+</sup> 5278 5279createPixelMap(callback: AsyncCallback\<PixelMap>): void 5280 5281通过默认参数创建PixelMap对象，使用callback形式返回结果。 5282 5283从API version 15开始，推荐使用[createPixelMapUsingAllocator](#createpixelmapusingallocator15)，该接口可以指定输出pixelMap的内存类型[AllocatorType](#allocatortype15)，详情请参考[申请图片解码内存(ArkTS)](../../media/image/image-allocator-type.md)。 5284 5285**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 5286 5287**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5288 5289**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5290 5291**参数：** 5292 5293| 参数名 | 类型 | 必填 | 说明 | 5294| -------- | ------------------------------------- | ---- | -------------------------- | 5295| callback | AsyncCallback<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap对象成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 5296 5297**示例：** 5298 5299```ts 5300import { BusinessError } from '@kit.BasicServicesKit'; 5301 5302imageSourceApi.createPixelMap((err: BusinessError, pixelMap: image.PixelMap) => { 5303 if (err) { 5304 console.error(`Failed to create pixelMap.code is ${err.code},message is ${err.message}`); 5305 } else { 5306 console.info('Succeeded in creating pixelMap object.'); 5307 } 5308}) 5309``` 5310 5311### createPixelMap<sup>7+</sup> 5312 5313createPixelMap(options: DecodingOptions, callback: AsyncCallback\<PixelMap>): void 5314 5315通过图片解码参数创建PixelMap对象。 5316 5317从API version 15开始，推荐使用[createPixelMapUsingAllocator](#createpixelmapusingallocator15)，该接口可以指定输出pixelMap的内存类型[AllocatorType](#allocatortype15)，详情请参考[申请图片解码内存(ArkTS)](../../media/image/image-allocator-type.md)。 5318 5319**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 5320 5321**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5322 5323**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5324 5325**参数：** 5326 5327| 参数名 | 类型 | 必填 | 说明 | 5328| -------- | ------------------------------------- | ---- | -------------------------- | 5329| options | [DecodingOptions](#decodingoptions7) | 是 | 解码参数。 | 5330| callback | AsyncCallback<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap对象成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 5331 5332**示例：** 5333 5334```ts 5335import { BusinessError } from '@kit.BasicServicesKit'; 5336 5337let decodingOptions: image.DecodingOptions = { 5338 sampleSize: 1, 5339 editable: true, 5340 desiredSize: { width: 1, height: 2 }, 5341 rotate: 10, 5342 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5343 desiredRegion: { size: { width: 1, height: 2 }, x: 0, y: 0 }, 5344 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5345 index: 0 5346}; 5347imageSourceApi.createPixelMap(decodingOptions, (err: BusinessError, pixelMap: image.PixelMap) => { 5348 if (err) { 5349 console.error(`Failed to create pixelMap.code is ${err.code},message is ${err.message}`); 5350 } else { 5351 console.info('Succeeded in creating pixelMap object.'); 5352 } 5353}) 5354``` 5355 5356### createPixelMapSync<sup>12+</sup> 5357 5358createPixelMapSync(options?: DecodingOptions): PixelMap 5359 5360通过图片解码参数同步创建PixelMap对象。 5361 5362从API version 15开始，推荐使用[createPixelMapUsingAllocatorSync](#createpixelmapusingallocatorsync15)，该接口可以指定输出pixelMap的内存类型[AllocatorType](#allocatortype15)，详情请参考[申请图片解码内存(ArkTS)](../../media/image/image-allocator-type.md)。 5363 5364**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5365 5366**参数：** 5367 5368| 参数名 | 类型 | 必填 | 说明 | 5369| -------- | ------------------------------------- | ---- | -------------------------- | 5370| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5371 5372**返回值：** 5373 5374| 类型 | 说明 | 5375| -------------------------------- | --------------------- | 5376| [PixelMap](#pixelmap7) | 用于同步返回创建结果。 | 5377 5378**示例：** 5379 5380<!--code_no_check--> 5381```ts 5382import { common } from '@kit.AbilityKit'; 5383import { image } from '@kit.ImageKit'; 5384 5385// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 5386let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5387//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5388let filePath: string = context.filesDir + "/test.jpg"; 5389let imageSource = image.createImageSource(filePath); 5390let decodingOptions: image.DecodingOptions = { 5391 sampleSize: 1, 5392 editable: true, 5393 desiredSize: { width: 1, height: 2 }, 5394 rotate: 10, 5395 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5396 desiredRegion: { size: { width: 1, height: 2 }, x: 0, y: 0 }, 5397 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5398 index: 0 5399}; 5400let pixelmap = imageSource.createPixelMapSync(decodingOptions); 5401if (pixelmap != undefined) { 5402 console.info('Succeeded in creating pixelMap object.'); 5403} else { 5404 console.error('Failed to create pixelMap.'); 5405} 5406``` 5407 5408### createPixelMapList<sup>10+</sup> 5409 5410createPixelMapList(options?: DecodingOptions): Promise<Array\<PixelMap>> 5411 5412通过图片解码参数创建PixelMap数组。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5413 5414> **注意：** 5415> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5416 5417**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5418 5419**参数：** 5420 5421| 参数名 | 类型 | 必填 | 说明 | 5422| -------- | ------------------------------------- | ---- | -------------------------- | 5423| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5424 5425**返回值：** 5426 5427| 类型 | 说明 | 5428| -------------------------------- | --------------------- | 5429| Promise<Array<[PixelMap](#pixelmap7)>> | 异步返回PixeMap数组。 | 5430 5431**错误码：** 5432 5433以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5434 5435| 错误码ID | 错误信息 | 5436| ------- | --------------------------------------------| 5437| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5438| 62980099 | The shared memory data is abnormal. | 5439| 62980101 | The image data is abnormal. | 5440| 62980103| The image data is not supported. | 5441| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 5442| 62980109 | Failed to crop the image. | 5443| 62980110| The image source data is incorrect. | 5444| 62980111| The image source data is incomplete. | 5445| 62980112 | The image format does not match. | 5446| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5447| 62980115 | Invalid image parameter. | 5448| 62980116 | Failed to decode the image. | 5449| 62980118| Failed to create the image plugin. | 5450| 62980122 | Failed to decode the image header. | 5451| 62980137 | Invalid media operation. | 5452| 62980173 | The DMA memory does not exist. | 5453| 62980174 | The DMA memory data is abnormal. | 5454 5455**示例：** 5456 5457```ts 5458import { BusinessError } from '@kit.BasicServicesKit'; 5459 5460let decodeOpts: image.DecodingOptions = { 5461 sampleSize: 1, 5462 editable: true, 5463 desiredSize: { width: 198, height: 202 }, 5464 rotate: 0, 5465 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5466 index: 0, 5467}; 5468imageSourceApi.createPixelMapList(decodeOpts).then((pixelMapList: Array<image.PixelMap>) => { 5469 console.info('Succeeded in creating pixelMapList object.'); 5470}).catch((err: BusinessError) => { 5471 console.error(`Failed to create pixelMapList object, error code is ${err}`); 5472}) 5473``` 5474 5475### createPixelMapList<sup>10+</sup> 5476 5477createPixelMapList(callback: AsyncCallback<Array\<PixelMap>>): void 5478 5479通过默认参数创建PixelMap数组，使用callback形式返回结果。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5480 5481> **注意：** 5482> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5483 5484**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5485 5486**参数：** 5487 5488| 参数名 | 类型 | 必填 | 说明 | 5489| -------- | ------------------------------------- | ---- | -------------------------- | 5490| callback | AsyncCallback<Array<[PixelMap](#pixelmap7)>> | 是 | 回调函数，当创建PixelMap对象数组成功，err为undefined，data为获取到的PixelMap对象数组；否则为错误对象。 | 5491 5492**错误码：** 5493 5494以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5495 5496| 错误码ID | 错误信息 | 5497| ------- | --------------------------------------------| 5498| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5499| 62980099 | The shared memory data is abnormal. | 5500| 62980101 | The image data is abnormal. | 5501| 62980103 | The image data is not supported. | 5502| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 5503| 62980109 | Failed to crop the image. | 5504| 62980110 | The image source data is incorrect. | 5505| 62980111 | The image source data is incomplete. | 5506| 62980112 | The image format does not match. | 5507| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5508| 62980115 | Invalid image parameter. | 5509| 62980116 | Failed to decode the image. | 5510| 62980118 | Failed to create the image plugin. | 5511| 62980122 | Failed to decode the image header. | 5512| 62980137 | Invalid media operation. | 5513| 62980173 | The DMA memory does not exist. | 5514| 62980174 | The DMA memory data is abnormal. | 5515 5516**示例：** 5517 5518```ts 5519import { BusinessError } from '@kit.BasicServicesKit'; 5520 5521imageSourceApi.createPixelMapList((err: BusinessError, pixelMapList: Array<image.PixelMap>) => { 5522 if (err) { 5523 console.error(`Failed to create pixelMapList object, error code is ${err}`); 5524 } else { 5525 console.info('Succeeded in creating pixelMapList object.'); 5526 } 5527}) 5528``` 5529 5530### createPixelMapList<sup>10+</sup> 5531 5532createPixelMapList(options: DecodingOptions, callback: AsyncCallback<Array\<PixelMap>>): void 5533 5534通过图片解码参数创建PixelMap数组，使用callback形式返回结果。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5535 5536> **注意：** 5537> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5538 5539**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5540 5541**参数：** 5542 5543| 参数名 | 类型 | 必填 | 说明 | 5544| -------- | -------------------- | ---- | ---------------------------------- | 5545| options | [DecodingOptions](#decodingoptions7) | 是 | 解码参数。 | 5546| callback | AsyncCallback<Array<[PixelMap](#pixelmap7)>> | 是 | 回调函数，当创建PixelMap对象数组成功，err为undefined，data为获取到的PixelMap对象数组；否则为错误对象。 | 5547 5548**错误码：** 5549 5550以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5551 5552| 错误码ID | 错误信息 | 5553| ------- | --------------------------------------------| 5554| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5555| 62980099 | The shared memory data is abnormal. | 5556| 62980101 | The image data is abnormal. | 5557| 62980103 | The image data is not supported. | 5558| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 5559| 62980109 | Failed to crop the image. | 5560| 62980110 | The image source data is incorrect. | 5561| 62980111 | The image source data is incomplete. | 5562| 62980112 | The image format does not match. | 5563| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5564| 62980115 | Invalid image parameter. | 5565| 62980116 | Failed to decode the image. | 5566| 62980118 | Failed to create the image plugin. | 5567| 62980122 | Failed to decode the image header. | 5568| 62980137 | Invalid media operation. | 5569| 62980173 | The DMA memory does not exist. | 5570| 62980174 | The DMA memory data is abnormal. | 5571 5572**示例：** 5573 5574```ts 5575import { BusinessError } from '@kit.BasicServicesKit'; 5576 5577let decodeOpts: image.DecodingOptions = { 5578 sampleSize: 1, 5579 editable: true, 5580 desiredSize: { width: 198, height: 202 }, 5581 rotate: 0, 5582 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5583 index: 0, 5584}; 5585imageSourceApi.createPixelMapList(decodeOpts, (err: BusinessError, pixelMapList: Array<image.PixelMap>) => { 5586 if (err) { 5587 console.error(`Failed to create pixelMapList object, error code is ${err}`); 5588 } else { 5589 console.info('Succeeded in creating pixelMapList object.'); 5590 } 5591}) 5592``` 5593 5594### createPixelMapUsingAllocator<sup>15+</sup> 5595 5596createPixelMapUsingAllocator(options?: DecodingOptions, allocatorType?: AllocatorType): Promise\<PixelMap> 5597 5598使用指定的分配器根据图像解码参数异步创建PixelMap对象。使用Promise异步回调。接口使用详情请参考[申请图片解码内存(ArkTS)](../../media/image/image-allocator-type.md)。 5599 5600**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5601 5602**参数：** 5603 5604| 参数名 | 类型 | 必填 | 说明 | 5605| ------------- | ------------------------------------ | ---- | ------------------------ | 5606| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5607| allocatorType | [AllocatorType](#allocatortype15) | 否 | 用于图像解码的内存类型。默认值为AllocatorType.AUTO。 | 5608 5609**返回值：** 5610 5611| 类型 | 说明 | 5612| -------------------------------- | --------------------------- | 5613| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 5614 5615**错误码：** 5616 5617以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5618 5619| 错误码ID | 错误信息 | 5620| -------- | ------------------------------------------------------------ | 5621| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types;3.Parameter verification failed. | 5622| 7700101 | Bad source. e.g.,1. Image has invalid width or height. 2. Image source incomplete. 3. Read image data failed. 4. Codec create failed. | 5623| 7700102 | Unsupported mimetype. | 5624| 7700103 | Image too large. This status code is thrown when an error occurs during the process of checking size. | 5625| 7700201 | Unsupported allocator type, e.g., use share memory to decode a HDR image as only DMA supported hdr metadata. | 5626| 7700203 | Unsupported options, e.g., cannot convert image into desired pixel format. | 5627| 7700301 | Failed to decode image. | 5628| 7700302 | Failed to allocate memory. | 5629 5630**示例：** 5631 5632<!--code_no_check--> 5633```ts 5634import { common } from '@kit.AbilityKit'; 5635import image from '@ohos.multimedia.image'; 5636 5637// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 5638let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5639// 此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5640let filePath: string = context.filesDir + "/test.jpg"; 5641let imageSource = image.createImageSource(filePath); 5642let decodingOptions: image.DecodingOptions = { 5643 editable: true, 5644 desiredSize: { width: 3072, height: 4096 }, 5645 rotate: 10, 5646 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5647 desiredRegion: { size: { width: 3072, height: 4096 }, x: 0, y: 0 }, 5648 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5649 index: 0 5650}; 5651let pixelmap = imageSource.createPixelMapUsingAllocator(decodingOptions, image.AllocatorType.AUTO); 5652if (pixelmap != undefined) { 5653 console.info('Succeeded in creating pixelMap object.'); 5654} else { 5655 console.error('Failed to create pixelMap.'); 5656} 5657``` 5658 5659### createPixelMapUsingAllocatorSync<sup>15+</sup> 5660 5661createPixelMapUsingAllocatorSync(options?: DecodingOptions, allocatorType?: AllocatorType): PixelMap 5662 5663根据指定的分配器同步创建一个基于图像解码参数的PixelMap对象。接口使用详情请参考[申请图片解码内存(ArkTS)](../../media/image/image-allocator-type.md)。 5664 5665**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5666 5667**参数：** 5668 5669| 参数名 | 类型 | 必填 | 说明 | 5670| ------------- | ------------------------------------ | ---- | ------------------------ | 5671| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5672| allocatorType | [AllocatorType](#allocatortype15) | 否 | 用于图像解码的内存类型。默认值为AllocatorType.AUTO。 | 5673 5674**返回值：** 5675 5676| 类型 | 说明 | 5677| ---------------------- | ---------------------- | 5678| [PixelMap](#pixelmap7) | 用于同步返回创建结果。 | 5679 5680**错误码：** 5681 5682以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5683 5684| 错误码ID | 错误信息 | 5685| -------- | ------------------------------------------------------------ | 5686| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types;3.Parameter verification failed. | 5687| 7700101 | Bad source. e.g.,1. Image has invalid width or height. 2. Image source incomplete. 3. Read image data failed. 4. Codec create failed. | 5688| 7700102 | Unsupported mimetype. | 5689| 7700103 | Image too large. This status code is thrown when an error occurs during the process of checking size. | 5690| 7700201 | Unsupported allocator type, e.g., use share memory to decode a HDR image as only DMA supported hdr metadata. | 5691| 7700203 | Unsupported options, e.g., cannot convert image into desired pixel format. | 5692| 7700301 | Failed to decode image. | 5693| 7700302 | Failed to allocate memory. | 5694 5695**示例：** 5696 5697<!--code_no_check--> 5698```ts 5699import { common } from '@kit.AbilityKit'; 5700import image from '@ohos.multimedia.image'; 5701 5702// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 5703let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5704// 此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5705let filePath: string = context.filesDir + "/test.jpg"; 5706let imageSource = image.createImageSource(filePath); 5707let decodingOptions: image.DecodingOptions = { 5708 editable: true, 5709 desiredSize: { width: 3072, height: 4096 }, 5710 rotate: 10, 5711 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5712 desiredRegion: { size: { width: 3072, height: 4096 }, x: 0, y: 0 }, 5713 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5714 index: 0 5715}; 5716let pixelmap = imageSource.createPixelMapUsingAllocatorSync(decodingOptions, image.AllocatorType.AUTO); 5717if (pixelmap != undefined) { 5718 console.info('Succeeded in creating pixelMap object.'); 5719} else { 5720 console.error('Failed to create pixelMap.'); 5721} 5722``` 5723 5724### getDelayTimeList<sup>10+</sup> 5725 5726getDelayTimeList(callback: AsyncCallback<Array\<number>>): void 5727 5728获取图像延迟时间数组，使用callback形式返回结果。此接口仅用于gif图片和webp图片。 5729 5730**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5731 5732**参数：** 5733 5734| 参数名 | 类型 | 必填 | 说明 | 5735| -------- | -------------------- | ---- | ---------------------------------- | 5736| callback | AsyncCallback<Array\<number>> | 是 | 回调函数，当获取图像延迟时间数组成功，err为undefined，data为获取到的图像延时时间数组；否则为错误对象。 | 5737 5738**错误码：** 5739 5740以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5741 5742| 错误码ID | 错误信息 | 5743| ------- | --------------------------------------------| 5744| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5745| 62980110| The image source data is incorrect. | 5746| 62980111| The image source data is incomplete. | 5747| 62980112 | The image format does not match. | 5748| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5749| 62980115 | Invalid image parameter. | 5750| 62980116| Failed to decode the image. | 5751| 62980118| Failed to create the image plugin. | 5752| 62980122| Failed to decode the image header. | 5753| 62980137 | Invalid media operation. | 5754| 62980149 | Invalid MIME type for the image source. | 5755 5756**示例：** 5757 5758```ts 5759import { BusinessError } from '@kit.BasicServicesKit'; 5760 5761imageSourceApi.getDelayTimeList((err: BusinessError, delayTimes: Array<number>) => { 5762 if (err) { 5763 console.error(`Failed to get delayTimes object.code is ${err.code},message is ${err.message}`); 5764 } else { 5765 console.info('Succeeded in getting delayTimes object.'); 5766 } 5767}) 5768``` 5769 5770### getDelayTimeList<sup>10+</sup> 5771 5772getDelayTimeList(): Promise<Array\<number>> 5773 5774获取图像延迟时间数组，使用Promise形式返回结果。此接口仅用于gif图片和webp图片。 5775 5776**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5777 5778**返回值：** 5779 5780| 类型 | 说明 | 5781| -------------- | --------------------------- | 5782| Promise<Array\<number>> | Promise对象，返回延迟时间数组。 | 5783 5784**错误码：** 5785 5786以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5787 5788| 错误码ID | 错误信息 | 5789| ------- | --------------------------------------------| 5790| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5791| 62980110 | The image source data is incorrect. | 5792| 62980111 | The image source data is incomplete. | 5793| 62980112 | The image format does not match. | 5794| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5795| 62980115 | Invalid image parameter. | 5796| 62980116 | Failed to decode the image. | 5797| 62980118 | Failed to create the image plugin. | 5798| 62980122 | Failed to decode the image header. | 5799| 62980137 | Invalid media operation. | 5800| 62980149 | Invalid MIME type for the image source. | 5801 5802**示例：** 5803 5804```ts 5805import { BusinessError } from '@kit.BasicServicesKit'; 5806 5807imageSourceApi.getDelayTimeList().then((delayTimes: Array<number>) => { 5808 console.info('Succeeded in getting delayTimes object.'); 5809}).catch((err: BusinessError) => { 5810 console.error(`Failed to get delayTimes object.code is ${err.code},message is ${err.message}`); 5811}) 5812``` 5813 5814### getFrameCount<sup>10+</sup> 5815 5816getFrameCount(callback: AsyncCallback\<number>): void 5817 5818获取图像帧数，使用callback形式返回结果。 5819 5820**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5821 5822**参数：** 5823 5824| 参数名 | 类型 | 必填 | 说明 | 5825| -------- | -------------------- | ---- | ---------------------------------- | 5826| callback | AsyncCallback\<number> | 是 | 回调函数，当获取图像帧数成功，err为undefined，data为获取到的图像帧数；否则为错误对象。 | 5827 5828**错误码：** 5829 5830以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5831 5832| 错误码ID | 错误信息 | 5833| ------- | --------------------------------------------| 5834| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5835| 62980110| The image source data is incorrect. | 5836| 62980111| The image source data is incomplete. | 5837| 62980112| The image format does not match. | 5838| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5839| 62980115| Invalid image parameter. | 5840| 62980116| Failed to decode the image. | 5841| 62980118| Failed to create the image plugin. | 5842| 62980122| Failed to decode the image header. | 5843| 62980137| Invalid media operation. | 5844 5845**示例：** 5846 5847```ts 5848import { BusinessError } from '@kit.BasicServicesKit'; 5849 5850imageSourceApi.getFrameCount((err: BusinessError, frameCount: number) => { 5851 if (err) { 5852 console.error(`Failed to get frame count.code is ${err.code},message is ${err.message}`); 5853 } else { 5854 console.info('Succeeded in getting frame count.'); 5855 } 5856}) 5857``` 5858 5859### getFrameCount<sup>10+</sup> 5860 5861getFrameCount(): Promise\<number> 5862 5863获取图像帧数，使用Promise形式返回结果。 5864 5865**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5866 5867**返回值：** 5868 5869| 类型 | 说明 | 5870| -------------- | --------------------------- | 5871| Promise\<number> | Promise对象，返回图像帧数。 | 5872 5873**错误码：** 5874 5875以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5876 5877| 错误码ID | 错误信息 | 5878| ------- | --------------------------------------------| 5879| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5880| 62980110 | The image source data is incorrect. | 5881| 62980111 | The image source data is incomplete. | 5882| 62980112 | The image format does not match. | 5883| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 5884| 62980115 | Invalid image parameter. | 5885| 62980116 | Failed to decode the image. | 5886| 62980118 | Failed to create the image plugin. | 5887| 62980122 | Failed to decode the image header. | 5888| 62980137 | Invalid media operation. | 5889 5890**示例：** 5891 5892```ts 5893import { BusinessError } from '@kit.BasicServicesKit'; 5894 5895imageSourceApi.getFrameCount().then((frameCount: number) => { 5896 console.info('Succeeded in getting frame count.'); 5897}).catch((err: BusinessError) => { 5898 console.error(`Failed to get frame count.code is ${err.code},message is ${err.message}`); 5899}) 5900``` 5901 5902### getDisposalTypeList<sup>12+</sup> 5903 5904getDisposalTypeList(): Promise\<Array\<number>> 5905 5906获取图像帧过渡模式数组，使用Promise形式返回结果。此接口仅用于gif图片。 5907 5908**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5909 5910**返回值：** 5911 5912| 类型 | 说明 | 5913| -------------- | --------------------------- | 5914| Promise\<Array\<number>> | Promise对象，返回帧过渡模式数组。 | 5915 5916**错误码：** 5917 5918以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5919 5920| 错误码ID | 错误信息 | 5921| ------- | --------------------------------------------| 5922| 62980096 | Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 5923| 62980101 | The image data is abnormal. | 5924| 62980137 | Invalid media operation. | 5925| 62980149 | Invalid MIME type for the image source. | 5926 5927**示例：** 5928 5929```ts 5930import { BusinessError } from '@kit.BasicServicesKit'; 5931imageSourceApi.getDisposalTypeList().then((disposalTypes: Array<number>) => { 5932 console.info('Succeeded in getting disposalTypes object.'); 5933}).catch((err: BusinessError) => { 5934 console.error(`Failed to get disposalTypes object.code ${err.code},message is ${err.message}`); 5935}) 5936``` 5937 5938### release 5939 5940release(callback: AsyncCallback\<void>): void 5941 5942释放ImageSource实例，使用callback形式返回结果。 5943 5944ArkTS有内存回收机制，ImageSource对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5945 5946**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5947 5948**参数：** 5949 5950| 参数名 | 类型 | 必填 | 说明 | 5951| -------- | -------------------- | ---- | ---------------------------------- | 5952| callback | AsyncCallback\<void> | 是 | 回调函数，当资源释放成功，err为undefined，否则为错误对象。 | 5953 5954**示例：** 5955 5956```ts 5957import { BusinessError } from '@kit.BasicServicesKit'; 5958 5959imageSourceApi.release((err: BusinessError) => { 5960 if (err) { 5961 console.error(`Failed to release the image source instance.code ${err.code},message is ${err.message}`); 5962 } else { 5963 console.info('Succeeded in releasing the image source instance.'); 5964 } 5965}) 5966``` 5967 5968### release 5969 5970release(): Promise\<void> 5971 5972释放ImageSource实例，使用Promise形式返回结果。 5973 5974ArkTS有内存回收机制，ImageSource对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5975 5976**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5977 5978**返回值：** 5979 5980| 类型 | 说明 | 5981| -------------- | --------------------------- | 5982| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 5983 5984**示例：** 5985 5986```ts 5987import { BusinessError } from '@kit.BasicServicesKit'; 5988 5989imageSourceApi.release().then(() => { 5990 console.info('Succeeded in releasing the image source instance.'); 5991}).catch((error: BusinessError) => { 5992 console.error(`Failed to release the image source instance.code ${error.code},message is ${error.message}`); 5993}) 5994``` 5995 5996## image.getImageSourceSupportedFormats<sup>20+</sup> 5997 5998getImageSourceSupportedFormats(): string[] 5999 6000获取支持解码的图片格式，图片格式以mime type表示。 6001 6002**系统能力：** SystemCapability.Multimedia.Image.Core 6003 6004**返回值：** 6005 6006| 类型 | 说明 | 6007| -------- | ------------------------------------------ | 6008| string[] | 支持解码的图片格式（mime type）列表。 | 6009 6010**示例：** 6011 6012```ts 6013import { image } from '@kit.ImageKit'; 6014function GetImageSourceSupportedFormats() { 6015 let formats = image.getImageSourceSupportedFormats(); 6016 console.info('formats:', formats); 6017} 6018``` 6019 6020## image.createImagePacker 6021 6022createImagePacker(): ImagePacker 6023 6024创建ImagePacker实例。 6025 6026**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6027 6028**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6029 6030**返回值：** 6031 6032| 类型 | 说明 | 6033| --------------------------- | --------------------- | 6034| [ImagePacker](#imagepacker) | 返回ImagePacker实例。 | 6035 6036**示例：** 6037 6038```ts 6039const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6040``` 6041 6042## ImagePacker 6043 6044图片编码器类，用于图片压缩和编码。在调用ImagePacker的方法前，需要先通过[createImagePacker](#imagecreateimagepacker)构建一个ImagePacker实例，当前支持格式有：jpeg、webp、png、heif<sup>12+</sup>（不同硬件设备支持情况不同）。 6045 6046### 属性 6047 6048**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6049 6050| 名称 | 类型 | 只读 | 可选 | 说明 | 6051| ---------------- | -------------- | ---- | ---- | -------------------------- | 6052| supportedFormats | Array\<string> | 是 | 否 | 图片编码支持的格式 jpeg、webp、png、heic<sup>12+</sup>（不同硬件设备支持情况不同）。 | 6053 6054### packToData<sup>13+</sup> 6055 6056packToData(source: ImageSource, options: PackingOption): Promise\<ArrayBuffer> 6057 6058图片压缩或重新编码，使用Promise形式返回结果。 6059 6060**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 6061 6062**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6063 6064**参数：** 6065 6066| 参数名 | 类型 | 必填 | 说明 | 6067| ------ | ------------------------------- | ---- | -------------- | 6068| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6069| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6070 6071**错误码：** 6072 6073以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6074 6075| 错误码ID | 错误信息 | 6076| ------- | --------------------------------------------| 6077| 401 | If the parameter is invalid. | 6078| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 6079| 62980101 | The image data is abnormal. | 6080| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 6081| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 6082| 62980119 | Failed to encode the image. | 6083| 62980120 | Add pixelmap out of range. | 6084| 62980172 | Failed to encode icc. | 6085| 62980252 | Failed to create surface. | 6086 6087**返回值：** 6088 6089| 类型 | 说明 | 6090| ---------------------------- | --------------------------------------------- | 6091| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。 | 6092 6093**示例：** 6094 6095<!--code_no_check--> 6096```ts 6097import { common } from '@kit.AbilityKit'; 6098import { BusinessError } from '@kit.BasicServicesKit'; 6099 6100// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6101let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6102//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6103let filePath: string = context.filesDir + "/test.jpg"; 6104const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 6105let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6106const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6107imagePackerApi.packToData(imageSourceApi, packOpts) 6108 .then((data: ArrayBuffer) => { 6109 console.info('Succeeded in packing the image.'); 6110 }).catch((error: BusinessError) => { 6111 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 6112 }) 6113``` 6114 6115### packToData<sup>13+</sup> 6116 6117packToData(source: PixelMap, options: PackingOption): Promise\<ArrayBuffer> 6118 6119图片压缩或重新编码，使用Promise形式返回结果。 6120 6121> **注意：** 6122> 接口如果返回401错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6123 6124**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 6125 6126**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6127 6128**参数：** 6129 6130| 参数名 | 类型 | 必填 | 说明 | 6131| ------ | ------------------------------- | ---- | ------------------ | 6132| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap源。 | 6133| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6134 6135**返回值：** 6136 6137| 类型 | 说明 | 6138| --------------------- | -------------------------------------------- | 6139| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。| 6140 6141**错误码：** 6142 6143以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6144 6145| 错误码ID | 错误信息 | 6146| ------- | --------------------------------------------| 6147| 401 | If the parameter is invalid. | 6148| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 6149| 62980101 | The image data is abnormal. | 6150| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 6151| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 6152| 62980119 | Failed to encode the image. | 6153| 62980120 | Add pixelmap out of range. | 6154| 62980172 | Failed to encode icc. | 6155| 62980252 | Failed to create surface. | 6156 6157**示例：** 6158 6159```ts 6160import { BusinessError } from '@kit.BasicServicesKit'; 6161 6162const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6163let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 6164image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 6165 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6166 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6167 imagePackerApi.packToData(pixelMap, packOpts) 6168 .then((data: ArrayBuffer) => { 6169 console.info('Succeeded in packing the image.'); 6170 }).catch((error: BusinessError) => { 6171 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 6172 }) 6173}).catch((error: BusinessError) => { 6174 console.error(`Failed to create PixelMap.code ${error.code},message is ${error.message}`); 6175}) 6176``` 6177 6178### packing<sup>13+</sup> 6179 6180packing(picture: Picture, options: PackingOption): Promise\<ArrayBuffer> 6181 6182将图像压缩或重新编码，使用Promise形式返回结果。 6183 6184**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6185 6186**参数：** 6187 6188| 参数名 | 类型 | 必填 | 说明 | 6189| ---------------- | ---------------------------------------------------- | ---- | -------------------- | 6190| picture | [Picture](#picture13) | 是 | 编码的Picture对象。 | 6191| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6192 6193**返回值：** 6194 6195| 类型 | 说明 | 6196| --------------------- | ------------------------------------- | 6197| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。 | 6198 6199**错误码：** 6200 6201以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6202 6203| 错误码ID | 错误信息 | 6204| -------- | ------------------------------------------------------------ | 6205| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6206| 7800301 | Encode failed. | 6207 6208**示例：** 6209 6210```ts 6211import { BusinessError } from '@kit.BasicServicesKit'; 6212import { image } from '@kit.ImageKit'; 6213 6214async function Packing(context: Context) { 6215 const resourceMgr = context.resourceManager; 6216 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 6217 let ops: image.SourceOptions = { 6218 sourceDensity: 98, 6219 } 6220 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6221 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6222 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6223 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6224 let funcName = "Packing"; 6225 if (imagePackerApi != null) { 6226 let opts: image.PackingOption = { 6227 format: "image/jpeg", 6228 quality: 98, 6229 bufferSize: 10, 6230 desiredDynamicRange: image.PackingDynamicRange.AUTO, 6231 needsPackProperties: true}; 6232 await imagePackerApi.packing(pictureObj, opts).then((data: ArrayBuffer) => { 6233 console.info(funcName, 'Succeeded in packing the image.'+ data); 6234 }).catch((error: BusinessError) => { 6235 console.error(funcName, 'Failed to pack the image.code ${error.code},message is ${error.message}'); 6236 }); 6237 } 6238} 6239``` 6240 6241### packToDataFromPixelmapSequence<sup>18+</sup> 6242 6243packToDataFromPixelmapSequence(pixelmapSequence: Array\<PixelMap>, options: PackingOptionsForSequence): Promise\<ArrayBuffer> 6244 6245将多个PixelMap编码成GIF数据。使用Promise形式返回结果。 6246 6247**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6248 6249**参数：** 6250 6251| 参数名 | 类型 | 必填 | 说明 | 6252| ---------------- | --------------------------------------------------------- | ---- | ---------------------- | 6253| pixelmapSequence | Array\<[PixelMap](#pixelmap7)> | 是 | 待编码的PixelMap序列。 | 6254| options | [PackingOptionsForSequence](#packingoptionsforsequence18) | 是 | 动图编码参数。 | 6255 6256**返回值：** 6257 6258| 类型 | 说明 | 6259| --------------------- | ------------------------------- | 6260| Promise\<ArrayBuffer> | Promise对象，返回编码后的数据。 | 6261 6262**错误码：** 6263 6264以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 6265 6266| 错误码ID | 错误信息 | 6267| -------- | ------------------------------------------------------------ | 6268| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6269| 7800201 | Unsupported packing options. | 6270| 7800301 | Failed to encode image. | 6271 6272**示例：** 6273 6274<!--code_no_check--> 6275```ts 6276import { common } from '@kit.AbilityKit'; 6277import { BusinessError } from '@ohos.base'; 6278import image from "@ohos.multimedia.image"; 6279 6280// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6281let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6282const resourceMgr = context.resourceManager; 6283// 此处'moving_test.gif'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 6284const fileData = resourceMgr.getRawFileContent('moving_test.gif'); 6285const color = fileData.buffer; 6286let imageSource = image.createImageSource(color); 6287let pixelMapList = imageSource.createPixelMapList(); 6288let ops: image.PackingOptionsForSequence = { 6289 frameCount: 3, // 指定GIF编码中的帧数为3。 6290 delayTimeList: [10, 10, 10], // 指定GIF编码中3帧的延迟时间分别为100ms、100ms、100ms。 6291 disposalTypes: [3, 2, 3], // 指定GIF编码中3帧的帧过渡模式分别为3（恢复到之前的状态）、2（恢复背景色)、3(恢复到之前的状态)。 6292 loopCount: 0 // 指定GIF编码中循环次数为无限循环。 6293}; 6294let Packer = image.createImagePacker(); 6295Packer.packToDataFromPixelmapSequence(pixelMapList, ops) 6296 .then((data: ArrayBuffer) => { 6297 console.info('Succeeded in packing.'); 6298 }).catch((error: BusinessError) => { 6299 console.error('Failed to packing.'); 6300 }) 6301``` 6302 6303### packing<sup>(deprecated)</sup> 6304 6305packing(source: ImageSource, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 6306 6307图片压缩或重新编码，使用callback形式返回结果。 6308 6309> **说明：** 6310> 6311> 从API version 6开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6312 6313**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6314 6315**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6316 6317**参数：** 6318 6319| 参数名 | 类型 | 必填 | 说明 | 6320| -------- | ---------------------------------- | ---- | ---------------------------------- | 6321| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6322| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6323| callback | AsyncCallback\<ArrayBuffer> | 是 | 回调函数，当图片编码成功，err为undefined，data为获取到的压缩或编码数据；否则为错误对象。 | 6324 6325**示例：** 6326 6327<!--code_no_check--> 6328```ts 6329import { common } from '@kit.AbilityKit'; 6330import { BusinessError } from '@kit.BasicServicesKit'; 6331 6332// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6333let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6334//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6335let filePath: string = context.filesDir + "/test.jpg"; 6336const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 6337let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6338const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6339imagePackerApi.packing(imageSourceApi, packOpts, (err: BusinessError, data: ArrayBuffer) => { 6340 if (err) { 6341 console.error(`Failed to pack the image.code ${err.code},message is ${err.message}`); 6342 } else { 6343 console.info('Succeeded in packing the image.'); 6344 } 6345}) 6346``` 6347 6348### packing<sup>(deprecated)</sup> 6349 6350packing(source: ImageSource, option: PackingOption): Promise\<ArrayBuffer> 6351 6352图片压缩或重新编码，使用Promise形式返回结果。 6353 6354> **说明：** 6355> 6356> 从API version 6开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6357 6358**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6359 6360**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6361 6362**参数：** 6363 6364| 参数名 | 类型 | 必填 | 说明 | 6365| ------ | ------------------------------- | ---- | -------------- | 6366| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6367| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6368 6369**返回值：** 6370 6371| 类型 | 说明 | 6372| ---------------------------- | --------------------------------------------- | 6373| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。 | 6374 6375**示例：** 6376 6377<!--code_no_check--> 6378```ts 6379import { common } from '@kit.AbilityKit'; 6380import { BusinessError } from '@kit.BasicServicesKit'; 6381 6382// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6383let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6384//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6385let filePath: string = context.filesDir + "/test.jpg"; 6386const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 6387let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6388const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6389imagePackerApi.packing(imageSourceApi, packOpts) 6390 .then((data: ArrayBuffer) => { 6391 console.info('Succeeded in packing the image.'); 6392 }).catch((error: BusinessError) => { 6393 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 6394 }) 6395``` 6396 6397### packing<sup>(deprecated)</sup> 6398 6399packing(source: PixelMap, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 6400 6401图片压缩或重新编码，使用callback形式返回结果。 6402 6403> **说明：** 6404> 6405> 从API version 8开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6406 6407> **注意：** 6408> 接口如果返回"PixelMap mismatch"，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6409 6410**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6411 6412**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6413 6414**参数：** 6415 6416| 参数名 | 类型 | 必填 | 说明 | 6417| -------- | ------------------------------- | ---- | ---------------------------------- | 6418| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap资源。 | 6419| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6420| callback | AsyncCallback\<ArrayBuffer> | 是 | 回调函数，当图片编码成功，err为undefined，data为获取到的压缩或编码数据；否则为错误对象。 | 6421 6422**示例：** 6423 6424```ts 6425import { BusinessError } from '@kit.BasicServicesKit'; 6426 6427const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6428let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6429image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 6430 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6431 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6432 imagePackerApi.packing(pixelMap, packOpts, (err: BusinessError, data: ArrayBuffer) => { 6433 if (err) { 6434 console.error(`Failed to pack the image.code ${err.code},message is ${err.message}`); 6435 } else { 6436 console.info('Succeeded in packing the image.'); 6437 } 6438 }) 6439}).catch((error: BusinessError) => { 6440 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 6441}) 6442``` 6443 6444### packing<sup>(deprecated)</sup> 6445 6446packing(source: PixelMap, option: PackingOption): Promise\<ArrayBuffer> 6447 6448图片压缩或重新编码，使用Promise形式返回结果。 6449 6450> **说明：** 6451> 6452> 从API version 8开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6453 6454> **注意：** 6455> 接口如果返回"PixelMap mismatch"，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6456 6457**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6458 6459**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6460 6461**参数：** 6462 6463| 参数名 | 类型 | 必填 | 说明 | 6464| ------ | ------------------------------- | ---- | ------------------ | 6465| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap源。 | 6466| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6467 6468**返回值：** 6469 6470| 类型 | 说明 | 6471| --------------------- | -------------------------------------------- | 6472| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。| 6473 6474**示例：** 6475 6476```ts 6477import { BusinessError } from '@kit.BasicServicesKit'; 6478 6479const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6480let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6481image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 6482 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6483 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6484 imagePackerApi.packing(pixelMap, packOpts) 6485 .then((data: ArrayBuffer) => { 6486 console.info('Succeeded in packing the image.'); 6487 }).catch((error: BusinessError) => { 6488 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 6489 }) 6490}).catch((error: BusinessError) => { 6491 console.error(`Failed to create PixelMap.code ${error.code},message is ${error.message}`); 6492}) 6493``` 6494 6495### release 6496 6497release(callback: AsyncCallback\<void>): void 6498 6499释放图片编码实例，使用callback形式返回结果。 6500 6501ArkTS有内存回收机制，ImagePacker对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 6502 6503**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6504 6505**参数：** 6506 6507| 参数名 | 类型 | 必填 | 说明 | 6508| -------- | -------------------- | ---- | ------------------------------ | 6509| callback | AsyncCallback\<void> | 是 | 回调函数，当释放图片编码实例成功，err为undefined，否则为错误对象。 | 6510 6511**示例：** 6512 6513```ts 6514import { BusinessError } from '@kit.BasicServicesKit'; 6515 6516const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6517imagePackerApi.release((err: BusinessError)=>{ 6518 if (err) { 6519 console.error(`Failed to release image packaging.code ${err.code},message is ${err.message}`); 6520 } else { 6521 console.info('Succeeded in releasing image packaging.'); 6522 } 6523}) 6524``` 6525 6526### release 6527 6528release(): Promise\<void> 6529 6530释放图片编码实例，使用Promise形式返回释放结果。 6531 6532ArkTS有内存回收机制，ImagePacker对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 6533 6534**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6535 6536**返回值：** 6537 6538| 类型 | 说明 | 6539| -------------- | ------------------------------------------------------ | 6540| Promise\<void> | Promise对象。无返回结果的Promise对象。| 6541 6542**示例：** 6543 6544```ts 6545import { BusinessError } from '@kit.BasicServicesKit'; 6546 6547const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6548imagePackerApi.release().then(() => { 6549 console.info('Succeeded in releasing image packaging.'); 6550}).catch((error: BusinessError) => { 6551 console.error(`Failed to release image packaging.code ${error.code},message is ${error.message}`); 6552}) 6553``` 6554 6555### packToFile<sup>11+</sup> 6556 6557packToFile(source: ImageSource, fd: number, options: PackingOption, callback: AsyncCallback\<void>): void 6558 6559指定编码参数，将ImageSource直接编码进文件。使用callback形式返回结果。 6560 6561**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6562 6563**参数：** 6564 6565| 参数名 | 类型 | 必填 | 说明 | 6566| -------- | ------------------------------- | ---- | ------------------------------ | 6567| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6568| fd | number | 是 | 文件描述符。 | 6569| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6570| callback | AsyncCallback\<void> | 是 | 回调函数，当编码进文件成功，err为undefined，否则为错误对象。 | 6571 6572**错误码：** 6573 6574以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6575 6576| 错误码ID | 错误信息 | 6577| ------- | --------------------------------------------| 6578| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 6579| 62980101 | The image data is abnormal. | 6580| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 6581| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 6582| 62980115 | Invalid input parameter. | 6583| 62980119 | Failed to encode the image. | 6584| 62980120 | Add pixelmap out of range. | 6585| 62980172 | Failed to encode icc. | 6586| 62980252 | Failed to create surface. | 6587 6588**示例：** 6589 6590<!--code_no_check--> 6591```ts 6592import { common } from '@kit.AbilityKit'; 6593import { BusinessError } from '@kit.BasicServicesKit'; 6594import { fileIo as fs } from '@kit.CoreFileKit'; 6595 6596// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6597let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6598//此处'test.png'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6599const path: string = context.filesDir + "/test.png"; 6600const imageSourceApi: image.ImageSource = image.createImageSource(path); 6601let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6602const filePath: string = context.filesDir + "/image_source.jpg"; 6603let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6604const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6605imagePackerApi.packToFile(imageSourceApi, file.fd, packOpts, (err: BusinessError) => { 6606 if (err) { 6607 console.error(`Failed to pack the image to file.code ${err.code},message is ${err.message}`); 6608 } else { 6609 console.info('Succeeded in packing the image to file.'); 6610 } 6611}) 6612``` 6613 6614### packToFile<sup>11+</sup> 6615 6616packToFile (source: ImageSource, fd: number, options: PackingOption): Promise\<void> 6617 6618指定编码参数，将ImageSource直接编码进文件。使用Promise形式返回结果。 6619 6620**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6621 6622**参数：** 6623 6624| 参数名 | 类型 | 必填 | 说明 | 6625| ------ | ------------------------------- | ---- | -------------- | 6626| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6627| fd | number | 是 | 文件描述符。 | 6628| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6629 6630**返回值：** 6631 6632| 类型 | 说明 | 6633| -------------- | --------------------------------- | 6634| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6635 6636**错误码：** 6637 6638以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6639 6640| 错误码ID | 错误信息 | 6641| ------- | --------------------------------------------| 6642| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 6643| 62980101 | The image data is abnormal. | 6644| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 6645| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 6646| 62980115 | Invalid input parameter. | 6647| 62980119 | Failed to encode the image. | 6648| 62980120 | Add pixelmap out of range. | 6649| 62980172 | Failed to encode icc. | 6650| 62980252 | Failed to create surface. | 6651 6652**示例：** 6653 6654<!--code_no_check--> 6655```ts 6656import { common } from '@kit.AbilityKit'; 6657import { BusinessError } from '@kit.BasicServicesKit'; 6658import { fileIo as fs } from '@kit.CoreFileKit'; 6659 6660// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6661let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6662//此处'test.png'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6663const path: string = context.filesDir + "/test.png"; 6664const imageSourceApi: image.ImageSource = image.createImageSource(path); 6665let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6666const filePath: string = context.filesDir + "/image_source.jpg"; 6667let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6668const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6669imagePackerApi.packToFile(imageSourceApi, file.fd, packOpts).then(() => { 6670 console.info('Succeeded in packing the image to file.'); 6671}).catch((error: BusinessError) => { 6672 console.error(`Failed to pack the image to file.code ${error.code},message is ${error.message}`); 6673}) 6674``` 6675 6676### packToFile<sup>11+</sup> 6677 6678packToFile (source: PixelMap, fd: number, options: PackingOption, callback: AsyncCallback\<void>): void 6679 6680指定编码参数，将PixelMap直接编码进文件。使用callback形式返回结果。 6681 6682> **注意：** 6683> 接口如果返回62980115错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6684 6685**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6686 6687**参数：** 6688 6689| 参数名 | 类型 | 必填 | 说明 | 6690| -------- | ------------------------------- | ---- | ------------------------------ | 6691| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap资源。 | 6692| fd | number | 是 | 文件描述符。 | 6693| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6694| callback | AsyncCallback\<void> | 是 | 回调函数，当编码图片进文件成功，err为undefined，否则为错误对象。 | 6695 6696**错误码：** 6697 6698以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6699 6700| 错误码ID | 错误信息 | 6701| ------- | --------------------------------------------| 6702| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 6703| 62980101 | The image data is abnormal. | 6704| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 6705| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 6706| 62980115 | Invalid input parameter. | 6707| 62980119 | Failed to encode the image. | 6708| 62980120 | Add pixelmap out of range. | 6709| 62980172 | Failed to encode icc. | 6710| 62980252 | Failed to create surface. | 6711 6712**示例：** 6713 6714<!--code_no_check--> 6715```ts 6716import { common } from '@kit.AbilityKit'; 6717import { BusinessError } from '@kit.BasicServicesKit'; 6718import { fileIo as fs } from '@kit.CoreFileKit'; 6719 6720const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6721let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6722// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6723let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6724const path: string = context.filesDir + "/pixel_map.jpg"; 6725image.createPixelMap(color, opts).then((pixelmap: image.PixelMap) => { 6726 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6727 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6728 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6729 imagePackerApi.packToFile(pixelmap, file.fd, packOpts, (err: BusinessError) => { 6730 if (err) { 6731 console.error(`Failed to pack the image to file.code ${err.code},message is ${err.message}`); 6732 } else { 6733 console.info('Succeeded in packing the image to file.'); 6734 } 6735 }) 6736}) 6737``` 6738 6739### packToFile<sup>11+</sup> 6740 6741packToFile (source: PixelMap, fd: number, options: PackingOption): Promise\<void> 6742 6743指定编码参数，将PixelMap直接编码进文件。使用Promise形式返回结果。 6744 6745> **注意：** 6746> 接口如果返回62980115错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6747 6748**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6749 6750**参数：** 6751 6752| 参数名 | 类型 | 必填 | 说明 | 6753| ------ | ------------------------------- | ---- | -------------------- | 6754| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap资源。 | 6755| fd | number | 是 | 文件描述符。 | 6756| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6757 6758**返回值：** 6759 6760| 类型 | 说明 | 6761| -------------- | --------------------------------- | 6762| Promise\<void> | Promise对象。无返回结果的Promise对象。| 6763 6764**错误码：** 6765 6766以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6767 6768| 错误码ID | 错误信息 | 6769| ------- | --------------------------------------------| 6770| 62980096| Operation failed.Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 6771| 62980101 | The image data is abnormal. | 6772| 62980106 | The image data is too large. This status code is thrown when an error occurs during the process of checking size. | 6773| 62980113| Unknown image format.The image data provided is not in a recognized or supported format, or it may be occorrupted. | 6774| 62980115 | Invalid input parameter. | 6775| 62980119 | Failed to encode the image. | 6776| 62980120 | Add pixelmap out of range. | 6777| 62980172 | Failed to encode icc. | 6778| 62980252 | Failed to create surface. | 6779 6780**示例：** 6781 6782<!--code_no_check--> 6783```ts 6784import { common } from '@kit.AbilityKit'; 6785import { BusinessError } from '@kit.BasicServicesKit'; 6786import { fileIo as fs } from '@kit.CoreFileKit'; 6787 6788const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6789let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6790// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6791let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6792const path: string = context.filesDir + "/pixel_map.jpg"; 6793image.createPixelMap(color, opts).then((pixelmap: image.PixelMap) => { 6794 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6795 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6796 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6797 imagePackerApi.packToFile(pixelmap, file.fd, packOpts) 6798 .then(() => { 6799 console.info('Succeeded in packing the image to file.'); 6800 }).catch((error: BusinessError) => { 6801 console.error(`Failed to pack the image to file.code ${error.code},message is ${error.message}`); 6802 }) 6803}) 6804``` 6805 6806### packToFile<sup>13+</sup> 6807 6808packToFile(picture: Picture, fd: number, options: PackingOption): Promise\<void> 6809 6810指定编码参数，将Picture直接编码进文件。使用Promise形式返回结果。 6811 6812**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6813 6814**参数：** 6815 6816| 参数名 | 类型 | 必填 | 说明 | 6817| ------- | ---------------------------- | ---- | -------------------- | 6818| picture | [Picture](#picture13) | 是 | 编码的Picture资源。 | 6819| fd | number | 是 | 文件描述符。 | 6820| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6821 6822**返回值：** 6823 6824| 类型 | 说明 | 6825| -------------- | ------------------------- | 6826| Promise\<void> | 无返回结果的Promise对象。 | 6827 6828**错误码：** 6829 6830以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6831 6832| 错误码ID | 错误信息 | 6833| -------- | ------------------------------------------------------------ | 6834| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6835| 7800301 | Encode failed. | 6836 6837**示例：** 6838 6839```ts 6840import { BusinessError } from '@kit.BasicServicesKit'; 6841import { image } from '@kit.ImageKit'; 6842import { fileIo as fs } from '@kit.CoreFileKit'; 6843 6844async function PackToFile(context: Context) { 6845 const resourceMgr = context.resourceManager; 6846 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 6847 let ops: image.SourceOptions = { 6848 sourceDensity: 98, 6849 } 6850 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6851 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6852 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6853 6854 let funcName = "PackToFile"; 6855 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6856 if (imagePackerApi != null) { 6857 const filePath: string = context.filesDir + "/test.jpg"; 6858 let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6859 let packOpts: image.PackingOption = { 6860 format: "image/jpeg", 6861 quality: 98, 6862 bufferSize: 10, 6863 desiredDynamicRange: image.PackingDynamicRange.AUTO, 6864 needsPackProperties: true}; 6865 await imagePackerApi.packToFile(pictureObj, file.fd, packOpts).then(() => { 6866 console.info(funcName, 'Succeeded in packing the image to file.'); 6867 }).catch((error: BusinessError) => { 6868 console.error(funcName, 'Failed to pack the image to file.code ${error.code},message is ${error.message}'); 6869 }); 6870 } 6871} 6872``` 6873 6874### packToFileFromPixelmapSequence<sup>18+</sup> 6875 6876packToFileFromPixelmapSequence(pixelmapSequence: Array\<PixelMap>, fd: number, options: PackingOptionsForSequence): Promise\<void> 6877 6878指定编码参数，将多个PixelMap编码成GIF文件。使用Promise形式返回结果。 6879 6880**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6881 6882**参数：** 6883 6884| 参数名 | 类型 | 必填 | 说明 | 6885| ---------------- | --------------------------------------------------------- | ---- | ---------------------- | 6886| pixelmapSequence | Array<[PixelMap](#pixelmap7)> | 是 | 待编码的PixelMap序列。 | 6887| fd | number | 是 | 文件描述符。 | 6888| options | [PackingOptionsForSequence](#packingoptionsforsequence18) | 是 | 动图编码参数。 | 6889 6890**返回值：** 6891 6892| 类型 | 说明 | 6893| -------------- | ------------------------- | 6894| Promise\<void> | 无返回结果的Promise对象。 | 6895 6896**错误码：** 6897 6898以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 6899 6900| 错误码ID | 错误信息 | 6901| -------- | ------------------------------------------------------------ | 6902| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6903| 7800201 | Unsupported packing options. | 6904| 7800301 | Failed to encode image. | 6905 6906**示例：** 6907 6908<!--code_no_check--> 6909```ts 6910import { common } from '@kit.AbilityKit'; 6911import { BusinessError } from '@ohos.base'; 6912import fs from '@ohos.file.fs'; 6913import image from "@ohos.multimedia.image"; 6914 6915// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 6916let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6917const resourceMgr = context.resourceManager; 6918// 此处'moving_test.gif'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 6919const fileData = await resourceMgr.getRawFileContent('moving_test.gif'); 6920const color = fileData.buffer; 6921let imageSource = image.createImageSource(color); 6922let pixelMapList = await imageSource.createPixelMapList(); 6923let path: string = context.cacheDir + '/result.gif'; 6924let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6925let ops: image.PackingOptionsForSequence = { 6926 frameCount: 3, // 指定GIF编码中的帧数为3。 6927 delayTimeList: [10, 10, 10], // 指定GIF编码中3帧的延迟时间分别为100ms、100ms、100ms。 6928 disposalTypes: [3, 2, 3], // 指定GIF编码中3帧的帧过渡模式分别为3（恢复到之前的状态）、2（恢复背景色)、3(恢复到之前的状态)。 6929 loopCount: 0 // 指定GIF编码中循环次数为无限循环。 6930}; 6931let Packer = image.createImagePacker(); 6932Packer.packToFileFromPixelmapSequence(pixelMapList, file.fd, ops) 6933 .then(() => { 6934 console.info('Succeeded in packToFileMultiFrames.'); 6935 }).catch((error: BusinessError) => { 6936 console.error('Failed to packToFileMultiFrames.'); 6937 }) 6938``` 6939 6940## image.getImagePackerSupportedFormats<sup>20+</sup> 6941 6942getImagePackerSupportedFormats(): string[] 6943 6944获取支持编码的图片格式，图片格式以mime type表示。 6945 6946**系统能力：** SystemCapability.Multimedia.Image.Core 6947 6948**返回值：** 6949 6950| 类型 | 说明 | 6951| -------- | ------------------------------------------ | 6952| string[] | 支持解码的图片格式（mime type）列表。 | 6953 6954**示例：** 6955 6956```ts 6957import { image } from '@kit.ImageKit'; 6958function GetImagePackerSupportedFormats() { 6959 let formats = image.getImagePackerSupportedFormats(); 6960 console.info('formats:', formats); 6961} 6962``` 6963 6964## image.createAuxiliaryPicture<sup>13+</sup> 6965 6966createAuxiliaryPicture(buffer: ArrayBuffer, size: Size, type: AuxiliaryPictureType): AuxiliaryPicture 6967 6968通过ArrayBuffer图片数据、辅助图尺寸、辅助图类型创建AuxiliaryPicture实例。 6969 6970**系统能力：** SystemCapability.Multimedia.Image.Core 6971 6972**参数：** 6973 6974| 参数名 | 类型 | 必填 | 说明 | 6975| ------ | ----------------------------------------------- | ---- | ---------------------------- | 6976| buffer | ArrayBuffer | 是 | 以buffer形式存放的图像数据。 | 6977| size | [Size](#size) | 是 | 辅助图的尺寸。单位：像素。 | 6978| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 6979 6980**返回值：** 6981 6982| 类型 | 说明 | 6983| --------------------------------------- | ------------------------------------------ | 6984| [AuxiliaryPicture](#auxiliarypicture13) | 如果操作成功，则返回AuxiliaryPicture实例。 | 6985 6986**错误码：** 6987 6988以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6989 6990| 错误码ID | 错误信息 | 6991| -------- | ------------------------------------------------------------ | 6992| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6993 6994**示例：** 6995 6996```ts 6997import { image } from '@kit.ImageKit'; 6998 6999async function CreateAuxiliaryPicture(context: Context) { 7000 let funcName = "CreateAuxiliaryPicture"; 7001 const resourceMgr = context.resourceManager; 7002 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 7003 let auxBuffer: ArrayBuffer = rawFile.buffer as ArrayBuffer; 7004 let auxSize: Size = { 7005 height: 180, 7006 width: 240 7007 }; 7008 let auxType: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 7009 let auxPictureObj: image.AuxiliaryPicture | null = image.createAuxiliaryPicture(auxBuffer, auxSize, auxType); 7010 if(auxPictureObj != null) { 7011 let type: image.AuxiliaryPictureType = auxPictureObj.getType(); 7012 console.info(funcName, 'CreateAuxiliaryPicture succeeded this.Aux_picture.type.' + JSON.stringify(type)); 7013 } else { 7014 console.error(funcName, 'CreateAuxiliaryPicture failed'); 7015 } 7016} 7017``` 7018 7019## AuxiliaryPicture<sup>13+</sup> 7020 7021辅助图一般用于辅助主图进行特殊信息的展示，使图像包含更丰富的信息。辅助图图像类，用于读取或写入图像的辅助图数据以及获取图像的辅助图信息。在调用AuxiliaryPicture的方法前，需要先通过[createAuxiliaryPicture](#imagecreateauxiliarypicture13)创建一个AuxiliaryPicture实例。 7022 7023### 属性 7024 7025**系统能力：** SystemCapability.Multimedia.Image.Core 7026 7027### writePixelsFromBuffer<sup>13+</sup> 7028 7029writePixelsFromBuffer(data: ArrayBuffer): Promise\<void> 7030 7031读取ArrayBuffer中的辅助图片数据，并将数据写入AuxiliaryPicture对象，使用Promise形式返回。 7032 7033**系统能力：** SystemCapability.Multimedia.Image.Core 7034 7035**参数：** 7036 7037| 参数名 | 类型 | 必填 | 说明 | 7038| ------ | ----------- | ---- | ---------------- | 7039| data | ArrayBuffer | 是 | 辅助图像素数据。 | 7040 7041**返回值：** 7042 7043| 类型 | 说明 | 7044| -------------- | -------------------------------------- | 7045| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7046 7047**错误码：** 7048 7049以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7050 7051| 错误码ID | 错误信息 | 7052| -------- | ------------------------------------------------------------ | 7053| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 7054| 7600301 | Memory alloc failed. | 7055| 7600302 | Memory copy failed. | 7056 7057**示例:** 7058 7059```ts 7060import { image } from '@kit.ImageKit'; 7061 7062async function WritePixelsFromBuffer(context: Context) { 7063 const resourceMgr = context.resourceManager; 7064 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 7065 let ops: image.SourceOptions = { 7066 sourceDensity: 98, 7067 } 7068 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7069 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7070 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7071 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP); 7072 if(auxPictureObj != null) { 7073 let auxBuffer: ArrayBuffer = await auxPictureObj.readPixelsToBuffer(); 7074 await auxPictureObj.writePixelsFromBuffer(auxBuffer); 7075 console.info('Write pixels from buffer success.'); 7076 } else { 7077 console.error('AuxPictureObj is null.'); 7078 } 7079} 7080``` 7081 7082### readPixelsToBuffer<sup>13+</sup> 7083 7084readPixelsToBuffer(): Promise\<ArrayBuffer> 7085 7086读取图像像素映射数据并将数据写入ArrayBuffer，使用Promise形式返回。 7087 7088**系统能力：** SystemCapability.Multimedia.Image.Core 7089 7090**返回值：** 7091 7092| 类型 | 说明 | 7093| --------------------- | --------------------------------- | 7094| Promise\<ArrayBuffer> | Promise对象。返回辅助图像素数据。 | 7095 7096**错误码：** 7097 7098以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7099 7100| 错误码ID | 错误信息 | 7101| -------- | -------------------- | 7102| 7600301 | Memory alloc failed. | 7103| 7600302 | Memory copy failed. | 7104 7105**示例：** 7106 7107```ts 7108import { BusinessError } from '@kit.BasicServicesKit'; 7109import { image } from '@kit.ImageKit'; 7110 7111async function ReadPixelsToBuffer(context: Context) { 7112 const resourceMgr = context.resourceManager; 7113 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 7114 let ops: image.SourceOptions = { 7115 sourceDensity: 98, 7116 } 7117 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7118 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7119 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7120 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP); 7121 if(auxPictureObj != null) { 7122 await auxPictureObj.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => { 7123 console.info('Read pixels to buffer success.' ); 7124 }).catch((error: BusinessError) => { 7125 console.error('Read pixels to buffer failed error.code: ' + JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 7126 }); 7127 } else { 7128 console.error('AuxPictureObj is null.'); 7129 } 7130} 7131``` 7132 7133### getType<sup>13+</sup> 7134 7135getType(): AuxiliaryPictureType 7136 7137获取辅助图的类型。 7138 7139**系统能力：** SystemCapability.Multimedia.Image.Core 7140 7141**返回值：** 7142 7143| 类型 | 说明 | 7144| ----------------------------------------------- | ---------------------------- | 7145| [AuxiliaryPictureType](#auxiliarypicturetype13) | 操作成功，返回辅助图的类型。 | 7146 7147**示例：** 7148 7149```ts 7150import { image } from '@kit.ImageKit'; 7151 7152async function GetAuxiliaryPictureType() { 7153 if (auxPictureObj != null) { 7154 let type: image.AuxiliaryPictureType = auxPictureObj.getType(); 7155 console.info('Success get auxiliary picture type ' + JSON.stringify(type)); 7156 } else { 7157 console.error('Failed get auxiliary picture type '); 7158 } 7159} 7160``` 7161 7162### setMetadata<sup>13+</sup> 7163 7164setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void> 7165 7166设置辅助图元数据。 7167 7168**系统能力：** SystemCapability.Multimedia.Image.Core 7169 7170**参数：** 7171 7172| 参数名 | 类型 | 必填 | 说明 | 7173| ------------ | ------------------------------- | ---- | ------------------------------------ | 7174| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据的类型，用于设置对应的元数据。 | 7175| metadata | [Metadata](#metadata13) | 是 | 元数据对象。 | 7176 7177**返回值：** 7178 7179| 类型 | 说明 | 7180| -------------- | -------------------------------------- | 7181| Promise\<void> | Promise对象，无返回结果的Promise对象。 | 7182 7183**错误码：** 7184 7185以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7186 7187| 错误码ID | 错误信息 | 7188| -------- | ------------------------------------------------------------ | 7189| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 7190| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 7191 7192**示例：** 7193 7194```ts 7195import { BusinessError } from '@kit.BasicServicesKit'; 7196import { image } from '@kit.ImageKit'; 7197 7198async function SetAuxPictureObjMetadata(exifContext: Context) { 7199 const exifResourceMgr = exifContext.resourceManager; 7200 const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");//图片包含exif metadata。 7201 let exifOps: image.SourceOptions = { 7202 sourceDensity: 98, 7203 } 7204 let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps); 7205 let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap(); 7206 let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap); 7207 if (exifPictureObj != null) { 7208 console.info('Create picture succeeded'); 7209 } else { 7210 console.error('Create picture failed'); 7211 } 7212 7213 if (auxPictureObj != null) { 7214 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7215 let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType); 7216 auxPictureObj.setMetadata(metadataType, exifMetaData).then(() => { 7217 console.info('Set metadata success'); 7218 }).catch((error: BusinessError) => { 7219 console.error('Set metadata failed.error.code: ${error.code}, error.message: ${error.message}'); 7220 }); 7221 } else { 7222 console.error('AuxPictureObjMetaData is null'); 7223 } 7224} 7225``` 7226 7227### getMetadata<sup>13+</sup> 7228 7229getMetadata(metadataType: MetadataType): Promise\<Metadata> 7230 7231从辅助图中获取元数据。 7232 7233**系统能力：** SystemCapability.Multimedia.Image.Core 7234 7235**参数：** 7236 7237| 参数名 | 类型 | 必填 | 说明 | 7238| ------------ | ------------------------------- | ---- | -------------------------------------- | 7239| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型，用于获取对应类型的元数据。 | 7240 7241**返回值：** 7242 7243| 类型 | 说明 | 7244| -------------------------------- | ---------------- | 7245| Promise<[Metadata](#metadata13)> | 返回元数据对象。 | 7246 7247**错误码：** 7248 7249以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7250 7251| 错误码ID | 错误信息 | 7252| -------- | ------------------------------------------------------------ | 7253| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 7254| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 7255 7256**示例：** 7257 7258```ts 7259import { image } from '@kit.ImageKit'; 7260 7261async function GetAuxPictureObjMetadata() { 7262 if (auxPictureObj != null) { 7263 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7264 let auxPictureObjMetaData: image.Metadata | null = await auxPictureObj.getMetadata(metadataType); 7265 if (auxPictureObjMetaData != null) { 7266 console.info('Get auxpictureobj Metadata success' ); 7267 } else { 7268 console.error('Get auxpictureobj Metadata failed'); 7269 } 7270 } else { 7271 console.error('Get auxpictureobj is null.'); 7272 } 7273} 7274``` 7275 7276### getAuxiliaryPictureinfo<sup>13+</sup> 7277 7278getAuxiliaryPictureInfo(): AuxiliaryPictureInfo 7279 7280获取有关此辅助图的图像信息。 7281 7282**系统能力：** SystemCapability.Multimedia.Image.Core 7283 7284**返回值：** 7285 7286| 类型 | 说明 | 7287| ----------------------------------------------- | --------------------------------- | 7288| [AuxiliaryPictureInfo](#auxiliarypictureinfo13) | Promise对象，返回辅助图图像信息。 | 7289 7290**示例：** 7291 7292```ts 7293import { image } from '@kit.ImageKit'; 7294 7295async function GetAuxiliaryPictureInfo() { 7296 if(auxPictureObj != null) { 7297 let auxinfo: image.AuxiliaryPictureInfo = auxPictureObj.getAuxiliaryPictureInfo(); 7298 console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType + 7299 ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width + 7300 ' rowStride: ' + auxinfo.rowStride + ' pixelFormat: ' + auxinfo.pixelFormat + 7301 ' colorSpace: ' + auxinfo.colorSpace); 7302 } else { 7303 console.error('Get auxiliary picture information failed'); 7304 } 7305} 7306``` 7307 7308### setAuxiliaryPictureinfo<sup>13+</sup> 7309 7310setAuxiliaryPictureInfo(info: AuxiliaryPictureInfo): void 7311 7312设置辅助图的图像信息。 7313 7314**系统能力：** SystemCapability.Multimedia.Image.Core 7315 7316**参数：** 7317 7318| 参数名 | 类型 | 必填 | 说明 | 7319| ------ | ----------------------------------------------- | ---- | ------------------ | 7320| info | [AuxiliaryPictureInfo](#auxiliarypictureinfo13) | 是 | 辅助图的图像信息。 | 7321 7322**错误码：** 7323 7324以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7325 7326| 错误码ID | 错误信息 | 7327| -------- | :----------------------------------------------------------- | 7328| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 7329 7330**示例：** 7331 7332```ts 7333import { colorSpaceManager } from '@kit.ArkGraphics2D'; 7334import { image } from '@kit.ImageKit'; 7335 7336async function SetAuxiliaryPictureInfo() { 7337 if(auxPictureObj != null) { 7338 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 7339 let info: image.AuxiliaryPictureInfo = { 7340 auxiliaryPictureType: image.AuxiliaryPictureType.GAINMAP, 7341 size: {height: 100, width: 200}, 7342 pixelFormat: image.PixelMapFormat.RGBA_8888, 7343 rowStride: 0, 7344 colorSpace: colorSpaceManager.create(colorSpaceName), 7345 }; 7346 auxPictureObj.setAuxiliaryPictureInfo(info); 7347 } 7348} 7349``` 7350 7351### release<sup>13+</sup> 7352 7353release():void 7354 7355释放辅助图对象，无返回值。 7356 7357**系统能力：** SystemCapability.Multimedia.Image.Core 7358 7359**示例：** 7360 7361```ts 7362import { image } from '@kit.ImageKit'; 7363 7364async function Release() { 7365 let funcName = "Release"; 7366 if (auxPictureObj != null) { 7367 auxPictureObj.release(); 7368 if (auxPictureObj.getType() == null) { 7369 console.info(funcName, 'Success !'); 7370 } else { 7371 console.error(funcName, 'Failed !'); 7372 } 7373 } else { 7374 console.error('PictureObj is null'); 7375 } 7376} 7377``` 7378 7379## Metadata<sup>13+</sup> 7380 7381图像元数据类，用于存储图像的元数据。目前支持的元数据类型可参考[MetadataType](#metadatatype13)。 7382 7383### 属性 7384 7385**系统能力：** SystemCapability.Multimedia.Image.Core 7386 7387### getProperties<sup>13+</sup> 7388 7389getProperties(key: Array\<string>): Promise\<Record\<string, string | null>> 7390 7391获取图像中属性的值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 7392 7393**系统能力：** SystemCapability.Multimedia.Image.Core 7394 7395**参数：** 7396 7397| 参数名 | 类型 | 必填 | 说明 | 7398| ------ | -------------- | ---- | ------------------------ | 7399| key | Array\<string> | 是 | 要获取其值的属性的名称。 | 7400 7401**返回值：** 7402 7403| 类型 | 说明 | 7404| ---------------------------------------- | ------------------------------------------------------------ | 7405| Promise\<Record<string, string \| null>> | Promise对象，返回元数据要获取的属性的值，如获取失败则返回错误码。 | 7406 7407**错误码：** 7408 7409以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7410 7411| 错误码ID | 错误信息 | 7412| -------- | ------------------------------------------------------------ | 7413| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 7414| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 7415 7416**示例：** 7417 7418```ts 7419import { BusinessError } from '@kit.BasicServicesKit'; 7420import { image } from '@kit.ImageKit'; 7421 7422async function GetProperties(context: Context) { 7423 const resourceMgr = context.resourceManager; 7424 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7425 let ops: image.SourceOptions = { 7426 sourceDensity: 98, 7427 } 7428 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7429 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7430 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7431 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7432 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7433 if (metaData != null) { 7434 await metaData.getProperties(["ImageWidth", "ImageLength"]).then((data2) => { 7435 console.info('Get properties ',JSON.stringify(data2)); 7436 }).catch((error: BusinessError) => { 7437 console.error('Get properties failed error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 7438 }); 7439 } else { 7440 console.error('Metadata is null.'); 7441 } 7442} 7443``` 7444 7445### setProperties<sup>13+</sup> 7446 7447setProperties(records: Record\<string, string | null>): Promise\<void> 7448 7449批量设置图片元数据中的指定属性的值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 7450 7451**系统能力：** SystemCapability.Multimedia.Image.Core 7452 7453**参数：** 7454 7455| 参数名 | 类型 | 必填 | 说明 | 7456| ------- | ------------------------------ | ---- | ------------------------ | 7457| records | Record<string, string \| null> | 是 | 要修改的属性和值的数组。 | 7458 7459**返回值：** 7460 7461| 类型 | 说明 | 7462| -------------- | ------------------------------------- | 7463| Promise\<void> | Promise对象，如获取失败则返回错误码。 | 7464 7465**错误码：** 7466 7467以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7468 7469| 错误码ID | 错误信息 | 7470| -------- | ------------------------------------------------------------ | 7471| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 7472| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 7473 7474**示例：** 7475 7476```ts 7477import { BusinessError } from '@kit.BasicServicesKit'; 7478import { image } from '@kit.ImageKit'; 7479 7480async function SetProperties(context: Context) { 7481 const resourceMgr = context.resourceManager; 7482 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7483 let ops: image.SourceOptions = { 7484 sourceDensity: 98, 7485 } 7486 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7487 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7488 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7489 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7490 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7491 if (metaData != null) { 7492 let setkey: Record<string, string | null> = { 7493 "ImageWidth": "200", 7494 "ImageLength": "300" 7495 }; 7496 await metaData.setProperties(setkey).then(async () => { 7497 console.info('Set auxpictureobj properties success.'); 7498 }).catch((error: BusinessError) => { 7499 console.error('Failed to set metadata Properties. code is ${error.code}, message is ${error.message}'); 7500 }) 7501 } else { 7502 console.error('AuxPictureObj metadata is null. '); 7503 } 7504} 7505``` 7506 7507### getAllProperties<sup>13+</sup> 7508 7509getAllProperties(): Promise\<Record<string, string | null>> 7510 7511获取图片中所有元数据的属性和值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 7512 7513**系统能力：** SystemCapability.Multimedia.Image.Core 7514 7515**返回值：** 7516 7517| 类型 | 说明 | 7518| ---------------------------------------- | ------------------------------------------- | 7519| Promise\<Record<string, string \| null>> | Promise对象，返回元数据拥有的所有属性的值。 | 7520 7521**示例：** 7522 7523```ts 7524import { BusinessError } from '@kit.BasicServicesKit'; 7525import { image } from '@kit.ImageKit'; 7526 7527async function GetAllProperties(context: Context) { 7528 const resourceMgr = context.resourceManager; 7529 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7530 let ops: image.SourceOptions = { 7531 sourceDensity: 98, 7532 } 7533 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7534 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7535 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7536 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7537 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7538 if (metaData != null) { 7539 await metaData.getAllProperties().then((data2) => { 7540 const count = Object.keys(data2).length; 7541 console.info('Metadata have ', count, ' properties'); 7542 console.info('Get metadata all properties: ', JSON.stringify(data2)); 7543 }).catch((error: BusinessError) => { 7544 console.error('Get metadata all properties failed error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 7545 }); 7546 } else { 7547 console.error('Metadata is null.'); 7548 } 7549} 7550``` 7551 7552### clone<sup>13+</sup> 7553 7554clone(): Promise\<Metadata> 7555 7556对元数据进行克隆，用Promise形式返回结果。 7557 7558**系统能力：** SystemCapability.Multimedia.Image.Core 7559 7560**返回值：** 7561 7562| 类型 | 说明 | 7563| --------------------------------- | --------------------------------- | 7564| Promise\<[Metadata](#metadata13)> | Promise对象，成功返回元数据实例。 | 7565 7566**错误码：** 7567 7568以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7569 7570| 错误码ID | 错误信息 | 7571| -------- | -------------------- | 7572| 7600301 | Memory alloc failed. | 7573| 7600302 | Memory copy failed. | 7574 7575**示例：** 7576 7577```ts 7578import { BusinessError } from '@kit.BasicServicesKit'; 7579import { image } from '@kit.ImageKit'; 7580 7581async function clone(context: Context) { 7582 const resourceMgr = context.resourceManager; 7583 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7584 let ops: image.SourceOptions = { 7585 sourceDensity: 98, 7586 } 7587 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7588 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7589 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7590 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7591 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7592 if (metaData != null) { 7593 let new_metadata: image.Metadata = await metaData.clone(); 7594 new_metadata.getProperties(["ImageWidth"]).then((data1) => { 7595 console.info('Clone new_metadata and get Properties.', JSON.stringify(data1)); 7596 }).catch((err: BusinessError) => { 7597 console.error('Clone new_metadata failed.', JSON.stringify(err)); 7598 }); 7599 } else { 7600 console.error('Metadata is null.'); 7601 } 7602} 7603``` 7604 7605## image.createImageReceiver<sup>11+</sup> 7606 7607createImageReceiver(size: Size, format: ImageFormat, capacity: number): ImageReceiver 7608 7609通过图片大小、图片格式、容量创建ImageReceiver实例。ImageReceiver做为图片的接收方、消费者，它的参数属性实际上不会对接收到的图片产生影响。图片属性的配置应在发送方、生产者进行，如相机预览流[createPreviewOutput](../apis-camera-kit/arkts-apis-camera-CameraManager.md#createpreviewoutput)。 7610 7611**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7612 7613**参数：** 7614 7615| 参数名 | 类型 | 必填 | 说明 | 7616| -------- | ------ | ---- | ---------------------- | 7617| size | [Size](#size) | 是 | 图像的默认大小。该参数不会影响接收到的图片大小，实际返回大小由生产者决定，如相机。 | 7618| format | [ImageFormat](#imageformat9) | 是 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机）。 | 7619| capacity | number | 是 | 同时访问的最大图像数。 | 7620 7621**返回值：** 7622 7623| 类型 | 说明 | 7624| -------------------------------- | --------------------------------------- | 7625| [ImageReceiver](#imagereceiver9) | 如果操作成功，则返回ImageReceiver实例。 | 7626 7627**错误码：** 7628 7629以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7630 7631| 错误码ID | 错误信息 | 7632| ------- | --------------------------------------------| 7633| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 7634 7635**示例：** 7636 7637```ts 7638let size: image.Size = { 7639 height: 8192, 7640 width: 8 7641} 7642let receiver: image.ImageReceiver = image.createImageReceiver(size, image.ImageFormat.JPEG, 8); 7643``` 7644 7645## image.createImageReceiver<sup>(deprecated)</sup> 7646 7647createImageReceiver(width: number, height: number, format: number, capacity: number): ImageReceiver 7648 7649通过宽、高、图片格式、容量创建ImageReceiver实例。ImageReceiver做为图片的接收方、消费者，它的参数属性实际上不会对接收到的图片产生影响。图片属性的配置应在发送方、生产者进行，如相机预览流[createPreviewOutput](../apis-camera-kit/arkts-apis-camera-CameraManager.md#createpreviewoutput)。 7650 7651> **说明：** 7652> 7653> 从API version 11开始不再维护，建议使用[createImageReceiver](#imagecreateimagereceiver11)代替。 7654 7655**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7656 7657**参数：** 7658 7659| 参数名 | 类型 | 必填 | 说明 | 7660| -------- | ------ | ---- | ---------------------- | 7661| width | number | 是 | 图像的默认宽度。单位：像素。该参数不会影响接收到的图片宽度，实际宽度由生产者决定，如相机。 | 7662| height | number | 是 | 图像的默认高度。单位：像素。该参数不会影响接收到的图片高度，实际高度由生产者决定，如相机。 | 7663| format | number | 是 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机）。 | 7664| capacity | number | 是 | 同时访问的最大图像数。 | 7665 7666**返回值：** 7667 7668| 类型 | 说明 | 7669| -------------------------------- | --------------------------------------- | 7670| [ImageReceiver](#imagereceiver9) | 如果操作成功，则返回ImageReceiver实例。 | 7671 7672**示例：** 7673 7674```ts 7675let receiver: image.ImageReceiver = image.createImageReceiver(8192, 8, image.ImageFormat.JPEG, 8); 7676``` 7677 7678## ImageReceiver<sup>9+</sup> 7679 7680图像接收类，用于获取组件surface id，接收最新的图片和读取下一张图片，以及释放ImageReceiver实例。ImageReceiver做为图片的接收方、消费者，它的参数属性实际上不会对接收到的图片产生影响。图片属性的配置应在发送方、生产者进行，如相机预览流[createPreviewOutput](../apis-camera-kit/arkts-apis-camera-CameraManager.md#createpreviewoutput)。 7681 7682在调用以下方法前需要先创建ImageReceiver实例。 7683 7684### 属性 7685 7686**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7687 7688| 名称 | 类型 | 只读 | 可选 | 说明 | 7689| -------- | ---------------------------- | ---- | ---- | ------------------ | 7690| size | [Size](#size) | 是 | 否 | 图片大小。该参数不会影响接收到的图片大小，实际返回大小由生产者决定，如相机。 | 7691| capacity | number | 是 | 否 | 同时访问的图像数。 | 7692| format | [ImageFormat](#imageformat9) | 是 | 否 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机） | 7693 7694### getReceivingSurfaceId<sup>9+</sup> 7695 7696getReceivingSurfaceId(callback: AsyncCallback\<string>): void 7697 7698用于获取一个surface id供Camera或其他组件使用。使用callback返回结果。 7699 7700**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7701 7702**参数：** 7703 7704| 参数名 | 类型 | 必填 | 说明 | 7705| -------- | ---------------------- | ---- | -------------------------- | 7706| callback | AsyncCallback\<string> | 是 | 回调函数，当获取surface id成功，err为undefined，data为获取到的surface id；否则为错误对象。 | 7707 7708**示例:** 7709 7710```ts 7711import { BusinessError } from '@kit.BasicServicesKit'; 7712 7713receiver.getReceivingSurfaceId((err: BusinessError, id: string) => { 7714 if (err) { 7715 console.error(`Failed to get the ReceivingSurfaceId.code ${err.code},message is ${err.message}`); 7716 } else { 7717 console.info('Succeeded in getting the ReceivingSurfaceId.'); 7718 } 7719}); 7720``` 7721 7722### getReceivingSurfaceId<sup>9+</sup> 7723 7724getReceivingSurfaceId(): Promise\<string> 7725 7726用于获取一个surface id供Camera或其他组件使用。使用promise返回结果。 7727 7728**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7729 7730**返回值：** 7731 7732| 类型 | 说明 | 7733| ---------------- | -------------------- | 7734| Promise\<string> | Promise对象，返回surface id。 | 7735 7736**示例：** 7737 7738```ts 7739import { BusinessError } from '@kit.BasicServicesKit'; 7740 7741receiver.getReceivingSurfaceId().then((id: string) => { 7742 console.info('Succeeded in getting the ReceivingSurfaceId.'); 7743}).catch((error: BusinessError) => { 7744 console.error(`Failed to get the ReceivingSurfaceId.code ${error.code},message is ${error.message}`); 7745}) 7746``` 7747 7748### readLatestImage<sup>9+</sup> 7749 7750readLatestImage(callback: AsyncCallback\<Image>): void 7751 7752从ImageReceiver读取最新的图片，并使用callback返回结果。 7753 7754**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7755 7756**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7757 7758**参数：** 7759 7760| 参数名 | 类型 | 必填 | 说明 | 7761| -------- | ------------------------------- | ---- | ------------------------ | 7762| callback | AsyncCallback<[Image](#image9)> | 是 | 回调函数，当读取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 7763 7764**示例：** 7765 7766```ts 7767import { BusinessError } from '@kit.BasicServicesKit'; 7768 7769receiver.readLatestImage((err: BusinessError, img: image.Image) => { 7770 if (err) { 7771 console.error(`Failed to read the latest Image.code ${err.code},message is ${err.message}`); 7772 } else { 7773 console.info('Succeeded in reading the latest Image.'); 7774 } 7775}); 7776``` 7777 7778### readLatestImage<sup>9+</sup> 7779 7780readLatestImage(): Promise\<Image> 7781 7782从ImageReceiver读取最新的图片，并使用promise返回结果。 7783 7784**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7785 7786**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7787 7788**返回值：** 7789 7790| 类型 | 说明 | 7791| ------------------------- | ------------------ | 7792| Promise<[Image](#image9)> | Promise对象，返回最新图片。 | 7793 7794**示例：** 7795 7796```ts 7797import { BusinessError } from '@kit.BasicServicesKit'; 7798 7799receiver.readLatestImage().then((img: image.Image) => { 7800 console.info('Succeeded in reading the latest Image.'); 7801}).catch((error: BusinessError) => { 7802 console.error(`Failed to read the latest Image.code ${error.code},message is ${error.message}`); 7803}) 7804``` 7805 7806### readNextImage<sup>9+</sup> 7807 7808readNextImage(callback: AsyncCallback\<Image>): void 7809 7810从ImageReceiver读取下一张图片，并使用callback返回结果。 7811 7812**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7813 7814**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7815 7816**参数：** 7817 7818| 参数名 | 类型 | 必填 | 说明 | 7819| -------- | ------------------------------- | ---- | -------------------------- | 7820| callback | AsyncCallback<[Image](#image9)> | 是 | 回调函数，当获取下一张图片成功，err为undefined，data为获取到的下一张图片；否则为错误对象。 | 7821 7822**示例：** 7823 7824```ts 7825import { BusinessError } from '@kit.BasicServicesKit'; 7826 7827receiver.readNextImage((err: BusinessError, img: image.Image) => { 7828 if (err) { 7829 console.error(`Failed to read the next Image.code ${err.code},message is ${err.message}`); 7830 } else { 7831 console.info('Succeeded in reading the next Image.'); 7832 } 7833}); 7834``` 7835 7836### readNextImage<sup>9+</sup> 7837 7838readNextImage(): Promise\<Image> 7839 7840从ImageReceiver读取下一张图片，并使用promise返回结果。 7841 7842**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7843 7844**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7845 7846**返回值：** 7847 7848| 类型 | 说明 | 7849| ------------------------- | -------------------- | 7850| Promise<[Image](#image9)> | Promise对象，返回下一张图片。 | 7851 7852**示例：** 7853 7854```ts 7855import { BusinessError } from '@kit.BasicServicesKit'; 7856 7857receiver.readNextImage().then((img: image.Image) => { 7858 console.info('Succeeded in reading the next Image.'); 7859}).catch((error: BusinessError) => { 7860 console.error(`Failed to read the next Image.code ${error.code},message is ${error.message}`); 7861}) 7862``` 7863 7864### on<sup>9+</sup> 7865 7866on(type: 'imageArrival', callback: AsyncCallback\<void>): void 7867 7868接收图片时注册回调。 7869 7870**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7871 7872**参数：** 7873 7874| 参数名 | 类型 | 必填 | 说明 | 7875| -------- | -------------------- | ---- | ------------------------------------------------------ | 7876| type | string | 是 | 注册事件的类型，固定为'imageArrival'，接收图片时触发。 | 7877| callback | AsyncCallback\<void> | 是 | 回调函数，当注册事件触发成功，err为undefined，否则为错误对象。 | 7878 7879**示例：** 7880 7881```ts 7882receiver.on('imageArrival', () => { 7883 // image arrival, do something. 7884}) 7885``` 7886 7887### off<sup>13+</sup> 7888 7889off(type: 'imageArrival', callback?: AsyncCallback\<void>): void 7890 7891释放buffer时移除注册回调。 7892 7893**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7894 7895**参数：** 7896 7897| 参数名 | 类型 | 必填 | 说明 | 7898| -------- | -------------------- |----|----------------------------------------| 7899| type | string | 是 | 注册事件的类型，固定为'imageArrival'，释放buffer时触发。 | 7900| callback | AsyncCallback\<void> | 否 | 移除的回调函数。 | 7901 7902**示例：** 7903 7904```ts 7905let callbackFunc = ()=>{ 7906 // do something. 7907} 7908receiver.on('imageArrival', callbackFunc) 7909receiver.off('imageArrival', callbackFunc) 7910``` 7911 7912### release<sup>9+</sup> 7913 7914release(callback: AsyncCallback\<void>): void 7915 7916释放ImageReceiver实例并使用回调返回结果。 7917 7918ArkTS有内存回收机制，ImageReceiver对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7919 7920**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7921 7922**参数：** 7923 7924| 参数名 | 类型 | 必填 | 说明 | 7925| -------- | -------------------- | ---- | ------------------------ | 7926| callback | AsyncCallback\<void> | 是 | 回调函数，当释放ImageReceiver实例成功，err为undefined，否则为错误对象。 | 7927 7928**示例：** 7929 7930```ts 7931import { BusinessError } from '@kit.BasicServicesKit'; 7932 7933receiver.release((err: BusinessError) => { 7934 if (err) { 7935 console.error(`Failed to release the receiver.code ${err.code},message is ${err.message}`); 7936 } else { 7937 console.info('Succeeded in releasing the receiver.'); 7938 } 7939}) 7940``` 7941 7942### release<sup>9+</sup> 7943 7944release(): Promise\<void> 7945 7946释放ImageReceiver实例并使用promise返回结果。 7947 7948ArkTS有内存回收机制，ImageReceiver对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7949 7950**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7951 7952**返回值：** 7953 7954| 类型 | 说明 | 7955| -------------- | ------------------ | 7956| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7957 7958**示例：** 7959 7960```ts 7961import { BusinessError } from '@kit.BasicServicesKit'; 7962 7963receiver.release().then(() => { 7964 console.info('Succeeded in releasing the receiver.'); 7965}).catch((error: BusinessError) => { 7966 console.error(`Failed to release the receiver.code ${error.code},message is ${error.message}`); 7967}) 7968``` 7969 7970## image.createImageCreator<sup>11+</sup> 7971 7972createImageCreator(size: Size, format: ImageFormat, capacity: number): ImageCreator 7973 7974通过图片大小、图片格式、容量创建ImageCreator实例。 7975 7976**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7977 7978**参数：** 7979 7980| 参数名 | 类型 | 必填 | 说明 | 7981| -------- | ------ | ---- | ---------------------- | 7982| size | [Size](#size) | 是 | 图像的默认大小。 | 7983| format | [ImageFormat](#imageformat9) | 是 | 图像格式，如YCBCR_422_SP，JPEG。 | 7984| capacity | number | 是 | 同时访问的最大图像数。 | 7985 7986**返回值：** 7987 7988| 类型 | 说明 | 7989| ------------------------------ | --------------------------------------- | 7990| [ImageCreator](#imagecreator9) | 如果操作成功，则返回ImageCreator实例。 | 7991 7992 7993**错误码：** 7994 7995以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7996 7997| 错误码ID | 错误信息 | 7998| ------- | --------------------------------------------| 7999| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 8000 8001**示例：** 8002 8003```ts 8004let size: image.Size = { 8005 height: 8192, 8006 width: 8 8007} 8008let creator: image.ImageCreator = image.createImageCreator(size, image.ImageFormat.JPEG, 8); 8009``` 8010 8011## image.createImageCreator<sup>(deprecated)</sup> 8012 8013createImageCreator(width: number, height: number, format: number, capacity: number): ImageCreator 8014 8015通过宽、高、图片格式、容量创建ImageCreator实例。 8016 8017> **说明：** 8018> 8019> 从API version 11开始不再维护，建议使用[createImageCreator](#imagecreateimagecreator11)代替。 8020 8021**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8022 8023**参数：** 8024 8025| 参数名 | 类型 | 必填 | 说明 | 8026| -------- | ------ | ---- | ---------------------- | 8027| width | number | 是 | 图像的默认宽度。单位：像素。 | 8028| height | number | 是 | 图像的默认高度。单位：像素。 | 8029| format | number | 是 | 图像格式，如YCBCR_422_SP，JPEG。 | 8030| capacity | number | 是 | 同时访问的最大图像数。 | 8031 8032**返回值：** 8033 8034| 类型 | 说明 | 8035| ------------------------------ | --------------------------------------- | 8036| [ImageCreator](#imagecreator9) | 如果操作成功，则返回ImageCreator实例。 | 8037 8038**示例：** 8039 8040```ts 8041let creator: image.ImageCreator = image.createImageCreator(8192, 8, image.ImageFormat.JPEG, 8); 8042``` 8043 8044## ImageCreator<sup>9+</sup> 8045 8046图像创建模块，用于请求图像数据区域，并开放给应用编译图像数据的能力。 8047在调用以下方法前需要先创建[ImageCreator](#imagecreator9)实例，ImageCreator不支持多线程。 8048 8049### 属性 8050 8051**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8052 8053| 名称 | 类型 | 只读 | 可选 | 说明 | 8054| -------- | ---------------------------- | ---- | ---- | ------------------ | 8055| capacity | number | 是 | 否 | 同时访问的图像数。 | 8056| format | [ImageFormat](#imageformat9) | 是 | 否 | 图像格式。 | 8057 8058### dequeueImage<sup>9+</sup> 8059 8060dequeueImage(callback: AsyncCallback\<Image>): void 8061 8062从空闲队列中获取buffer图片，用于绘制UI内容，并使用callback返回结果。 8063 8064**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8065 8066**参数：** 8067 8068| 参数名 | 类型 | 必填 | 说明 | 8069| ------------- | ---------------------------------------| ---- | -------------------- | 8070| callback | AsyncCallback\<[Image](#image9)> | 是 | 回调函数，当获取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 8071 8072**示例：** 8073 8074```ts 8075import { BusinessError } from '@kit.BasicServicesKit'; 8076 8077creator.dequeueImage((err: BusinessError, img: image.Image) => { 8078 if (err) { 8079 console.error(`Failed to dequeue the Image.code ${err.code},message is ${err.message}`); 8080 } else { 8081 console.info('Succeeded in dequeuing the Image.'); 8082 } 8083}); 8084``` 8085 8086### dequeueImage<sup>9+</sup> 8087 8088dequeueImage(): Promise\<Image> 8089 8090从空闲队列中获取buffer图片，用于绘制UI内容，并使用promise返回结果。 8091 8092**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8093 8094**返回值：** 8095 8096| 类型 | 说明 | 8097| --------------- | ------------- | 8098| Promise\<[Image](#image9)> | Promise对象，返回最新图片。 | 8099 8100**示例：** 8101 8102```ts 8103import { BusinessError } from '@kit.BasicServicesKit'; 8104 8105creator.dequeueImage().then((img: image.Image) => { 8106 console.info('Succeeded in dequeuing the Image.'); 8107}).catch((error: BusinessError) => { 8108 console.error(`Failed to dequeue the Image.code ${error.code},message is ${error.message}`); 8109}) 8110``` 8111 8112### queueImage<sup>9+</sup> 8113 8114queueImage(interface: Image, callback: AsyncCallback\<void>): void 8115 8116将绘制好的图片放入队列，并使用callback返回结果。 8117 8118**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8119 8120**参数：** 8121 8122| 参数名 | 类型 | 必填 | 说明 | 8123| ------------- | -------------------------| ---- | -------------------- | 8124| interface | [Image](#image9) | 是 | 绘制好的buffer图像。 | 8125| callback | AsyncCallback\<void> | 是 | 回调函数，当将图片放入队列成功，err为undefined，否则为错误对象。 | 8126 8127**示例：** 8128 8129```ts 8130import { BusinessError } from '@kit.BasicServicesKit'; 8131 8132creator.dequeueImage().then((img: image.Image) => { 8133 //绘制图片。 8134 img.getComponent(4).then((component : image.Component) => { 8135 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 8136 for (let i = 0; i < bufferArr.length; i += 4) { 8137 bufferArr[i] = 0; //B 8138 bufferArr[i + 1] = 0; //G 8139 bufferArr[i + 2] = 255; //R 8140 bufferArr[i + 3] = 255; //A 8141 } 8142 }) 8143 creator.queueImage(img, (err: BusinessError) => { 8144 if (err) { 8145 console.error(`Failed to queue the Image.code ${err.code},message is ${err.message}`); 8146 } else { 8147 console.info('Succeeded in queuing the Image.'); 8148 } 8149 }) 8150}) 8151 8152``` 8153 8154### queueImage<sup>9+</sup> 8155 8156queueImage(interface: Image): Promise\<void> 8157 8158将绘制好的图片放入队列，并使用promise返回结果。 8159 8160**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8161 8162**参数：** 8163 8164| 参数名 | 类型 | 必填 | 说明 | 8165| ------------- | --------| ---- | ------------------- | 8166| interface | [Image](#image9) | 是 | 绘制好的buffer图像。 | 8167 8168**返回值：** 8169 8170| 类型 | 说明 | 8171| -------------- | ------------- | 8172| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 8173 8174**示例：** 8175 8176```ts 8177import { BusinessError } from '@kit.BasicServicesKit'; 8178 8179creator.dequeueImage().then((img: image.Image) => { 8180 //绘制图片。 8181 img.getComponent(4).then((component: image.Component) => { 8182 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 8183 for (let i = 0; i < bufferArr.length; i += 4) { 8184 bufferArr[i] = 0; //B 8185 bufferArr[i + 1] = 0; //G 8186 bufferArr[i + 2] = 255; //R 8187 bufferArr[i + 3] = 255; //A 8188 } 8189 }) 8190 creator.queueImage(img).then(() => { 8191 console.info('Succeeded in queuing the Image.'); 8192 }).catch((error: BusinessError) => { 8193 console.error(`Failed to queue the Image.code ${error.code},message is ${error.message}`); 8194 }) 8195}) 8196 8197``` 8198 8199### on<sup>9+</sup> 8200 8201on(type: 'imageRelease', callback: AsyncCallback\<void>): void 8202 8203监听imageRelease事件，并使用callback返回结果。 8204 8205**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8206 8207**参数：** 8208 8209| 参数名 | 类型 | 必填 | 说明 | 8210| ------------- | -------------------------| ---- | -------------------- | 8211| type | string | 是 | 监听事件类型，如'imageRelease'。 | 8212| callback | AsyncCallback\<void> | 是 | 回调函数，当监听事件触发成功，err为undefined，否则为错误对象。 | 8213 8214**示例：** 8215 8216```ts 8217import { BusinessError } from '@kit.BasicServicesKit'; 8218 8219creator.on('imageRelease', (err: BusinessError) => { 8220 if (err) { 8221 console.error(`Failed to get the imageRelease callback.code ${err.code},message is ${err.message}`); 8222 } else { 8223 console.info('Succeeded in getting imageRelease callback.'); 8224 } 8225}) 8226``` 8227 8228### off<sup>13+</sup> 8229 8230off(type: 'imageRelease', callback?: AsyncCallback\<void>): void 8231 8232释放buffer时，移除注册的回调函数。 8233 8234**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8235 8236**参数：** 8237 8238| 参数名 | 类型 | 必填 | 说明 | 8239| ------------- | -------------------------|----|--------------------------------------------| 8240| type | string | 是 | 监听事件类型，如'imageRelease'。 | 8241| callback | AsyncCallback\<void> | 否 | 将被移除的回调函数。 | 8242 8243**示例：** 8244 8245```ts 8246let callbackFunc = ()=>{ 8247 // do something. 8248} 8249creator.on('imageRelease', callbackFunc) 8250creator.off('imageRelease', callbackFunc) 8251``` 8252 8253### release<sup>9+</sup> 8254 8255release(callback: AsyncCallback\<void>): void 8256 8257释放当前图像，并使用callback返回结果。 8258 8259ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 8260 8261**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8262 8263**参数：** 8264 8265| 参数名 | 类型 | 必填 | 说明 | 8266| ------------- | -------------------------| ---- | -------------------- | 8267| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 8268 8269**示例：** 8270 8271```ts 8272import { BusinessError } from '@kit.BasicServicesKit'; 8273 8274creator.release((err: BusinessError) => { 8275 if (err) { 8276 console.error(`Failed to release the creator.code ${err.code},message is ${err.message}`); 8277 } else { 8278 console.info('Succeeded in releasing creator.'); 8279 } 8280}); 8281``` 8282### release<sup>9+</sup> 8283 8284release(): Promise\<void> 8285 8286释放当前图像，并使用promise返回结果。 8287 8288ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 8289 8290**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 8291 8292**返回值：** 8293 8294| 类型 | 说明 | 8295| -------------- | ------------- | 8296| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 8297 8298**示例：** 8299 8300```ts 8301import { BusinessError } from '@kit.BasicServicesKit'; 8302 8303creator.release().then(() => { 8304 console.info('Succeeded in releasing creator.'); 8305}).catch((error: BusinessError) => { 8306 console.error(`Failed to release the creator.code ${error.code},message is ${error.message}`); 8307}) 8308``` 8309 8310## Image<sup>9+</sup> 8311 8312提供基本的图像操作，包括获取图像信息、读写图像数据。调用[readNextImage](#readnextimage9)和[readLatestImage](#readlatestimage9)接口时会返回image。 8313 8314### 属性 8315 8316**系统能力：** SystemCapability.Multimedia.Image.Core 8317 8318| 名称 | 类型 | 只读 | 可选 | 说明 | 8319| -------- | ------------------ | ---- | ---- | -------------------------------------------------- | 8320| clipRect | [Region](#region8) | 是 | 是 | 要裁剪的图像区域。 | 8321| 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)。 | 8322| format | number | 是 | 否 | 图像格式，参考[OH_NativeBuffer_Format](../apis-arkgraphics2d/capi-native-buffer-h.md#oh_nativebuffer_format)。 | 8323| timestamp<sup>12+</sup> | number | 是 | 否 | 图像时间戳。时间戳以纳秒为单位，通常是单调递增的。时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。如果要获取某张照片的生成时间，可以通过[getImageProperty](#getimageproperty11)接口读取相关的EXIF信息。| 8324 8325### getComponent<sup>9+</sup> 8326 8327getComponent(componentType: ComponentType, callback: AsyncCallback\<Component>): void 8328 8329根据图像的组件类型从图像中获取组件缓存并使用callback返回结果。 8330 8331**系统能力：** SystemCapability.Multimedia.Image.Core 8332 8333**参数：** 8334 8335| 参数名 | 类型 | 必填 | 说明 | 8336| ------------- | --------------------------------------- | ---- | -------------------- | 8337| componentType | [ComponentType](#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机） | 8338| callback | AsyncCallback<[Component](#component9)> | 是 | 回调函数，当返回组件缓冲区成功，err为undefined，data为获取到的组件缓冲区；否则为错误对象。 | 8339 8340**示例：** 8341 8342```ts 8343import { BusinessError } from '@kit.BasicServicesKit'; 8344 8345img.getComponent(4, (err: BusinessError, component: image.Component) => { 8346 if (err) { 8347 console.error(`Failed to get the component.code ${err.code},message is ${err.message}`); 8348 } else { 8349 console.info('Succeeded in getting component.'); 8350 } 8351}) 8352``` 8353 8354### getComponent<sup>9+</sup> 8355 8356getComponent(componentType: ComponentType): Promise\<Component> 8357 8358根据图像的组件类型从图像中获取组件缓存并使用Promise方式返回结果。 8359 8360**系统能力：** SystemCapability.Multimedia.Image.Core 8361 8362**参数：** 8363 8364| 参数名 | 类型 | 必填 | 说明 | 8365| ------------- | -------------------------------- | ---- | ---------------- | 8366| componentType | [ComponentType](#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机）。 | 8367 8368**返回值：** 8369 8370| 类型 | 说明 | 8371| --------------------------------- | --------------------------------- | 8372| Promise<[Component](#component9)> | Promise对象，返回组件缓冲区。 | 8373 8374**示例：** 8375 8376```ts 8377import { BusinessError } from '@kit.BasicServicesKit'; 8378 8379img.getComponent(4).then((component: image.Component) => { 8380 console.info('Succeeded in getting component.'); 8381}).catch((error: BusinessError) => { 8382 console.error(`Failed to get the component.code ${error.code},message is ${error.message}`); 8383}) 8384``` 8385 8386### release<sup>9+</sup> 8387 8388release(callback: AsyncCallback\<void>): void 8389 8390释放当前图像并使用callback返回结果。 8391 8392在接收另一个图像前必须先释放对应资源。 8393 8394ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 8395 8396**系统能力：** SystemCapability.Multimedia.Image.Core 8397 8398**参数：** 8399 8400| 参数名 | 类型 | 必填 | 说明 | 8401| -------- | -------------------- | ---- | -------------- | 8402| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 8403 8404**示例：** 8405 8406```ts 8407import { BusinessError } from '@kit.BasicServicesKit'; 8408 8409img.release((err: BusinessError) => { 8410 if (err) { 8411 console.error(`Failed to release the image instance.code ${err.code},message is ${err.message}`); 8412 } else { 8413 console.info('Succeeded in releasing the image instance.'); 8414 } 8415}) 8416``` 8417 8418### release<sup>9+</sup> 8419 8420release(): Promise\<void> 8421 8422释放当前图像并使用Promise方式返回结果。 8423 8424在接收另一个图像前必须先释放对应资源。 8425 8426ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 8427 8428**系统能力：** SystemCapability.Multimedia.Image.Core 8429 8430**返回值：** 8431 8432| 类型 | 说明 | 8433| -------------- | --------------------- | 8434| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 8435 8436**示例：** 8437 8438```ts 8439import { BusinessError } from '@kit.BasicServicesKit'; 8440 8441img.release().then(() => { 8442 console.info('Succeeded in releasing the image instance.'); 8443}).catch((error: BusinessError) => { 8444 console.error(`Failed to release the image instance.code ${error.code},message is ${error.message}`); 8445}) 8446``` 8447 8448## PositionArea<sup>7+</sup> 8449 8450表示图片指定区域内的数据。 8451 8452**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8453 8454**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8455 8456**系统能力：** SystemCapability.Multimedia.Image.Core 8457 8458| 名称 | 类型 | 只读| 可选| 说明 | 8459| ------ | ------------------ | ---| -----|------------------------------------------------------- | 8460| pixels | ArrayBuffer | 否 | 否 | 像素。仅支持BGRA_8888格式的图像像素数据。 | 8461| offset | number | 否 | 否 | 偏移量。单位：字节。 | 8462| stride | number | 否 | 否 | 跨距，内存中每行像素所占的空间。stride >= region.size.width*4。 | 8463| region | [Region](#region8) | 否 | 否 |区域，按照区域读写。写入的区域宽度加X坐标不能大于原图的宽度，写入的区域高度加Y坐标不能大于原图的高度。 | 8464 8465## ImageInfo 8466 8467表示图片信息。 8468 8469**系统能力：** SystemCapability.Multimedia.Image.Core 8470 8471| 名称 | 类型 | 只读 | 可选 | 说明 | 8472| ---- | ------------- | --- |-----|---------- | 8473| size<sup>6+</sup> | [Size](#size) | 否 | 否 |图片大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8474| density<sup>9+</sup> | number | 否 | 否 |像素密度，单位为ppi。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8475| stride<sup>11+</sup> | number | 否 | 否 | 跨距，内存中每行像素所占的空间。stride >= region.size.width*4 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8476| pixelFormat<sup>12+</sup> | [PixelMapFormat](#pixelmapformat7) | 否 | 否 | 像素格式。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8477| alphaType<sup>12+</sup> | [AlphaType](#alphatype9) | 否 | 否 |透明度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8478| mimeType<sup>12+</sup> | string | 否 | 否 |图片真实格式（MIME type）。 | 8479| isHdr<sup>12+</sup> | boolean | 否 | 否 | true表示图片为高动态范围（HDR），false表示图片非高动态范围（SDR）。对于[ImageSource](#imagesource)，代表源图片是否为HDR；对于[PixelMap](#pixelmap7)，代表解码后的pixelmap是否为HDR。 | 8480 8481## Size 8482 8483表示图片尺寸。 8484 8485**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8486 8487**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8488 8489**系统能力：** SystemCapability.Multimedia.Image.Core 8490 8491| 名称 | 类型 | 只读 | 可选 |说明 | 8492| ------ | ------ | -- |-----| -------------- | 8493| height | number | 否 | 否 |输出图片的高，单位：像素。 | 8494| width | number | 否 | 否 | 输出图片的宽，单位：像素。 | 8495 8496## PixelMapFormat<sup>7+</sup> 8497 8498枚举，图片像素格式。 8499 8500**系统能力：** SystemCapability.Multimedia.Image.Core 8501 8502| 名称 | 值 | 说明 | 8503| ---------------------- | ------ | ----------------- | 8504| UNKNOWN | 0 | 未知格式。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8505| ARGB_8888<sup>18+</sup> | 1 | 颜色信息由透明度（Alpha）与R（Red），G（Green），B（Blue）四部分组成，每个部分占8位，总共占32位。 该格式当前仅支持PixelMap的接口。| 8506| RGB_565 | 2 | 颜色信息由R（Red），G（Green），B（Blue）三部分组成，R占5位，G占6位，B占5位，总共占16位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8507| RGBA_8888 | 3 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，每个部分占8位，总共占32位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8508| BGRA_8888<sup>9+</sup> | 4 | 颜色信息由B（Blue），G（Green），R（Red）与透明度（Alpha）四部分组成，每个部分占8位，总共占32位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8509| RGB_888<sup>9+</sup> | 5 | 颜色信息由R（Red），G（Green），B（Blue）三部分组成，每个部分占8位，总共占24位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8510| ALPHA_8<sup>9+</sup> | 6 | 颜色信息仅包含透明度（Alpha），每个像素占8位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8511| RGBA_F16<sup>9+</sup> | 7 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，每个部分占16位，总共占64位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8512| NV21<sup>9+</sup> | 8 | YVU像素排列，V分量在U分量之前。颜色信息由亮度分量Y和交错排列的色度分量V和U组成，其中Y分量占8位，UV分量因4：2：0采样平均占4位，总共平均占12位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8513| NV12<sup>9+</sup> | 9 | YVU像素排列，U分量在V分量之前。颜色信息由亮度分量Y和交错排列的色度分量U和V组成，其中Y分量占8位，UV分量因4：2：0采样平均占4位，总共平均占12位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8514| RGBA_1010102<sup>12+</sup> | 10 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，其中R、G、B分别占10位，透明度占2位，总共占32位。 | 8515| YCBCR_P010<sup>12+</sup> | 11 | 颜色信息由亮度分量Y和色度分量Cb与Cr组成，每个分量有效10位，实际存储时，Y平面每个像素占16位数据（10位有效），UV平面交错排列，每4个像素占32位数据（每色度分量10位有效），平均有效占15位。 8516| YCRCB_P010<sup>12+</sup> | 12 | 颜色信息由亮度分量Y和色度分量Cr与Cb组成，每个分量有效10位，实际存储时，Y平面每个像素占16位数据（10位有效），UV平面交错排列，每4个像素占32位数据（每色度分量10位有效），平均有效占15位。 | 8517| ASTC_4x4<sup>18+</sup> | 102 | 存储格式为 ASTC 4x4 格式，内存使用量仅为 RGBA_8888 的 1/4。该格式仅用于直接显示场景，不支持像素访问或后期处理编辑。 | 8518 8519## AlphaType<sup>9+</sup> 8520 8521枚举，图像的透明度类型。 8522 8523**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8524 8525**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8526 8527**系统能力：** SystemCapability.Multimedia.Image.Core 8528 8529| 名称 | 值 | 说明 | 8530| -------- | ------ | ----------------------- | 8531| UNKNOWN | 0 | 未知透明度。 | 8532| OPAQUE | 1 | 没有alpha或图片不透明。 | 8533| PREMUL | 2 | RGB预乘alpha。 | 8534| UNPREMUL | 3 | RGB非预乘alpha。 | 8535 8536## AuxiliaryPictureType<sup>13+</sup> 8537 8538枚举，辅助图的图像类型。 8539 8540**系统能力：** SystemCapability.Multimedia.Image.Core 8541 8542| 名称 | 值 | 说明 | 8543| ------------- | ---- | ------------ | 8544| GAINMAP | 1 | 增益图，代表了一种增强SDR图像以产生具有可变显示调整能力的HDR图像的机制。它是一组描述如何应用gainmap元数据的组合。 | 8545| DEPTH_MAP | 2 | 深度图，储存图像的深度数据，通过捕捉每个像素与摄像机之间的距离，提供场景的三维结构信息，通常用于3D重建和场景理解。 | 8546| UNREFOCUS_MAP | 3 | 人像未对焦的原图，提供了一种在人像拍摄中突出背景模糊效果的方式，能够帮助用户在后期处理中选择焦点区域，增加创作自由度。 | 8547| LINEAR_MAP | 4 | 线性图，用于提供额外的数据视角或补充信息，通常用于视觉效果的增强，它可以包含场景中光照、颜色或其他视觉元素的线性表示。 | 8548| FRAGMENT_MAP | 5 | 水印裁剪图，表示在原图中被水印覆盖的区域，该图像用于修复或移除水印影响，恢复图像的完整性和可视性。 | 8549 8550## AuxiliaryPictureInfo<sup>13+</sup> 8551 8552表示辅助图图像信息。 8553 8554**系统能力：** SystemCapability.Multimedia.Image.Core 8555 8556| 名称 | 类型 | 只读 | 可选 | 说明 | 8557| ------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 8558| auxiliaryPictureType | [AuxiliaryPictureType](#auxiliarypicturetype13) | 否 | 否 | 辅助图的图像类型。 | 8559| size | [Size](#size) | 否 | 否 | 图片大小。 | 8560| rowStride | number | 否 | 否 | 行距。 | 8561| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 否 | 像素格式。 | 8562| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 否 | 否 | 目标色彩空间。 | 8563 8564## MetadataType<sup>13+</sup> 8565 8566枚举，图片元数据类型。 8567 8568**系统能力：** SystemCapability.Multimedia.Image.Core 8569 8570| 名称 | 值 | 说明 | 8571| ----------------- | ---- | ------------------ | 8572| EXIF_METADATA | 1 | exif数据。 | 8573| FRAGMENT_METADATA | 2 | 水印裁剪图元数据。 | 8574 8575## ScaleMode<sup>9+</sup> 8576 8577枚举，图像的缩放模式。 8578 8579**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8580 8581**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8582 8583**系统能力：** SystemCapability.Multimedia.Image.Core 8584 8585| 名称 | 值 | 说明 | 8586| --------------- | ------ | -------------------------------------------------- | 8587| CENTER_CROP | 1 | 缩放图像以填充目标图像区域并居中裁剪区域外的效果。 | 8588| FIT_TARGET_SIZE | 0 | 图像适合目标尺寸的效果。 | 8589 8590## SourceOptions<sup>9+</sup> 8591 8592ImageSource的初始化选项。 8593 8594**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8595 8596**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8597 8598**系统能力：** SystemCapability.Multimedia.Image.Core 8599 8600| 名称 | 类型 | 只读 | 可选 | 说明 | 8601| ----------------- | ---------------------------------- | ---- | ---- | ------------------ | 8602| sourceDensity | number | 否 | 否 | 图片资源像素密度，单位为ppi。<br>在解码参数[DecodingOptions](#decodingoptions7)未设置desiredSize的前提下，当前参数SourceOptions.sourceDensity与DecodingOptions.fitDensity非零时将对解码输出的pixelmap进行缩放。<br>缩放后宽计算公式如下(高同理)：(width * fitDensity + (sourceDensity >> 1)) / sourceDensity。| 8603| sourcePixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 图片像素格式，默认值为UNKNOWN。 | 8604| sourceSize | [Size](#size) | 否 | 是 | 图像像素大小，默认值为空。 | 8605 8606 8607## InitializationOptions<sup>8+</sup> 8608 8609PixelMap的初始化选项。 8610 8611**系统能力：** SystemCapability.Multimedia.Image.Core 8612 8613| 名称 | 类型 | 只读 |可选 | 说明 | 8614| ------------------------ | ---------------------------------- | ----| -----| -------------- | 8615| alphaType<sup>9+</sup> | [AlphaType](#alphatype9) | 否 | 是| 透明度。默认值为IMAGE_ALPHA_TYPE_PREMUL。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8616| editable | boolean | 否 | 是| true表示可编辑，false表示不可编辑。默认值为false。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。| 8617| srcPixelFormat<sup>12+</sup> | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 传入的buffer数据的像素格式。默认值为BGRA_8888。| 8618| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是| 生成的pixelMap的像素格式。默认值为RGBA_8888。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8619| scaleMode<sup>9+</sup> | [ScaleMode](#scalemode9) | 否 | 是 | 缩略值。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8620| size | [Size](#size) | 否 | 否|创建图片大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8621 8622## DecodingOptions<sup>7+</sup> 8623 8624图像解码设置选项。 8625 8626**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8627 8628| 名称 | 类型 | 只读 | 可选 | 说明 | 8629| ------------------ | ---------------------------------- | ---- | ---- | ---------------- | 8630| sampleSize | number | 否 | 是 | 缩略图采样大小，默认值为1。当前只能取1。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8631| rotate | number | 否 | 是 | 旋转角度。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8632| editable | boolean | 否 | 是 | true表示可编辑，false表示不可编辑。默认值为false。当取值为false时，图片不可二次编辑，如writepixels操作将失败。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8633| desiredSize | [Size](#size) | 否 | 是 | 期望输出大小，必须为正整数，若与原尺寸比例不一致，则会进行拉伸/缩放到指定尺寸，默认为原始尺寸。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8634| desiredRegion | [Region](#region8) | 否 | 是 | 解码图像中由Region指定的矩形区域，当原始图像很大而只需要解码图像的一部分时，可以设置该参数，有助于提升性能，默认为原始大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8635| desiredPixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 解码的像素格式。默认值为RGBA_8888。仅支持设置：RGBA_8888、BGRA_8888和RGB_565。有透明通道图片格式不支持设置RGB_565，如PNG、GIF、ICO和WEBP。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8636| index | number | 否 | 是 | 解码图片序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8637| fitDensity<sup>9+</sup> | number | 否 | 是 | 图像像素密度，单位为ppi。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8638| desiredColorSpace<sup>11+</sup> | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 否 | 是 | 目标色彩空间。默认值为UNKNOWN。 | 8639| desiredDynamicRange<sup>12+</sup> | [DecodingDynamicRange](#decodingdynamicrange12) | 否 | 是 | 目标动态范围，默认值为SDR。<br>通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource不支持设置此属性，默认解码为SDR内容。<br>如果平台不支持HDR，设置无效，默认解码为SDR内容。 | 8640| cropAndScaleStrategy<sup>18+</sup> | [CropAndScaleStrategy](#cropandscalestrategy18) | 否 | 是 | 解码参数如果同时设置desiredRegion与desiredSize，由此决定裁剪与缩放操作的先后策略。<br>仅支持设置：SCALE_FIRST、CROP_FIRST。 | 8641 8642## DecodingOptionsForPicture<sup>13+</sup> 8643 8644图像解码设置选项。 8645 8646**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8647 8648| 名称 | 类型 | 只读 | 可选 | 说明 | 8649| ------------------------ | ------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | 8650| desiredAuxiliaryPictures | Array\<[AuxiliaryPictureType](#auxiliarypicturetype13)> | 否 | 否 | 设置AuxiliaryPicture类型，默认解码所有AuxiliaryPicture类型。 | 8651 8652## Region<sup>8+</sup> 8653 8654表示区域信息。 8655 8656**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8657 8658**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8659 8660**系统能力：** SystemCapability.Multimedia.Image.Core 8661 8662| 名称 | 类型 | 只读 | 可选| 说明 | 8663| ---- | ------------- | ---- | ---- | ------------ | 8664| size<sup>7+</sup> | [Size](#size) | 否 | 否 | 区域大小。 | 8665| x<sup>7+</sup> | number | 否 | 否 | 区域左上角横坐标。单位：像素。 | 8666| y<sup>7+</sup> | number | 否 | 否 | 区域左上角纵坐标。单位：像素。 | 8667 8668## PackingOption 8669 8670表示图片编码选项。 8671 8672**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 8673 8674| 名称 | 类型 | 只读 | 可选 | 说明 | 8675| ------- | ------ | ---- | ---- | --------------------------------------------------- | 8676| format | string | 否 | 否 | 目标格式。</br>当前只支持"image/jpeg"、"image/webp"、"image/png"和"image/heic(或者image/heif)"<sup>12+</sup>、"image/sdr_astc_4x4"<sup>18+</sup>、"image/sdr_sut_superfast_4x4"<sup>18+</sup>（不同硬件设备支持情况不同）。<br>**说明：** 因为jpeg不支持透明通道，若使用带透明通道的数据编码jpeg格式，透明色将变为黑色。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8677| quality | number | 否 | 否 | 1. 编码中设定输出图片质量的参数，该参数仅对JPEG图片和HEIF图片生效。取值范围为0-100。0质量最低，100质量最高，质量越高生成图片所占空间越大。WebP、PNG等图片均为无损编码。<br> 2.sdr_astc_4x4编码中，可以设定输出图片质量的参数，可选参数：92、85。<br>3. sut编码中，设定输出图片质量可选参数：92。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8678| bufferSize<sup>9+</sup> | number | 否 | 是 | 接收编码数据的缓冲区大小，单位为Byte。如果不设置大小，默认为25M。如果编码图片超过25M，需要指定大小。bufferSize需大于编码后图片大小。使用[packToFile](#packtofile11)不受此参数限制。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8679| desiredDynamicRange<sup>12+</sup> | [PackingDynamicRange](#packingdynamicrange12) | 否 | 是 | 目标动态范围。默认值为SDR。 | 8680| needsPackProperties<sup>12+</sup> | boolean | 否 | 是 | 是否需要编码图片属性信息，例如EXIF。true表示需要，false表示不需要。默认值为false。 | 8681 8682## PackingOptionsForSequence<sup>18+</sup> 8683 8684描述动图编码参数的选项。 8685 8686**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 8687 8688| 名称 | 类型 | 只读 | 可选 | 说明 | 8689| ------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 8690| frameCount | number | 否 | 否 | GIF编码中指定的帧数。 | 8691| delayTimeList | Array\<number> | 否 | 否 | GIF编码中设定每帧输出图像的延迟时间，取值需大于0。<br>- 单位为10毫秒。例如，取值为10时，实际单帧延迟是100毫秒。<br>- 如果长度小于frameCount，不足的部分将使用delayTimeList中的最后一个值进行填充。 | 8692| disposalTypes | Array\<number> | 否 | 是 | GIF编码中设定每帧输出图像的帧过渡模式，如果长度小于frameCount，不足的部分将使用disposalTypes中的最后一个值进行填充，可取值如下：<br>- 0：不需要任何操作。<br>- 1：保持图形不变。<br>- 2：恢复背景色。<br>- 3：恢复到之前的状态。 | 8693| loopCount | number | 否 | 是 | 表示在GIF编码中输出图片循环播放次数，取值范围为[0，65535]。<br>0表示无限循环；若无此字段，则表示不循环播放。 | 8694 8695## ImagePropertyOptions<sup>11+</sup> 8696 8697表示查询图片属性的索引。 8698 8699**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8700 8701| 名称 | 类型 | 只读 | 可选 | 说明 | 8702| ------------ | ------ | ---- | ---- | ------------ | 8703| index | number | 否 | 是 | 图片序号。默认值为0。 | 8704| defaultValue | string | 否 | 是 | 默认属性值。默认值为空。 | 8705 8706## GetImagePropertyOptions<sup>(deprecated)</sup> 8707 8708表示查询图片属性的索引。 8709 8710> **说明：** 8711> 8712> 从API version 11开始不再维护，建议使用[ImagePropertyOptions](#imagepropertyoptions11)代替。 8713 8714**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8715 8716| 名称 | 类型 | 只读 | 可选 | 说明 | 8717| ------------ | ------ | ---- | ---- | ------------ | 8718| index | number | 否 | 是 | 图片序号。默认值为0。 | 8719| defaultValue | string | 否 | 是 | 默认属性值。默认值为空。 | 8720 8721## PropertyKey<sup>7+</sup> 8722 8723枚举，Exif（Exchangeable image file format）图片信息。 8724 8725**系统能力：** SystemCapability.Multimedia.Image.Core 8726 8727| 名称 | 值 | 说明 | 8728| ----------------- | ----------------------- |---------------------------| 8729| NEW_SUBFILE_TYPE <sup>12+</sup> | "NewSubfileType" | **读写能力：** 可读写<br> 在Exif中，"NewSubfileType"字段用于标识子文件的数据类型，如全分辨率图像、缩略图或多帧图像的一部分。其值是位掩码，0代表全分辨率图像，1代表缩略图，2代表多帧图像的一部分。| 8730| SUBFILE_TYPE <sup>12+</sup> | "SubfileType" | **读写能力：** 可读写<br> 此标签指示此子文件中的数据类型。标签已弃用，请使用NewSubfileType替代。| 8731| IMAGE_WIDTH | "ImageWidth" | **读写能力：** 可读写<br> 图片宽度。| 8732| IMAGE_LENGTH | "ImageLength" | **读写能力：** 可读写<br> 图片长度。| 8733| BITS_PER_SAMPLE | "BitsPerSample" | **读写能力：** 可读写<br> 像素各分量的位数，如RGB，3分量，格式是8, 8, 8。| 8734| COMPRESSION <sup>12+</sup> | "Compression" | **读写能力：** 可读写<br> 图像压缩方案。| 8735| PHOTOMETRIC_INTERPRETATION <sup>12+</sup> | "PhotometricInterpretation" | **读写能力：** 可读写<br> 像素构成，例如 RGB 或 YCbCr。| 8736| IMAGE_DESCRIPTION<sup>10+</sup> | "ImageDescription" | **读写能力：** 可读写<br> 图像信息描述。| 8737| MAKE<sup>10+</sup> | "Make" | **读写能力：** 可读写<br> 生产商。| 8738| MODEL<sup>10+</sup> | "Model" | **读写能力：** 可读写<br> 设备型号。| 8739| STRIP_OFFSETS <sup>12+</sup> | "StripOffsets" | **读写能力：** 可读写<br> 每个strip的字节偏移量。| 8740| ORIENTATION | "Orientation" | **读写能力：** 可读写<br> 图片方向。<br/> 1："Top-left"，图像未旋转。<br/> 2："Top-right"，镜像水平翻转。<br/> 3："Bottom-right"，图像旋转180°。<br/> 4："Bottom-left"，镜像垂直翻转。<br/> 5："Left-top"，镜像水平翻转再顺时针旋转270°。<br/> 6："Right-top"，顺时针旋转90°。<br/> 7："Right-bottom"，镜像水平翻转再顺时针旋转90°。<br/> 8："Left-bottom"，顺时针旋转270°。<br/> 如果读到未定义值会返回"Unknown Value 0"。获取该属性时会以字符串的形式返回。修改该属性时既可以以数字形式指定，也可以以字符串形式指定。| 8741| SAMPLES_PER_PIXEL <sup>12+</sup> | "SamplesPerPixel" | **读写能力：** 可读写<br> 每个像素的分量数。由于该标准适用于 RGB 和 YCbCr 图像，因此该标签的值设置为 3。在 JPEG 压缩数据中，使用 JPEG 标记代替该标签。| 8742| ROWS_PER_STRIP <sup>12+</sup> | "RowsPerStrip" | **读写能力：** 可读写<br> 每个strip的图像数据行数。| 8743| STRIP_BYTE_COUNTS <sup>12+</sup> | "StripByteCounts" | **读写能力：** 可读写<br> 每个图像数据带的总字节数。| 8744| X_RESOLUTION <sup>12+</sup> | "XResolution" | **读写能力：** 可读写<br> 图像宽度方向的分辨率。| 8745| Y_RESOLUTION <sup>12+</sup> | "YResolution" | **读写能力：** 可读写<br> 图像高度方向的分辨率。| 8746| PLANAR_CONFIGURATION <sup>12+</sup> | "PlanarConfiguration" | **读写能力：** 可读写<br> 表示像素组件的记录格式，chunky格式或是planar格式。| 8747| RESOLUTION_UNIT <sup>12+</sup> | "ResolutionUnit" | **读写能力：** 可读写<br> 用于测量XResolution和YResolution的单位。| 8748| TRANSFER_FUNCTION <sup>12+</sup> | "TransferFunction" | **读写能力：** 可读写<br> 图像的传递函数，通常用于颜色校正。| 8749| SOFTWARE <sup>12+</sup> | "Software" | **读写能力：** 可读写<br> 用于生成图像的软件的名称和版本。| 8750| DATE_TIME<sup>10+</sup> | "DateTime" | **读写能力：** 可读写<br> 日期时间。格式如2024:01:25 05:51:34。| 8751| ARTIST <sup>12+</sup> | "Artist" | **读写能力：** 可读写<br> 创建图像的用户名称。| 8752| WHITE_POINT <sup>12+</sup> | "WhitePoint" | **读写能力：** 可读写<br> 图像的白点色度。| 8753| PRIMARY_CHROMATICITIES <sup>12+</sup> | "PrimaryChromaticities" | **读写能力：** 可读写<br> 图像的主要颜色的色度。| 8754| PHOTO_MODE<sup>10+</sup> | "PhotoMode" | **读写能力：** 可读写<br> 拍照模式。| 8755| JPEG_INTERCHANGE_FORMAT <sup>12+</sup> | "JPEGInterchangeFormat" | **读写能力：** 只读<br> JPEG压缩缩略图数据开始字节（SOI）的偏移。| 8756| JPEG_INTERCHANGE_FORMAT_LENGTH <sup>12+</sup> | "JPEGInterchangeFormatLength" | **读写能力：** 只读<br> JPEG压缩缩略图数据的字节数。| 8757| YCBCR_COEFFICIENTS <sup>12+</sup> | "YCbCrCoefficients" | **读写能力：** 可读写<br> 从RGB到YCbCr图像数据的转换矩阵系数。| 8758| YCBCR_SUB_SAMPLING <sup>12+</sup> | "YCbCrSubSampling" | **读写能力：** 可读写<br> 色度分量与亮度分量的采样比率。| 8759| YCBCR_POSITIONING <sup>12+</sup> | "YCbCrPositioning" | **读写能力：** 可读写<br> 色度分量相对于亮度分量的位置。| 8760| REFERENCE_BLACK_WHITE <sup>12+</sup> | "ReferenceBlackWhite" | **读写能力：** 可读写<br> 参考黑点值和参考白点值。| 8761| COPYRIGHT <sup>12+</sup> | "Copyright" | **读写能力：** 可读写<br> 图像的版权信息。| 8762| EXPOSURE_TIME<sup>9+</sup> | "ExposureTime" | **读写能力：** 可读写<br> 曝光时间，例如1/33 sec。| 8763| F_NUMBER<sup>9+</sup> | "FNumber" | **读写能力：** 可读写<br> 光圈值，例如f/1.8。| 8764| EXPOSURE_PROGRAM <sup>12+</sup> | "ExposureProgram" | **读写能力：** 可读写<br> 拍照时相机用来设置曝光的程序的类别。| 8765| SPECTRAL_SENSITIVITY <sup>12+</sup> | "SpectralSensitivity" | **读写能力：** 可读写<br> 表示所用相机的每个通道的光谱灵敏度。| 8766| GPS_VERSION_ID <sup>12+</sup> | "GPSVersionID" | **读写能力：** 可读写<br> GPSInfoIFD的版本。| 8767| GPS_LATITUDE_REF | "GPSLatitudeRef" | **读写能力：** 可读写<br> 纬度引用，例如N或S。| 8768| GPS_LATITUDE | "GPSLatitude" | **读写能力：** 可读写<br> 图片纬度。修改时应按"度,分,秒"格式传入，如"39,54,7.542"| 8769| GPS_LONGITUDE_REF | "GPSLongitudeRef" | **读写能力：** 可读写<br> 经度引用，例如W或E。| 8770| GPS_LONGITUDE | "GPSLongitude" | **读写能力：** 可读写<br> 图片经度。修改时应按"度,分,秒"格式传入，如"116,19,42.16"| 8771| GPS_ALTITUDE_REF <sup>12+</sup> | "GPSAltitudeRef" | **读写能力：** 可读写<br> 用于GPS高度的参照高度。| 8772| GPS_ALTITUDE <sup>12+</sup> | "GPSAltitude" | **读写能力：** 可读写<br> 基于GPSAltitudeRef的高度。| 8773| GPS_TIME_STAMP<sup>10+</sup> | "GPSTimeStamp" | **读写能力：** 可读写<br> GPS时间戳。| 8774| GPS_SATELLITES <sup>12+</sup> | "GPSSatellites" | **读写能力：** 可读写<br> 用于测量的GPS卫星。| 8775| GPS_STATUS <sup>12+</sup> | "GPSStatus" | **读写能力：** 可读写<br> 录制图像时GPS接收器的状态。| 8776| GPS_MEASURE_MODE <sup>12+</sup> | "GPSMeasureMode" | **读写能力：** 可读写<br> GPS测量模式。| 8777| GPS_DOP <sup>12+</sup> | "GPSDOP" | **读写能力：** 可读写<br> GPS DOP（数据精度等级）。| 8778| GPS_SPEED_REF <sup>12+</sup> | "GPSSpeedRef" | **读写能力：** 可读写<br> 用来表示GPS接收器移动速度的单位。| 8779| GPS_SPEED <sup>12+</sup> | "GPSSpeed" | **读写能力：** 可读写<br> GPS接收器的移动速度。| 8780| GPS_TRACK_REF <sup>12+</sup> | "GPSTrackRef" | **读写能力：** 可读写<br> GPS接收机移动方向的参照。| 8781| GPS_TRACK <sup>12+</sup> | "GPSTrack" | **读写能力：** 可读写<br> GPS接收机的移动方向。| 8782| GPS_IMG_DIRECTION_REF <sup>12+</sup> | "GPSImgDirectionRef" | **读写能力：** 可读写<br> 图像方向的参照。| 8783| GPS_IMG_DIRECTION <sup>12+</sup> | "GPSImgDirection" | **读写能力：** 可读写<br> 拍摄时图像的方向。| 8784| GPS_MAP_DATUM <sup>12+</sup> | "GPSMapDatum" | **读写能力：** 可读写<br> GPS接收器使用的大地测量数据。| 8785| GPS_DEST_LATITUDE_REF <sup>12+</sup> | "GPSDestLatitudeRef" | **读写能力：** 可读写<br> 目的地点的纬度参照。| 8786| GPS_DEST_LATITUDE <sup>12+</sup> | "GPSDestLatitude" | **读写能力：** 可读写<br> 目的地点的纬度。| 8787| GPS_DEST_LONGITUDE_REF <sup>12+</sup> | "GPSDestLongitudeRef" | **读写能力：** 可读写<br> 目的地点的经度参照。| 8788| GPS_DEST_LONGITUDE <sup>12+</sup> | "GPSDestLongitude" | **读写能力：** 可读写<br> 目的地点的经度。| 8789| GPS_DEST_BEARING_REF <sup>12+</sup> | "GPSDestBearingRef" | **读写能力：** 可读写<br> 指向目的地点的方位参照。| 8790| GPS_DEST_BEARING <sup>12+</sup> | "GPSDestBearing" | **读写能力：** 可读写<br> 目的地方位。| 8791| GPS_DEST_DISTANCE_REF <sup>12+</sup> | "GPSDestDistanceRef" | **读写能力：** 可读写<br> 目标点距离的测量单位。| 8792| GPS_DEST_DISTANCE <sup>12+</sup> | "GPSDestDistance" | **读写能力：** 可读写<br> 到目的地点的距离。| 8793| GPS_PROCESSING_METHOD <sup>12+</sup> | "GPSProcessingMethod" | **读写能力：** 可读写<br> 记录定位方法名的字符字符串。| 8794| GPS_AREA_INFORMATION <sup>12+</sup> | "GPSAreaInformation" | **读写能力：** 可读写<br> 记录GPS区域名的字符字符串。| 8795| GPS_DATE_STAMP<sup>10+</sup> | "GPSDateStamp" | **读写能力：** 可读写<br> GPS日期戳。| 8796| GPS_DIFFERENTIAL <sup>12+</sup> | "GPSDifferential" | **读写能力：** 可读写<br> 此字段表示GPS数据是否应用了差分校正，对于精确的位置准确性至关重要。| 8797| GPS_H_POSITIONING_ERROR <sup>12+</sup> | "GPSHPositioningError" | **读写能力：** 可读写<br> 此标签指示水平定位误差，单位为米。| 8798| ISO_SPEED_RATINGS<sup>9+</sup> | "ISOSpeedRatings" | **读写能力：** 可读写<br> ISO感光度，例如400。| 8799| PHOTOGRAPHIC_SENSITIVITY <sup>12+</sup> | "PhotographicSensitivity" | **读写能力：** 可读写<br> 此标签指示拍摄图像时相机或输入设备的灵敏度。| 8800| OECF <sup>12+</sup> | "OECF" | **读写能力：** 可读写<br> 表示ISO 14524中规定的光电转换函数（OECF）。| 8801| SENSITIVITY_TYPE<sup>10+</sup> | "SensitivityType" | **读写能力：** 可读写<br> 灵敏度类型。| 8802| STANDARD_OUTPUT_SENSITIVITY<sup>10+</sup> | "StandardOutputSensitivity" | **读写能力：** 可读写<br> 标准输出灵敏度。| 8803| RECOMMENDED_EXPOSURE_INDEX<sup>10+</sup> | "RecommendedExposureIndex" | **读写能力：** 可读写<br> 推荐曝光指数。| 8804| ISO_SPEED<sup>10+</sup> | "ISOSpeedRatings" | **读写能力：** 可读写<br> ISO速度等级。| 8805| ISO_SPEED_LATITUDE_YYY <sup>12+</sup> | "ISOSpeedLatitudeyyy" | **读写能力：** 可读写<br> 该标签指示摄像机或输入设备的ISO速度纬度yyy值，该值在ISO 12232中定义。| 8806| ISO_SPEED_LATITUDE_ZZZ <sup>12+</sup> | "ISOSpeedLatitudezzz" | **读写能力：** 可读写<br> 该标签指示摄像机或输入设备的ISO速度纬度zzz值，该值在ISO 12232中定义。| 8807| EXIF_VERSION <sup>12+</sup> | "ExifVersion" | **读写能力：** 可读写<br> 支持的Exif标准版本。| 8808| DATE_TIME_ORIGINAL<sup>9+</sup> | "DateTimeOriginal" | **读写能力：** 可读写<br> 拍摄时间，例如2022:09:06 15:48:00。| 8809| DATE_TIME_DIGITIZED <sup>12+</sup> | "DateTimeDigitized" | **读写能力：** 可读写<br> 图像作为数字数据存储的日期和时间，格式为YYYY:MM:DD HH:MM:SS| 8810| OFFSET_TIME <sup>12+</sup> | "OffsetTime" | **读写能力：** 可读写<br> 在Exif中，OffsetTime字段表示与UTC（协调世界时）的时间偏移，格式为±HH:MM，用于确定照片拍摄的本地时间。| 8811| OFFSET_TIME_ORIGINAL <sup>12+</sup> | "OffsetTimeOriginal" | **读写能力：** 可读写<br> 此标签记录原始图像创建时的UTC偏移量，对于时间敏感的应用至关重要。| 8812| OFFSET_TIME_DIGITIZED <sup>12+</sup> | "OffsetTimeDigitized" | **读写能力：** 可读写<br> 此标签记录图像数字化时的UTC偏移量，有助于准确调整时间戳。| 8813| COMPONENTS_CONFIGURATION <sup>12+</sup> | "ComponentsConfiguration" | **读写能力：** 可读写<br> 压缩数据的特定信息。| 8814| COMPRESSED_BITS_PER_PIXEL <sup>12+</sup> | "CompressedBitsPerPixel" | **读写能力：** 可读写<br> 用于压缩图像的压缩模式，单位为每像素位数。| 8815| SHUTTER_SPEED <sup>12+</sup> | "ShutterSpeedValue" | **读写能力：** 可读写<br> 快门速度，以APEX（摄影曝光的加法系统）值表示。| 8816| APERTURE_VALUE<sup>10+</sup> | "ApertureValue" | **读写能力：** 可读写<br> 光圈值。格式如4/1。| 8817| BRIGHTNESS_VALUE <sup>12+</sup> | "BrightnessValue" | **读写能力：** 可读写<br> 图像的亮度值，以APEX单位表示。| 8818| EXPOSURE_BIAS_VALUE<sup>10+</sup> | "ExposureBiasValue" | **读写能力：** 可读写<br> 曝光偏差值。| 8819| MAX_APERTURE_VALUE <sup>12+</sup> | "MaxApertureValue" | **读写能力：** 可读写<br> 最小F数镜头。| 8820| SUBJECT_DISTANCE <sup>12+</sup> | "SubjectDistance" | **读写能力：** 可读写<br> 测量单位为米的主体距离。| 8821| METERING_MODE<sup>10+</sup> | "MeteringMode" | **读写能力：** 可读写<br> 测光模式。| 8822| LIGHT_SOURCE<sup>10+</sup> | "LightSource" | **读写能力：** 可读写<br> 光源。例如Fluorescent。| 8823| FLASH <sup>10+</sup> | "Flash" | **读写能力：** 可读写<br> 闪光灯,记录闪光灯状态。| 8824| FOCAL_LENGTH <sup>10+</sup> | "FocalLength" | **读写能力：** 可读写<br> 焦距。| 8825| SUBJECT_AREA <sup>12+</sup> | "SubjectArea" | **读写能力：** 可读写<br> 该标签指示整个场景中主要主体的位置和区域。| 8826| MAKER_NOTE <sup>12+</sup> | "MakerNote" | **读写能力：** 可读写<br> Exif/DCF制造商使用的标签，用于记录任何所需信息。<br>在API 12-19，该字段为只读；从API 20开始，该字段可读写。| 8827| SCENE_POINTER <sup>12+</sup> | "HwMnoteScenePointer" | **读写能力：** 只读<br> 场景指针。| 8828| SCENE_VERSION <sup>12+</sup> | "HwMnoteSceneVersion" | **读写能力：** 只读<br> 场景算法版本信息。| 8829| SCENE_FOOD_CONF<sup>11+</sup> | "HwMnoteSceneFoodConf" | **读写能力：** 只读<br> 拍照场景：食物。| 8830| SCENE_STAGE_CONF<sup>11+</sup> | "HwMnoteSceneStageConf" | **读写能力：** 只读<br> 拍照场景：舞台。| 8831| SCENE_BLUE_SKY_CONF<sup>11+</sup> | "HwMnoteSceneBlueSkyConf" | **读写能力：** 只读<br> 拍照场景：蓝天。| 8832| SCENE_GREEN_PLANT_CONF<sup>11+</sup> | "HwMnoteSceneGreenPlantConf" | **读写能力：** 只读<br> 拍照场景：绿植。| 8833| SCENE_BEACH_CONF<sup>11+</sup> | "HwMnoteSceneBeachConf" | **读写能力：** 只读<br> 拍照场景：沙滩。| 8834| SCENE_SNOW_CONF<sup>11+</sup> | "HwMnoteSceneSnowConf" | **读写能力：** 只读<br> 拍照场景：下雪。| 8835| SCENE_SUNSET_CONF<sup>11+</sup> | "HwMnoteSceneSunsetConf" | **读写能力：** 只读<br> 拍照场景：日落。| 8836| SCENE_FLOWERS_CONF<sup>11+</sup> | "HwMnoteSceneFlowersConf" | **读写能力：** 只读<br> 拍照场景：花。| 8837| SCENE_NIGHT_CONF<sup>11+</sup> | "HwMnoteSceneNightConf" | **读写能力：** 只读<br> 拍照场景：夜晚。| 8838| SCENE_TEXT_CONF<sup>11+</sup> | "HwMnoteSceneTextConf" | **读写能力：** 只读<br> 拍照场景：文本。| 8839| FACE_POINTER <sup>12+</sup> | "HwMnoteFacePointer" | **读写能力：** 只读<br> 脸部指针。| 8840| FACE_VERSION <sup>12+</sup> | "HwMnoteFaceVersion" | **读写能力：** 只读<br> 人脸算法版本信息。| 8841| FACE_COUNT<sup>11+</sup> | "HwMnoteFaceCount" | **读写能力：** 只读<br> 人脸数量。| 8842| FACE_CONF <sup>12+</sup> | "HwMnoteFaceConf" | **读写能力：** 只读<br> 人脸置信度。| 8843| FACE_SMILE_SCORE <sup>12+</sup> | "HwMnoteFaceSmileScore" | **读写能力：** 只读<br> FaceCount张人脸的笑脸分数。| 8844| FACE_RECT <sup>12+</sup> | "HwMnoteFaceRect" | **读写能力：** 只读<br> 脸部矩形。| 8845| FACE_LEYE_CENTER <sup>12+</sup> | "HwMnoteFaceLeyeCenter" | **读写能力：** 只读<br> 左眼中心。| 8846| FACE_REYE_CENTER <sup>12+</sup> | "HwMnoteFaceReyeCenter" | **读写能力：** 只读<br> 右眼中心。| 8847| FACE_MOUTH_CENTER <sup>12+</sup> | "HwMnoteFaceMouthCenter" | **读写能力：** 只读<br> 嘴中心。| 8848| CAPTURE_MODE <sup>10+</sup> | "HwMnoteCaptureMode" | **读写能力：** 可读写<br> 捕获模式。| 8849| BURST_NUMBER <sup>12+</sup> | "HwMnoteBurstNumber" | **读写能力：** 只读<br> 连拍次数。| 8850| FRONT_CAMERA <sup>12+</sup> | "HwMnoteFrontCamera" | **读写能力：** 只读<br> 是否是前置相机自拍。| 8851| ROLL_ANGLE <sup>11+</sup> | "HwMnoteRollAngle" | **读写能力：** 只读<br> 滚动角度。| 8852| PITCH_ANGLE<sup>11+</sup> | "HwMnotePitchAngle" | **读写能力：** 只读<br> 俯仰角度。| 8853| PHYSICAL_APERTURE <sup>10+</sup> | "HwMnotePhysicalAperture" | **读写能力：** 只读<br> 物理孔径，光圈大小。| 8854| FOCUS_MODE<sup>11+</sup> | "HwMnoteFocusMode" | **读写能力：** 只读<br> 对焦模式。| 8855| USER_COMMENT <sup>10+</sup> | "UserComment" | **读写能力：** 可读写<br> 用户注释。| 8856| SUBSEC_TIME <sup>12+</sup> | "SubsecTime" | **读写能力：** 可读写<br> 用于为DateTime标签记录秒的分数的标签。| 8857| SUBSEC_TIME_ORIGINAL <sup>12+</sup> | "SubsecTimeOriginal" | **读写能力：** 可读写<br> 用于为DateTimeOriginal标签记录秒的分数的标签。| 8858| SUBSEC_TIME_DIGITIZED <sup>12+</sup> | "SubsecTimeDigitized" | **读写能力：** 可读写<br> 用于为DateTimeDigitized标签记录秒的分数的标签。| 8859| FLASHPIX_VERSION <sup>12+</sup> | "FlashpixVersion" | **读写能力：** 可读写<br> 该标签表示FPXR文件支持的Flashpix格式版本，增强了设备兼容性。| 8860| COLOR_SPACE <sup>12+</sup> | "ColorSpace" | **读写能力：** 可读写<br> 色彩空间信息标签，通常记录为色彩空间指定符。| 8861| PIXEL_X_DIMENSION <sup>10+</sup> | "PixelXDimension" | **读写能力：** 可读写<br> 像素X尺寸。| 8862| PIXEL_Y_DIMENSION<sup>10+</sup> | "PixelYDimension" | **读写能力：** 可读写<br> 像素Y尺寸。| 8863| RELATED_SOUND_FILE <sup>12+</sup> | "RelatedSoundFile" | **读写能力：** 可读写<br> 与图像数据相关的音频文件的名称。| 8864| FLASH_ENERGY <sup>12+</sup> | "FlashEnergy" | **读写能力：** 可读写<br> 图像捕获时的闪光能量，以BCPS表示。| 8865| SPATIAL_FREQUENCY_RESPONSE <sup>12+</sup> | "SpatialFrequencyResponse" | **读写能力：** 可读写<br> 相机或输入设备的空间频率表。| 8866| FOCAL_PLANE_X_RESOLUTION <sup>12+</sup> | "FocalPlaneXResolution" | **读写能力：** 可读写<br> 图像宽度中每FocalPlaneResolutionUnit的像素。| 8867| FOCAL_PLANE_Y_RESOLUTION <sup>12+</sup> | "FocalPlaneYResolution" | **读写能力：** 可读写<br> 图像高度中每FocalPlaneResolutionUnit的像素。| 8868| FOCAL_PLANE_RESOLUTION_UNIT <sup>12+</sup> | "FocalPlaneResolutionUnit" | **读写能力：** 可读写<br> 测量FocalPlaneXResolution和FocalPlaneYResolution的单位。| 8869| SUBJECT_LOCATION <sup>12+</sup> | "SubjectLocation" | **读写能力：** 可读写<br> 主要对象相对于左边缘的位置。| 8870| EXPOSURE_INDEX <sup>12+</sup> | "ExposureIndex" | **读写能力：** 可读写<br> 捕获时选定的曝光指数。| 8871| SENSING_METHOD <sup>12+</sup> | "SensingMethod" | **读写能力：** 可读写<br> 相机上的图像传感器类型。| 8872| FILE_SOURCE <sup>12+</sup> | "FileSource" | **读写能力：** 可读写<br> 表明图像来源。| 8873| SCENE_TYPE<sup>9+</sup> | "SceneType" | **读写能力：** 可读写<br> 拍摄场景模式，例如人像、风光、运动、夜景等。| 8874| CFA_PATTERN <sup>12+</sup> | "CFAPattern" | **读写能力：** 可读写<br> 图像传感器的色彩滤光片（CFA）几何图案。| 8875| CUSTOM_RENDERED <sup>12+</sup> | "CustomRendered" | **读写能力：** 可读写<br> 指示图像数据上的特殊处理。| 8876| EXPOSURE_MODE <sup>12+</sup> | "ExposureMode" | **读写能力：** 可读写<br> 拍摄时设置的曝光模式。| 8877| WHITE_BALANCE <sup>10+</sup> | "WhiteBalance" | **读写能力：** 可读写<br> 白平衡。| 8878| DIGITAL_ZOOM_RATIO <sup>12+</sup> | "DigitalZoomRatio" | **读写能力：** 可读写<br> 捕获时的数字变焦比率。| 8879| FOCAL_LENGTH_IN_35_MM_FILM <sup>10+</sup> | "FocalLengthIn35mmFilm" | **读写能力：** 可读写<br> 焦距35毫米胶片。| 8880| SCENE_CAPTURE_TYPE <sup>12+</sup> | "SceneCaptureType" | **读写能力：** 可读写<br> 捕获的场景类型。| 8881| GAIN_CONTROL <sup>12+</sup> | "GainControl" | **读写能力：** 可读写<br> 整体图像增益调整的程度。| 8882| CONTRAST <sup>12+</sup> | "Contrast" | **读写能力：** 可读写<br> 相机应用的对比度处理方向。| 8883| SATURATION <sup>12+</sup> | "Saturation" | **读写能力：** 可读写<br> 相机应用的饱和度处理方向。| 8884| SHARPNESS <sup>12+</sup> | "Sharpness" | **读写能力：** 可读写<br> 相机应用的锐度处理方向。| 8885| DEVICE_SETTING_DESCRIPTION <sup>12+</sup> | "DeviceSettingDescription" | **读写能力：** 可读写<br> 特定相机模型的拍照条件信息。| 8886| SUBJECT_DISTANCE_RANGE <sup>12+</sup> | "SubjectDistanceRange" | **读写能力：** 可读写<br> 表示主体到相机的距离范围。| 8887| IMAGE_UNIQUE_ID <sup>12+</sup> | "ImageUniqueID" | **读写能力：** 可读写<br> 为每张图片唯一分配的标识符。| 8888| CAMERA_OWNER_NAME <sup>12+</sup> | "CameraOwnerName" | **读写能力：** 可读写<br> 相机所有者的姓名。| 8889| BODY_SERIAL_NUMBER <sup>12+</sup> | "BodySerialNumber" | **读写能力：** 可读写<br> 相机机身的序列号。| 8890| LENS_SPECIFICATION <sup>12+</sup> | "LensSpecification" | **读写能力：** 可读写<br> 使用的镜头规格。| 8891| LENS_MAKE <sup>12+</sup> | "LensMake" | **读写能力：** 可读写<br> 镜头的制造商。| 8892| LENS_MODEL <sup>12+</sup> | "LensModel" | **读写能力：** 可读写<br> 镜头的型号名称。| 8893| LENS_SERIAL_NUMBER <sup>12+</sup> | "LensSerialNumber" | **读写能力：** 可读写<br> 镜头的序列号。| 8894| COMPOSITE_IMAGE <sup>12+</sup> | "CompositeImage" | **读写能力：** 可读写<br> 表示图像是否为合成图像。| 8895| SOURCE_IMAGE_NUMBER_OF_COMPOSITE_IMAGE <sup>12+</sup> | "SourceImageNumberOfCompositeImage" | **读写能力：** 可读写<br> 用于合成图像的源图像数量。| 8896| SOURCE_EXPOSURE_TIMES_OF_COMPOSITE_IMAGE <sup>12+</sup> | "SourceExposureTimesOfCompositeImage" | **读写能力：** 可读写<br> 合成图像的源图像曝光时间。| 8897| GAMMA <sup>12+</sup> | "Gamma" | **读写能力：** 可读写<br> 表示系数伽马的值。| 8898| DNG_VERSION <sup>12+</sup> | "DNGVersion" | **读写能力：** 可读写<br> DNG版本标签编码了符合DNG规范的四级版本号。| 8899| DEFAULT_CROP_SIZE <sup>12+</sup> | "DefaultCropSize" | **读写能力：** 可读写<br> DefaultCropSize指定了原始坐标中的最终图像大小，考虑了额外的边缘像素。| 8900| GIF_LOOP_COUNT <sup>12+</sup> | "GIFLoopCount" | **读写能力：** 只读<br> GIF图片循环次数。0表示无限循环，其他值表示循环次数。| 8901| IS_XMAGE_SUPPORTED <sup>12+</sup> | "HwMnoteIsXmageSupported" | **读写能力：** 可读写<br>是否支持XMAGE。 | 8902| XMAGE_MODE <sup>12+</sup> | "HwMnoteXmageMode" | **读写能力：** 可读写<br>XMAGE水印模式。 | 8903| XMAGE_LEFT <sup>12+</sup> | "HwMnoteXmageLeft" | **读写能力：** 可读写<br>水印区域X1坐标。 | 8904| XMAGE_TOP <sup>12+</sup> | "HwMnoteXmageTop" | **读写能力：** 可读写<br>水印区域Y1坐标。 | 8905| XMAGE_RIGHT <sup>12+</sup> | "HwMnoteXmageRight" | **读写能力：** 可读写<br>水印区域X2坐标。 | 8906| XMAGE_BOTTOM <sup>12+</sup> | "HwMnoteXmageBottom" | **读写能力：** 可读写<br>水印区域Y2坐标。 | 8907| CLOUD_ENHANCEMENT_MODE <sup>12+</sup> | "HwMnoteCloudEnhancementMode" | **读写能力：** 可读写<br>云增强模式。 | 8908| WIND_SNAPSHOT_MODE <sup>12+</sup> | "HwMnoteWindSnapshotMode" | **读写能力：** 只读<br>运动快拍模式。 | 8909 8910## FragmentMapPropertyKey<sup>13+</sup> 8911 8912枚举，水印裁剪图图片信息。 8913 8914**系统能力：** SystemCapability.Multimedia.Image.Core 8915 8916| 名称 | 值 | 说明 | 8917| ------------- | --------------------- | ----------------------------------- | 8918| X_IN_ORIGINAL | "XInOriginal" | 水印裁剪图左上角在原始图中的X坐标。 | 8919| Y_IN_ORIGINAL | "YInOriginal" | 水印裁剪图左上角在原始图中的Y坐标。 | 8920| WIDTH | "FragmentImageWidth" | 水印裁剪图的宽。 | 8921| HEIGHT | "FragmentImageHeight" | 水印裁剪图的高。 | 8922 8923## ImageFormat<sup>9+</sup> 8924 8925枚举，图片格式。 8926 8927**系统能力：** SystemCapability.Multimedia.Image.Core 8928 8929| 名称 | 值 | 说明 | 8930| ------------ | ------ | -------------------- | 8931| YCBCR_422_SP | 1000 | YCBCR422半平面格式。 | 8932| JPEG | 2000 | JPEG编码格式。 | 8933 8934## ComponentType<sup>9+</sup> 8935 8936枚举，图像的组件类型。 8937 8938**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 8939 8940| 名称 | 值 | 说明 | 8941| ----- | ------ | ----------- | 8942| YUV_Y | 1 | 亮度信息。 | 8943| YUV_U | 2 | 色度信息。 | 8944| YUV_V | 3 | 色度信息。 | 8945| JPEG | 4 | JPEG 类型。 | 8946 8947## Component<sup>9+</sup> 8948 8949描述图像颜色分量。 8950 8951**系统能力：** SystemCapability.Multimedia.Image.Core 8952 8953| 名称 | 类型 | 只读 | 可选 | 说明 | 8954| ------------- | -------------------------------- | ---- | ---- | ------------ | 8955| componentType | [ComponentType](#componenttype9) | 是 | 否 | 组件类型。 | 8956| rowStride | number | 是 | 否 | 行距。读取相机预览流数据时，需要按stride进行读取，使用详情请参考[相机预览花屏解决方案](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-deal-stride-solution)。 | 8957| pixelStride | number | 是 | 否 | 像素间距。 | 8958| byteBuffer | ArrayBuffer | 是 | 否 | 组件缓冲区。 | 8959 8960## DecodingDynamicRange<sup>12+</sup> 8961 8962描述解码时期望的图像动态范围。 8963 8964**系统能力：** SystemCapability.Multimedia.Image.Core 8965 8966| 名称 | 值 | 说明 | 8967| ------------- | ----------| ------------ | 8968| AUTO | 0 | 自适应，根据图片信息处理。即如果图片本身为HDR图片，则会按照HDR内容解码；反之按照SDR内容解码。通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource会解码为SDR内容。 | 8969| SDR | 1 | 按照标准动态范围处理图片。 | 8970| HDR | 2 | 按照高动态范围处理图片。通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource会解码为SDR内容。 | 8971 8972## PackingDynamicRange<sup>12+</sup> 8973 8974描述编码时期望的图像动态范围。 8975 8976**系统能力：** SystemCapability.Multimedia.Image.Core 8977 8978| 名称 | 值 | 说明 | 8979| ------------- | ----------| ------------ | 8980| AUTO | 0 | 自适应，根据[pixelmap](#pixelmap7)内容处理。即如果pixelmap本身为HDR，则会按照HDR内容进行编码；反之按照SDR内容编码。 | 8981| SDR | 1 | 按照标准动态范围处理图片。 | 8982 8983## CropAndScaleStrategy<sup>18+</sup> 8984 8985枚举，裁剪与缩放的先后策略。 8986 8987如果在配置解码选项[DecodingOptions](#decodingoptions7)时，未填入参数cropAndScaleStrategy，并且同时设置了参数desiredRegion和desiredSize，由于系统对于不同图片格式采用的解码算法不同，最终解码效果将略有差异。 8988 8989例如原始图片大小为200x200，传入desiredSize:{width: 150, height: 150}，desiredRegion:{x: 0, y: 0, width: 100, height: 100}，即预期解码原图左上角1/4区域，最终将pixelMap大小缩放至150x150返回。 8990 8991对于jpeg、webp图片（部分dng图片解码时会优先解码图片中的jpeg预览图，在此场景下也会被视为jpeg图片格式）会先进行下采样，例如按照7/8下采样，再基于175x175的图片大小进行区域裁剪，因此最终的区域内容稍大于原图的左上角1/4区域。 8992 8993对于svg图片，由于是矢量图，可以任意缩放不损失清晰度，在解码时会根据desiredSize与原图Size的比例选择缩放比例，在基于缩放后的图片大小进行区域裁剪，因此最终返回的解码区域会有所差异。 8994 8995针对该场景，建议在解码选项同时设置了desiredRegion与desiredSize时，参数cropAndScaleStrategy应传入CROP_FIRST保证效果一致。 8996 8997**系统能力：** SystemCapability.Multimedia.Image.Core 8998 8999| 名称 | 值 | 说明 | 9000| ------------- | ----------| ------------ | 9001| SCALE_FIRST | 1 | 解码参数如果同时设置desiredRegion与desiredSize，先根据desiredSize进行缩放，再根据desiredRegion进行区域裁剪。 | 9002| CROP_FIRST | 2 | 解码参数如果同时设置desiredRegion与desiredSize，先根据desiredRegion进行区域裁剪，再根据desiredSize进行缩放。 | 9003 9004 9005 9006## HdrMetadataKey<sup>12+</sup> 9007 9008枚举，[pixelmap](#pixelmap7)使用的HDR相关元数据信息的关键字。 9009 9010**系统能力：** SystemCapability.Multimedia.Image.Core 9011 9012| 名称 | 值 | 说明 | 9013| ------------- | ----------| ------------ | 9014| HDR_METADATA_TYPE | 0 | [pixelmap](#pixelmap7)使用的元数据类型。 | 9015| HDR_STATIC_METADATA | 1 | 静态元数据。 | 9016| HDR_DYNAMIC_METADATA | 2 | 动态元数据。 | 9017| HDR_GAINMAP_METADATA | 3 | Gainmap使用的元数据。 | 9018 9019## HdrMetadataType<sup>12+</sup> 9020 9021枚举，[HdrMetadataKey](#hdrmetadatakey12)中HDR_METADATA_TYPE关键字对应的值。 9022 9023**系统能力：** SystemCapability.Multimedia.Image.Core 9024 9025| 名称 | 值 | 说明 | 9026| ------------- | ----------| ------------ | 9027| NONE | 0 | 无元数据内容。 | 9028| BASE | 1 | 表示用于基础图的元数据。 | 9029| GAINMAP | 2 | 表示用于Gainmap图的元数据。 | 9030| ALTERNATE| 3 | 表示用于合成后HDR图的元数据。 | 9031 9032## HdrStaticMetadata<sup>12+</sup> 9033 9034静态元数据值，[HdrMetadataKey](#hdrmetadatakey12)中HDR_STATIC_METADATA关键字对应的值。 9035 9036**系统能力：** SystemCapability.Multimedia.Image.Core 9037 9038| 名称 | 类型 | 只读 | 可选 | 说明 | 9039| ------------- | ----------| -- | -- | ------------ | 9040| displayPrimariesX | Array\<number> | 否 | 否 | 归一化后显示设备三基色的X坐标，数组的长度为3，以0.00002为单位，范围[0.0, 1.0]。 | 9041| displayPrimariesY | Array\<number> | 否 | 否 | 归一化后显示设备三基色的Y坐标，数组的长度为3，以0.00002为单位，范围[0.0, 1.0]。 | 9042| whitePointX | number | 否 | 否 | 归一化后白点值的X坐标，以0.00002为单位，范围[0.0, 1.0]。 | 9043| whitePointY | number | 否 | 否 | 归一化后白点值的Y坐标，以0.00002为单位，范围[0.0, 1.0]。 | 9044| maxLuminance | number | 否 | 否 | 图像主监视器最大亮度。以1为单位，最大值为65535。 | 9045| minLuminance | number | 否 | 否 | 图像主监视器最小亮度。以0.0001为单位，最大值6.55535。 | 9046| maxContentLightLevel | number | 否 | 否 | 显示内容的最大亮度。以1为单位，最大值为65535。 | 9047| maxFrameAverageLightLevel | number | 否 | 否 | 显示内容的最大平均亮度，以1为单位，最大值为65535。 | 9048 9049## GainmapChannel<sup>12+</sup> 9050 9051Gainmap图单个通道的数据内容，参考ISO 21496-1。 9052 9053**系统能力：** SystemCapability.Multimedia.Image.Core 9054 9055| 名称 | 类型 | 只读 | 可选 | 说明 | 9056| ------------- | ----------| -- | -- | ------------ | 9057| gainmapMax | number | 否 | 否 | 增强图像的最大值，参考ISO 21496-1。 | 9058| gainmapMin | number | 否 | 否 | 增强图像的最小值，参考ISO 21496-1。 | 9059| gamma | number | 否 | 否 | gamma值，参考ISO 21496-1。 | 9060| baseOffset | number | 否 | 否 | 基础图的偏移，参考ISO 21496-1。 | 9061| alternateOffset | number | 否 | 否 | 提取的可选择图像偏移量，参考ISO 21496-1。 | 9062 9063## HdrGainmapMetadata<sup>12+</sup> 9064 9065Gainmap使用的元数据值，[HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的值，参考ISO 21496-1。 9066 9067**系统能力：** SystemCapability.Multimedia.Image.Core 9068 9069| 名称 | 类型 | 只读 | 可选 | 说明 | 9070| ------------- | ----------| -- | -- | ------------ | 9071| writerVersion | number | 否 | 否 | 元数据编写器使用的版本。 | 9072| miniVersion | number | 否 | 否 | 元数据解析需要理解的最小版本。 | 9073| gainmapChannelCount | number | 否 | 否 | Gainmap的颜色通道数，值为3时RGB通道的元数据值不同，值为1时各通道元数据值相同，参考ISO 21496-1。 | 9074| useBaseColorFlag | boolean | 否 | 否 | 是否使用基础图的色彩空间，参考ISO 21496-1。true表示是，false表示否。 | 9075| baseHeadroom | number | 否 | 否 | 基础图提亮比，参考ISO 21496-1。 | 9076| alternateHeadroom | number | 否 | 否 | 提取的可选择图像提亮比，参考ISO 21496-1。 | 9077| channels | Array<[GainmapChannel](#gainmapchannel12)> | 否 | 否 | 各通道的数据，长度为3，参考ISO 21496-1。 | 9078 9079## HdrMetadataValue<sup>12+</sup> 9080 9081type HdrMetadataValue = HdrMetadataType | HdrStaticMetadata | ArrayBuffer | HdrGainmapMetadata 9082 9083PixelMap使用的HDR元数据值类型，和[HdrMetadataKey](#hdrmetadatakey12)关键字相对应。 9084 9085**系统能力：** SystemCapability.Multimedia.Image.Core 9086 9087| 类型 | 说明 | 9088| ------------------- | ----------------------------------------------- | 9089| [HdrMetadataType](#hdrmetadatatype12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的元数据值类型。 | 9090| [HdrStaticMetadata](#hdrstaticmetadata12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_STATIC_METADATA关键字对应的元数据值类型。 | 9091| ArrayBuffer | [HdrMetadataKey](#hdrmetadatakey12)中HDR_DYNAMIC_METADATA关键字对应的元数据值类型。 | 9092| [HdrGainmapMetadata](#hdrgainmapmetadata12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的元数据值类型。 | 9093 9094## AntiAliasingLevel<sup>12+</sup> 9095 9096缩放时的缩放算法。 9097 9098**原子化服务API**：从API version 14 开始，该接口支持在原子化服务中使用。 9099 9100**系统能力：** SystemCapability.Multimedia.Image.Core 9101 9102| 名称 | 值 | 说明 | 9103| ---------------------- | ------ | ----------------- | 9104| NONE | 0 | 最近邻插值算法。 | 9105| LOW | 1 | 双线性插值算法。 | 9106| MEDIUM | 2 | 双线性插值算法，同时开启Mipmap。缩小图片时建议使用。 | 9107| HIGH | 3 | 三次插值算法。 | 9108 9109## AllocatorType<sup>15+</sup> 9110 9111枚举，用于图像解码的内存类型。 9112 9113**系统能力：** SystemCapability.Multimedia.Image.Core 9114 9115| 名称 | 值 | 说明 | 9116| ------------ | ---- | ---------------------------------- | 9117| AUTO | 0 | 系统决定内存申请方式。 | 9118| DMA | 1 | 使用DMA内存申请方式。 | 9119| SHARE_MEMORY | 2 | 使用SHARE_MEMORY的内存申请方式。 | 9120 9121## 补充说明 9122 9123### SVG标签说明 9124 9125从API version 10开始支持SVG标签，使用版本为(SVG) 1.1，SVG标签需设置width，height。SVG文件可添加xml声明，应以“<?xml”开头，当前支持的标签列表有： 9126- a 9127- circla 9128- clipPath 9129- defs 9130- ellipse 9131- feBlend 9132- feColorMatrix 9133- feComposite 9134- feDiffuseLighting 9135- feDisplacementMap 9136- feDistantLight 9137- feFlood 9138- feGaussianBlur 9139- feImage 9140- feMorphology 9141- feOffset 9142- fePointLight 9143- feSpecularLighting 9144- feSpotLight 9145- feTurbulence 9146- filter 9147- g 9148- image 9149- line 9150- linearGradient 9151- mask 9152- path 9153- pattern 9154- polygon 9155- polyline 9156- radialGradient 9157- rect 9158- stop 9159- svg 9160- text 9161- textPath 9162- tspan 9163- use
