1# @ohos.multimedia.image (图片处理) 2 3本模块提供图片处理效果，包括通过属性创建PixelMap、读取图像像素数据、读取区域内的图片数据等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 从API version 12开始，本模块接口支持在ArkTS卡片中使用。 10 11## 导入模块 12 13```ts 14import { image } from '@kit.ImageKit'; 15``` 16 17## image.createPicture<sup>13+</sup> 18 19createPicture(mainPixelmap : PixelMap): Picture 20 21通过主图的pixelmap创建一个Picture对象。 22 23**系统能力：** SystemCapability.Multimedia.Image.Core 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------------ | ------------------- | ---- | ---------------- | 29| mainPixelmap | [PixelMap](#pixelmap7) | 是 | 主图的pixelmap。 | 30 31**返回值：** 32 33| 类型 | 说明 | 34| ------------------ | ----------------- | 35| [Picture](#picture13) | 返回Picture对象。 | 36 37**错误码：** 38 39以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 40 41| 错误码ID | 错误信息 | 42| -------- | ------------------------------------------------------------ | 43| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. | 44 45**示例：** 46 47```ts 48import { image } from '@kit.ImageKit'; 49 50async function CreatePicture() { 51 const context = getContext(); 52 const resourceMgr = context.resourceManager; 53 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 54 let ops: image.SourceOptions = { 55 sourceDensity: 98, 56 } 57 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 58 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 59 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 60 if (pictureObj != null) { 61 console.info('Create picture succeeded'); 62 } else { 63 console.info('Create picture failed'); 64 } 65} 66``` 67 68## image.createPictureFromParcel<sup>13+</sup> 69 70createPictureFromParcel(sequence: rpc.MessageSequence): Picture 71 72从MessageSequence中获取Picture。 73 74**系统能力：** SystemCapability.Multimedia.Image.Core 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| -------- | ------------------------------------------------------------------- | ---- | ------------------------------------ | 80| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有Picture信息的MessageSequence。 | 81 82**返回值：** 83 84| 类型 | 说明 | 85| ------------------ | ----------------- | 86| [Picture](#picture13) | 返回Picture对象。 | 87 88**错误码：** 89 90以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 91 92| 错误码ID | 错误信息 | 93| -------- | ------------------------------------------------------------ | 94| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. | 95| 62980097 | IPC error. | 96 97**示例：** 98 99```ts 100import { rpc } from '@kit.IPCKit'; 101import { BusinessError } from '@kit.BasicServicesKit'; 102import { image } from '@kit.ImageKit'; 103 104class MySequence implements rpc.Parcelable { 105 picture: image.Picture | null = null; 106 constructor(conPicture: image.Picture) { 107 this.picture = conPicture; 108 } 109 marshalling(messageSequence: rpc.MessageSequence) { 110 if(this.picture != null) { 111 this.picture.marshalling(messageSequence); 112 console.info('Marshalling success !'); 113 return true; 114 } else { 115 console.info('Marshalling failed !'); 116 return false; 117 } 118 } 119 unmarshalling(messageSequence : rpc.MessageSequence) { 120 this.picture = image.createPictureFromParcel(messageSequence); 121 this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => { 122 console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 123 }).catch((error: BusinessError) => { 124 console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}'); 125 }); 126 return true; 127 } 128} 129 130async function Marshalling_UnMarshalling() { 131 const context = getContext(); 132 const resourceMgr = context.resourceManager; 133 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 134 let ops: image.SourceOptions = { 135 sourceDensity: 98, 136 } 137 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 138 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 139 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 140 if (pictureObj != null) { 141 let parcelable: MySequence = new MySequence(pictureObj); 142 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 143 // marshalling. 144 data.writeParcelable(parcelable); 145 let ret: MySequence = new MySequence(pictureObj); 146 // unmarshalling. 147 data.readParcelable(ret); 148 } else { 149 console.info('PictureObj is null'); 150 } 151} 152``` 153 154## image.createPixelMap<sup>8+</sup> 155 156createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise\<PixelMap> 157 158通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过Promise返回结果。 159 160**系统能力：** SystemCapability.Multimedia.Image.Core 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 166| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 167| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 168 169**返回值：** 170 171| 类型 | 说明 | 172| -------------------------------- | ----------------------------------------------------------------------- | 173| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。<br>当创建的pixelMap大小超过原图大小时，返回原图pixelMap大小。| 174 175**示例：** 176 177```ts 178import { BusinessError } from '@kit.BasicServicesKit'; 179 180async function CreatePixelMap() { 181 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 182 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 183 image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 184 console.info('Succeeded in creating pixelmap.'); 185 }).catch((error: BusinessError) => { 186 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 187 }) 188} 189``` 190 191## image.createPixelMap<sup>8+</sup> 192 193createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback\<PixelMap>): void 194 195通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过callback返回结果。 196 197**系统能力：** SystemCapability.Multimedia.Image.Core 198 199**参数：** 200 201| 参数名 | 类型 | 必填 | 说明 | 202| -------- | ------------------------------------------------ | ---- | -------------------------- | 203| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 204| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 205| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 206 207**示例：** 208 209```ts 210import { BusinessError } from '@kit.BasicServicesKit'; 211 212async function CreatePixelMap() { 213 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 214 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 215 image.createPixelMap(color, opts, (error: BusinessError, pixelMap: image.PixelMap) => { 216 if(error) { 217 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 218 return; 219 } else { 220 console.info('Succeeded in creating pixelmap.'); 221 } 222 }) 223} 224``` 225 226## image.createPixelMapFromParcel<sup>11+</sup> 227 228createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap 229 230从MessageSequence中获取PixelMap。 231 232**系统能力：** SystemCapability.Multimedia.Image.Core 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 238| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 239 240**返回值：** 241 242| 类型 | 说明 | 243| -------------------------------- | --------------------- | 244| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 245 246**错误码：** 247 248以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 249 250| 错误码ID | 错误信息 | 251| ------- | --------------------------------------------| 252| 62980096 | Operation failed| 253| 62980097 | IPC error.| 254| 62980115 | Invalid input parameter| 255| 62980105 | Failed to get the data| 256| 62980177 | Abnormal API environment| 257| 62980178 | Failed to create the PixelMap| 258| 62980179 | Abnormal buffer size| 259| 62980180 | FD mapping failed| 260| 62980246 | Failed to read the PixelMap| 261 262**示例：** 263 264```ts 265import { image } from '@kit.ImageKit'; 266import { rpc } from '@kit.IPCKit'; 267import { BusinessError } from '@kit.BasicServicesKit'; 268 269class MySequence implements rpc.Parcelable { 270 pixel_map: image.PixelMap; 271 constructor(conPixelmap: image.PixelMap) { 272 this.pixel_map = conPixelmap; 273 } 274 marshalling(messageSequence: rpc.MessageSequence) { 275 this.pixel_map.marshalling(messageSequence); 276 return true; 277 } 278 unmarshalling(messageSequence: rpc.MessageSequence) { 279 try { 280 this.pixel_map = image.createPixelMapFromParcel(messageSequence); 281 } catch(e) { 282 let error = e as BusinessError; 283 console.error(`createPixelMapFromParcel error. code is ${error.code}, message is ${error.message}`); 284 return false; 285 } 286 return true; 287 } 288} 289async function CreatePixelMapFromParcel() { 290 const color: ArrayBuffer = new ArrayBuffer(96); 291 let bufferArr: Uint8Array = new Uint8Array(color); 292 for (let i = 0; i < bufferArr.length; i++) { 293 bufferArr[i] = 0x80; 294 } 295 let opts: image.InitializationOptions = { 296 editable: true, 297 pixelFormat: image.PixelMapFormat.BGRA_8888, 298 size: { height: 4, width: 6 }, 299 alphaType: image.AlphaType.UNPREMUL 300 } 301 let pixelMap: image.PixelMap | undefined = undefined; 302 image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 303 pixelMap = srcPixelMap; 304 }) 305 if (pixelMap != undefined) { 306 // 序列化。 307 let parcelable: MySequence = new MySequence(pixelMap); 308 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 309 data.writeParcelable(parcelable); 310 311 // 反序列化 rpc获取到data。 312 let ret: MySequence = new MySequence(pixelMap); 313 data.readParcelable(ret); 314 315 // 获取到pixelmap。 316 let unmarshPixelmap = ret.pixel_map; 317 } 318} 319``` 320 321## image.createPixelMapFromSurface<sup>11+</sup> 322 323createPixelMapFromSurface(surfaceId: string, region: Region): Promise\<PixelMap> 324 325根据Surface id和区域信息，创建一个PixelMap对象。该区域的大小由[Region](#region8).size指定。使用Promise形式返回。 326 327> **说明：** 328> 当开发设备为折叠屏，折叠状态切换时，可能因Surface自带旋转角度导致接口创建失败，需将宽高适配旋转角度。 329 330**系统能力：** SystemCapability.Multimedia.Image.Core 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| ---------------------- | ------------- | ---- | ---------------------------------------- | 336| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 337| region | [Region](#region8) | 是 | 区域信息。[Region](#region8).size的宽高需和设置的预览流大小保持一致。 | 338 339**返回值：** 340| 类型 | 说明 | 341| -------------------------------- | --------------------- | 342| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 343 344**错误码：** 345 346以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 347 348| 错误码ID | 错误信息 | 349| ------- | --------------------------------------------| 350| 62980115 | If the image parameter invalid.| 351| 62980105 | Failed to get the data| 352| 62980178 | Failed to create the PixelMap| 353 354**示例：** 355 356```ts 357import { BusinessError } from '@kit.BasicServicesKit'; 358 359async function CreatePixelMapFromSurface(surfaceId: string) { 360 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 361 image.createPixelMapFromSurface(surfaceId, region).then(() => { 362 console.info('Succeeded in creating pixelmap from Surface'); 363 }).catch((error: BusinessError) => { 364 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 365 }); 366} 367``` 368 369## image.createPixelMapFromSurfaceSync<sup>12+</sup> 370 371createPixelMapFromSurfaceSync(surfaceId: string, region: Region): PixelMap 372 373以同步方式，根据Surface id和区域信息，创建一个PixelMap对象。该区域的大小由[Region](#region8).size指定。 374 375> **说明：** 376> 当开发设备为折叠屏，折叠状态切换时，可能因Surface自带旋转角度导致接口创建失败，需将宽高适配旋转角度。 377 378**系统能力：** SystemCapability.Multimedia.Image.Core 379 380**参数：** 381 382| 参数名 | 类型 | 必填 | 说明 | 383| ---------------------- | ------------- | ---- | ---------------------------------------- | 384| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 385| region | [Region](#region8) | 是 | 区域信息。[Region](#region8).size的宽高需和设置的预览流大小保持一致。 | 386 387**返回值：** 388| 类型 | 说明 | 389| -------------------------------- | --------------------- | 390| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 391 392**错误码：** 393 394以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 395 396| 错误码ID | 错误信息 | 397| ------- | --------------------------------------------| 398| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 399| 62980105 | Failed to get the data| 400| 62980178 | Failed to create the PixelMap| 401 402**示例：** 403 404```ts 405import { BusinessError } from '@kit.BasicServicesKit'; 406 407async function Demo(surfaceId: string) { 408 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 409 let pixelMap : image.PixelMap = image.createPixelMapFromSurfaceSync(surfaceId, region); 410 return pixelMap; 411} 412``` 413 414## image.createPixelMapFromSurface<sup>15+</sup> 415 416createPixelMapFromSurface(surfaceId: string): Promise\<PixelMap> 417 418从Surface id创建一个PixelMap对象。使用Promise异步回调，返回PixelMap。 419 420**系统能力：** SystemCapability.Multimedia.Image.Core 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| ---------------------- | ------------- | ---- | ---------------------------------------- | 426| surfaceId | string | 是 | 从[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件获取的surfaceId。| 427 428**返回值：** 429| 类型 | 说明 | 430| -------------------------------- | --------------------- | 431| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 432 433**错误码：** 434 435以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 436 437| 错误码ID | 错误信息 | 438| ------- | --------------------------------------------| 439| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 440| 62980105 | Failed to get the data| 441| 62980178 | Failed to create the PixelMap| 442 443**示例：** 444 445```ts 446import { BusinessError } from '@kit.BasicServicesKit'; 447 448async function Demo(surfaceId: string) { 449 image.createPixelMapFromSurface(surfaceId).then(() => { 450 console.info('Succeeded in creating pixelmap from Surface'); 451 }).catch((error: BusinessError) => { 452 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 453 }); 454} 455``` 456 457## image.createPixelMapFromSurfaceSync<sup>15+</sup> 458 459createPixelMapFromSurfaceSync(surfaceId: string): PixelMap 460 461从Surface id创建一个pixelMap对象，同步返回PixelMap结果。 462 463**系统能力：** SystemCapability.Multimedia.Image.Core 464 465**参数：** 466 467| 参数名 | 类型 | 必填 | 说明 | 468| ---------------------- | ------------- | ---- | ---------------------------------------- | 469| surfaceId | string | 是 | 从[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件获取的surfaceId。| 470 471**返回值：** 472| 类型 | 说明 | 473| -------------------------------- | --------------------- | 474| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 475 476**错误码：** 477 478以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 479 480| 错误码ID | 错误信息 | 481| ------- | --------------------------------------------| 482| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 483| 62980105 | Failed to get the data| 484| 62980178 | Failed to create the PixelMap| 485 486**示例：** 487 488```ts 489import { BusinessError } from '@kit.BasicServicesKit'; 490 491async function Demo(surfaceId: string) { 492 let pixelMap : image.PixelMap = image.createPixelMapFromSurfaceSync(surfaceId); 493 return pixelMap; 494} 495``` 496## image.createPixelMapSync<sup>12+</sup> 497 498createPixelMapSync(colors: ArrayBuffer, options: InitializationOptions): PixelMap 499 500通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，同步返回结果。 501 502**系统能力：** SystemCapability.Multimedia.Image.Core 503 504**参数：** 505 506| 参数名 | 类型 | 必填 | 说明 | 507| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 508| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 509| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 510 511**返回值：** 512| 类型 | 说明 | 513| -------------------------------- | --------------------- | 514| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 515 516**错误码：** 517 518以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 519 520| 错误码ID | 错误信息 | 521| ------- | --------------------------------------------| 522| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 523 524**示例：** 525 526```ts 527import { BusinessError } from '@kit.BasicServicesKit'; 528 529async function CreatePixelMapSync() { 530 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 531 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 532 let pixelMap : image.PixelMap = image.createPixelMapSync(color, opts); 533 return pixelMap; 534} 535``` 536 537## image.createPixelMapSync<sup>12+</sup> 538 539createPixelMapSync(options: InitializationOptions): PixelMap 540 541通过属性创建PixelMap，同步返回PixelMap结果。 542 543**系统能力：** SystemCapability.Multimedia.Image.Core 544 545**参数：** 546 547| 参数名 | 类型 | 必填 | 说明 | 548| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 549| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 550 551**返回值：** 552| 类型 | 说明 | 553| -------------------------------- | --------------------- | 554| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 555 556**错误码：** 557 558以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 559 560| 错误码ID | 错误信息 | 561| ------- | --------------------------------------------| 562| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 563 564**示例：** 565 566```ts 567import { BusinessError } from '@kit.BasicServicesKit'; 568 569async function CreatePixelMapSync() { 570 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 571 let pixelMap : image.PixelMap = image.createPixelMapSync(opts); 572 return pixelMap; 573} 574``` 575 576## image.createPremultipliedPixelMap<sup>12+</sup> 577 578createPremultipliedPixelMap(src: PixelMap, dst: PixelMap, callback: AsyncCallback\<void>): void 579 580将PixelMap的透明通道非预乘模式转变为预乘模式，转换后的数据存入目标PixelMap，通过回调函数返回结果。 581 582**系统能力：** SystemCapability.Multimedia.Image.Core 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| -------- | ------------------------------------------------ | ---- | -------------------------- | 588| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 589| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 590|callback | AsyncCallback\<void> | 是 | 回调函数，当创建PixelMap成功，err为undefined，否则为错误对象。 | 591 592**错误码：** 593 594以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 595 596| 错误码ID | 错误信息 | 597| ------- | --------------------------------------------| 598| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 599| 62980103 | The image data is not supported | 600| 62980246 | Failed to read the pixelMap | 601| 62980248 | Pixelmap not allow modify | 602 603**示例：** 604 605```ts 606import { BusinessError } from '@kit.BasicServicesKit'; 607 608async function CreatePremultipliedPixelMap() { 609 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 610 let bufferArr = new Uint8Array(color); 611 for (let i = 0; i < bufferArr.length; i += 4) { 612 bufferArr[i] = 255; 613 bufferArr[i+1] = 255; 614 bufferArr[i+2] = 122; 615 bufferArr[i+3] = 122; 616 } 617 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 618 let srcPixelmap = image.createPixelMapSync(color, optsForUnpre); 619 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 620 let dstPixelMap = image.createPixelMapSync(optsForPre); 621 image.createPremultipliedPixelMap(srcPixelmap, dstPixelMap, (error: BusinessError) => { 622 if(error) { 623 console.error(`Failed to convert pixelmap. code is ${error.code}, message is ${error.message}`); 624 return; 625 } else { 626 console.info('Succeeded in converting pixelmap.'); 627 } 628 }) 629} 630``` 631 632## image.createPremultipliedPixelMap<sup>12+</sup> 633 634createPremultipliedPixelMap(src: PixelMap, dst: PixelMap): Promise\<void> 635 636将PixelMap数据按照透明度非预乘格式转为预乘格式，转换后的数据存入另一个PixelMap，通过Promise返回结果。 637 638**系统能力：** SystemCapability.Multimedia.Image.Core 639 640**参数：** 641 642| 参数名 | 类型 | 必填 | 说明 | 643| -------- | ------------------------------------------------ | ---- | -------------------------- | 644| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 645| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 646 647**返回值：** 648 649| 类型 | 说明 | 650| -------------------------------- | ----------------------------------------------------------------------- | 651| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 652 653**错误码：** 654 655以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 656 657| 错误码ID | 错误信息 | 658| ------- | --------------------------------------------| 659| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 660| 62980103 | The image data is not supported | 661| 62980246 | Failed to read the pixelMap | 662| 62980248 | Pixelmap not allow modify | 663 664**示例：** 665 666```ts 667import { BusinessError } from '@kit.BasicServicesKit'; 668 669async function CreatePremultipliedPixelMap() { 670 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 671 let bufferArr = new Uint8Array(color); 672 for (let i = 0; i < bufferArr.length; i += 4) { 673 bufferArr[i] = 255; 674 bufferArr[i+1] = 255; 675 bufferArr[i+2] = 122; 676 bufferArr[i+3] = 122; 677 } 678 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 679 let srcPixelmap = image.createPixelMapSync(color, optsForUnpre); 680 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 681 let dstPixelMap = image.createPixelMapSync(optsForPre); 682 image.createPremultipliedPixelMap(srcPixelmap, dstPixelMap).then(() => { 683 console.info('Succeeded in converting pixelmap.'); 684 }).catch((error: BusinessError) => { 685 console.error(`Failed to convert pixelmap. code is ${error.code}, message is ${error.message}`); 686 }) 687} 688``` 689 690## image.createUnpremultipliedPixelMap<sup>12+</sup> 691 692createUnpremultipliedPixelMap(src: PixelMap, dst: PixelMap, callback: AsyncCallback\<void>): void 693 694将PixelMap的透明通道预乘模式转变为非预乘模式，转换后的数据存入目标PixelMap，通过回调函数返回结果。 695 696**系统能力：** SystemCapability.Multimedia.Image.Core 697 698**参数：** 699 700| 参数名 | 类型 | 必填 | 说明 | 701| -------- | ------------------------------------------------ | ---- | -------------------------- | 702| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 703| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。| 704|callback | AsyncCallback\<void> | 是 | 回调函数，当创建PixelMap成功，err为undefined，否则为错误对象。| 705 706**错误码：** 707 708以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 709 710| 错误码ID | 错误信息 | 711| ------- | --------------------------------------------| 712| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 713| 62980103 | The image data is not supported | 714| 62980246 | Failed to read the pixelMap | 715| 62980248 | Pixelmap not allow modify | 716 717**示例：** 718 719```ts 720import { BusinessError } from '@kit.BasicServicesKit'; 721 722async function CreateUnpremultipliedPixelMap() { 723 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 724 let bufferArr = new Uint8Array(color); 725 for (let i = 0; i < bufferArr.length; i += 4) { 726 bufferArr[i] = 255; 727 bufferArr[i+1] = 255; 728 bufferArr[i+2] = 122; 729 bufferArr[i+3] = 122; 730 } 731 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 732 let srcPixelmap = image.createPixelMapSync(color, optsForPre); 733 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 734 let dstPixelMap = image.createPixelMapSync(optsForUnpre); 735 image.createUnpremultipliedPixelMap(srcPixelmap, dstPixelMap, (error: BusinessError) => { 736 if(error) { 737 console.error(`Failed to convert pixelmap. code is ${error.code}, message is ${error.message}`); 738 return; 739 } else { 740 console.info('Succeeded in converting pixelmap.'); 741 } 742 }) 743} 744``` 745 746## image.createUnpremultipliedPixelMap<sup>12+</sup> 747 748createUnpremultipliedPixelMap(src: PixelMap, dst: PixelMap): Promise\<void> 749 750将PixelMap的透明通道预乘模式转变为非预乘模式，转换后的数据存入目标PixelMap，通过Promise返回结果。 751 752**系统能力：** SystemCapability.Multimedia.Image.Core 753 754**参数：** 755 756| 参数名 | 类型 | 必填 | 说明 | 757| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 758| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 759| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 760 761**返回值：** 762 763| 类型 | 说明 | 764| -------------------------------- | ----------------------------------------------------------------------- | 765| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 766 767**错误码：** 768 769以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 770 771| 错误码ID | 错误信息 | 772| ------- | --------------------------------------------| 773| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 774| 62980103 | The image data is not supported. | 775| 62980246 | Failed to read the pixelMap. | 776| 62980248 | Pixelmap not allow modify. | 777 778**示例：** 779 780```ts 781import { BusinessError } from '@kit.BasicServicesKit'; 782 783async function CreateUnpremultipliedPixelMap() { 784 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 785 let bufferArr = new Uint8Array(color); 786 for (let i = 0; i < bufferArr.length; i += 4) { 787 bufferArr[i] = 255; 788 bufferArr[i+1] = 255; 789 bufferArr[i+2] = 122; 790 bufferArr[i+3] = 122; 791 } 792 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 793 let srcPixelmap = image.createPixelMapSync(color, optsForPre); 794 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 795 let dstPixelMap = image.createPixelMapSync(optsForUnpre); 796 image.createUnpremultipliedPixelMap(srcPixelmap, dstPixelMap).then(() => { 797 console.info('Succeeded in converting pixelmap.'); 798 }).catch((error: BusinessError) => { 799 console.error(`Failed to convert pixelmap. code is ${error.code}, message is ${error.message}`); 800 }) 801} 802``` 803 804 805## Picture<sup>13+</sup> 806 807一些包含特殊信息的图片可以解码为多图对象，多图对象一般包含主图、辅助图和元数据。其中主图包含图像的大部分信息，主要用于显示图像内容；辅助图用于存储与主图相关但不同的数据，展示图像更丰富的信息；元数据一般用来存储关于图像文件的信息。多图对象类用于读取或写入多图对象。在调用Picture的方法前，需要先通过[createPicture](#imagecreatepicture13)创建一个Picture实例。 808 809### 属性 810 811**系统能力：** SystemCapability.Multimedia.Image.Core 812 813### getMainPixelmap<sup>13+</sup> 814 815getMainPixelmap(): PixelMap 816 817获取主图的pixelmap。 818 819**系统能力：** SystemCapability.Multimedia.Image.Core 820 821**返回值：** 822 823| 类型 | 说明 | 824| ------------------- | ---------------------- | 825| [PixelMap](#pixelmap7) | 同步返回PixelMap对象。 | 826 827**示例：** 828 829```ts 830import { BusinessError } from '@kit.BasicServicesKit'; 831import { image } from '@kit.ImageKit'; 832 833async function GetMainPixelmap() { 834 let funcName = "getMainPixelmap"; 835 if (pictureObj != null) { 836 let mainPixelmap: image.PixelMap = pictureObj.getMainPixelmap(); 837 if (mainPixelmap != null) { 838 mainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 839 if (imageInfo != null) { 840 console.info('GetMainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 841 } 842 }).catch((error: BusinessError) => { 843 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 844 }); 845 } 846 } else { 847 console.info('PictureObj is null'); 848 } 849} 850``` 851 852### getHdrComposedPixelmap<sup>13+</sup> 853 854getHdrComposedPixelmap(): Promise\<PixelMap> 855 856合成hdr图并获取hdr图的pixelmap，使用Promise形式返回结果。 857 858**系统能力：** SystemCapability.Multimedia.Image.Core 859 860**返回值：** 861 862| 类型 | 说明 | 863| ----------------------------- | --------------------------- | 864| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 865 866**错误码：** 867 868以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 869 870| 错误码ID | 错误信息 | 871| -------- | ---------------------- | 872| 7600901 | Unknown error. | 873| 7600201 | Unsupported operation. | 874 875**示例：** 876 877```ts 878import { BusinessError } from '@kit.BasicServicesKit'; 879import { image } from '@kit.ImageKit'; 880 881async function GetHdrComposedPixelmap() { 882 let funcName = "getHdrComposedPixelmap"; 883 if (pictureObj != null) { //图片包含Hdr图。 884 let hdrComposedPixelmap: image.PixelMap = await pictureObj.getHdrComposedPixelmap(); 885 if (hdrComposedPixelmap != null) { 886 hdrComposedPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 887 if (imageInfo != null) { 888 console.info('GetHdrComposedPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 889 } 890 }).catch((error: BusinessError) => { 891 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 892 }); 893 } 894 } else { 895 console.info('PictureObj is null'); 896 } 897} 898``` 899 900### getGainmapPixelmap<sup>13+</sup> 901 902getGainmapPixelmap(): PixelMap | null 903 904获取增益图的pixelmap。 905 906**系统能力：** SystemCapability.Multimedia.Image.Core 907 908**返回值：** 909 910| 类型 | 说明 | 911| ------------------------- | -------------------------------------- | 912| [PixelMap](#pixelmap7) \| null | 返回Pixelmap对象，如果没有则返回null。 | 913 914**示例：** 915 916```ts 917import { BusinessError } from '@kit.BasicServicesKit'; 918import { image } from '@kit.ImageKit'; 919 920async function GetGainmapPixelmap() { 921 let funcName = "getGainmapPixelmap"; 922 if (pictureObj != null) { //图片包含增益图。 923 let gainPixelmap: image.PixelMap | null = pictureObj.getGainmapPixelmap(); 924 if (gainPixelmap != null) { 925 gainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 926 if (imageInfo != null) { 927 console.info('GetGainmapPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 928 } else { 929 console.info('GainPixelmap is null'); 930 } 931 }).catch((error: BusinessError) => { 932 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 933 }); 934 } else { 935 console.info('GainPixelmap is null'); 936 } 937 } else { 938 console.info('PictureObj is null'); 939 } 940} 941``` 942 943### setAuxiliaryPicture<sup>13+</sup> 944 945setAuxiliaryPicture(type: AuxiliaryPictureType, auxiliaryPicture: AuxiliaryPicture): void 946 947设置辅助图。 948 949**系统能力：** SystemCapability.Multimedia.Image.Core 950 951**参数：** 952 953| 参数名 | 类型 | 必填 | 说明 | 954| ---------------- | -------------------- | ---- | ------------ | 955| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 956| auxiliaryPicture | [AuxiliaryPicture](#auxiliarypicture13) | 是 | 辅助图对象。 | 957 958**错误码：** 959 960以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 961 962| 错误码ID | 错误信息 | 963| -------- | ------------------------------------------------------------ | 964| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 965 966**示例：** 967 968```ts 969import { image } from '@kit.ImageKit'; 970 971async function SetAuxiliaryPicture() { 972 const context = getContext(); 973 const resourceMgr = context.resourceManager; 974 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg");//需要支持hdr的图片。 975 let ops: image.SourceOptions = { 976 sourceDensity: 98, 977 } 978 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 979 let pixelMap: image.PixelMap = await imageSource.createPixelMap(); 980 let auxPicture: image.Picture = image.createPicture(pixelMap); 981 if (auxPicture != null) { 982 console.info('Create picture succeeded'); 983 } else { 984 console.info('Create picture failed'); 985 } 986 987 if (pictureObj != null) { 988 let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 989 let auxPictureObj: image.AuxiliaryPicture | null = await auxPicture.getAuxiliaryPicture(type); 990 if (auxPictureObj != null) { 991 pictureObj.setAuxiliaryPicture(type, auxPictureObj); 992 } 993 } 994} 995``` 996 997### getAuxiliaryPicture<sup>13+</sup> 998 999getAuxiliaryPicture(type: AuxiliaryPictureType): AuxiliaryPicture | null 1000 1001根据类型获取辅助图。 1002 1003**系统能力：** SystemCapability.Multimedia.Image.Core 1004 1005**参数：** 1006 1007| 参数名 | 类型 | 必填 | 说明 | 1008| ------ | -------------------- | ---- | ------------ | 1009| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 1010 1011**返回值：** 1012 1013| 类型 | 说明 | 1014| ---------------------- | ---------------------------------------------- | 1015| [AuxiliaryPicture](#auxiliarypicture13) \| null | 返回AuxiliaryPicture对象，如果没有则返回null。 | 1016 1017**错误码：** 1018 1019以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1020 1021| 错误码ID | 错误信息 | 1022| -------- | ------------------------------------------------------------ | 1023| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1024 1025**示例：** 1026 1027```ts 1028import { image } from '@kit.ImageKit'; 1029 1030async function GetAuxiliaryPicture() { 1031 if (pictureObj != null) { 1032 let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 1033 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(type); 1034 } 1035} 1036``` 1037 1038### setMetadata<sup>13+</sup> 1039 1040setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void> 1041 1042设置主图的元数据。 1043 1044**系统能力：** SystemCapability.Multimedia.Image.Core 1045 1046**参数：** 1047 1048| 参数名 | 类型 | 必填 | 说明 | 1049| ------------ | ------------ | ---- | ------------ | 1050| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型。 | 1051| metadata | [Metadata](#metadata13) | 是 | 元数据对象。 | 1052 1053**返回值：** 1054 1055| 类型 | 说明 | 1056| -------------- | -------------------------------------- | 1057| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1058 1059**错误码：** 1060 1061以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1062 1063| 错误码ID | 错误信息 | 1064| -------- | ------------------------------------------------------------ | 1065| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1066| 7600202 | Unsupported metadata. Possible causes: Unsupported metadata type. | 1067 1068**示例：** 1069 1070```ts 1071import { BusinessError } from '@kit.BasicServicesKit'; 1072import { image } from '@kit.ImageKit'; 1073 1074async function SetPictureObjMetadata() { 1075 const exifContext = getContext(); 1076 const exifResourceMgr = exifContext.resourceManager; 1077 const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");//含有exif metadata的图片。 1078 let exifOps: image.SourceOptions = { 1079 sourceDensity: 98, 1080 } 1081 let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps); 1082 let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap(); 1083 let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap); 1084 if (exifPictureObj != null) { 1085 console.info('Create picture succeeded'); 1086 } else { 1087 console.info('Create picture failed'); 1088 } 1089 1090 if (pictureObj != null) { 1091 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 1092 let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType); 1093 pictureObj.setMetadata(metadataType, exifMetaData).then(() => { 1094 console.info('Set metadata success'); 1095 }).catch((error: BusinessError) => { 1096 console.error('Failed to set metadata. error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 1097 }); 1098 } else { 1099 console.info('PictureObj is null'); 1100 } 1101} 1102``` 1103 1104### getMetadata<sup>13+</sup> 1105 1106getMetadata(metadataType: MetadataType): Promise\<Metadata> 1107 1108获取主图的元数据。 1109 1110**系统能力：** SystemCapability.Multimedia.Image.Core 1111 1112**参数：** 1113 1114| 参数名 | 类型 | 必填 | 说明 | 1115| ------------ | ------------ | ---- | ------------ | 1116| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型。 | 1117 1118**返回值：** 1119 1120| 类型 | 说明 | 1121| ------------------ | ------------------------- | 1122| Promise\<[Metadata](#metadata13)> | Promise对象。返回元数据。 | 1123 1124**错误码：** 1125 1126以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1127 1128| 错误码ID | 错误信息 | 1129| -------- | ------------------------------------------------------------ | 1130| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1131| 7600202 | Unsupported metadata. Possible causes: Unsupported metadata type. | 1132 1133**示例：** 1134 1135```ts 1136import { image } from '@kit.ImageKit'; 1137 1138async function GetPictureObjMetadataProperties() { 1139 if (pictureObj != null) { 1140 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 1141 let pictureObjMetaData: image.Metadata = await pictureObj.getMetadata(metadataType); 1142 if (pictureObjMetaData != null) { 1143 console.info('get picture metadata success'); 1144 } else { 1145 console.info('get picture metadata is failed'); 1146 } 1147 } else { 1148 console.info(" pictureObj is null"); 1149 } 1150} 1151``` 1152 1153### marshalling<sup>13+</sup> 1154 1155marshalling(sequence: rpc.MessageSequence): void 1156 1157将picture序列化后写入MessageSequence。 1158 1159**系统能力：** SystemCapability.Multimedia.Image.Core 1160 1161**参数：** 1162 1163| 参数名 | 类型 | 必填 | 说明 | 1164| -------- | ------------------------------------------------------------------- | ---- | ------------------------- | 1165| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 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| 62980097 | IPC error. | 1175 1176**示例：** 1177 1178```ts 1179import { BusinessError } from '@kit.BasicServicesKit'; 1180import { image } from '@kit.ImageKit'; 1181import { rpc } from '@kit.IPCKit'; 1182 1183class MySequence implements rpc.Parcelable { 1184 picture: image.Picture | null = null; 1185 constructor(conPicture: image.Picture) { 1186 this.picture = conPicture; 1187 } 1188 marshalling(messageSequence: rpc.MessageSequence) { 1189 if(this.picture != null) { 1190 this.picture.marshalling(messageSequence); 1191 console.info('Marshalling success !'); 1192 return true; 1193 } else { 1194 console.info('Marshalling failed !'); 1195 return false; 1196 } 1197 } 1198 unmarshalling(messageSequence : rpc.MessageSequence) { 1199 this.picture = image.createPictureFromParcel(messageSequence); 1200 this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => { 1201 console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 1202 }).catch((error: BusinessError) => { 1203 console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}'); 1204 }); 1205 return true; 1206 } 1207} 1208 1209async function Marshalling_UnMarshalling() { 1210 if (pictureObj != null) { 1211 let parcelable: MySequence = new MySequence(pictureObj); 1212 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 1213 // marshalling. 1214 data.writeParcelable(parcelable); 1215 let ret: MySequence = new MySequence(pictureObj); 1216 // unmarshalling. 1217 data.readParcelable(ret); 1218 } else { 1219 console.info('PictureObj is null'); 1220 } 1221} 1222``` 1223 1224### release<sup>13+</sup> 1225 1226release(): void 1227 1228释放picture对象。 1229 1230**系统能力：** SystemCapability.Multimedia.Image.Core 1231 1232**示例：** 1233 1234```ts 1235import { image } from '@kit.ImageKit'; 1236 1237async function Release() { 1238 let funcName = "Release"; 1239 if (pictureObj != null) { 1240 pictureObj.release(); 1241 if (pictureObj.getMainPixelmap() == null) { 1242 console.info(funcName, 'Success !'); 1243 } else { 1244 console.info(funcName, 'Failed !'); 1245 } 1246 } else { 1247 console.info('PictureObj is null'); 1248 } 1249} 1250``` 1251 1252## PixelMap<sup>7+</sup> 1253 1254图像像素类，用于读取或写入图像数据以及获取图像信息。在调用PixelMap的方法前，需要先通过[createPixelMap](#imagecreatepixelmap8)创建一个PixelMap实例。目前pixelmap序列化大小最大128MB，超过会送显失败。大小计算方式为(宽\*高\*每像素占用字节数)。 1255 1256从API version 11开始，PixelMap支持通过worker跨线程调用。当PixelMap通过[Worker](../apis-arkts/js-apis-worker.md)跨线程后，原线程的PixelMap的所有接口均不能调用，否则将报错501 服务器不具备完成请求的功能。 1257 1258在调用PixelMap的方法前，需要先通过[image.createPixelMap](#imagecreatepixelmap8)构建一个PixelMap对象。 1259 1260开发原子化服务请通过[ImageSoure](#imagesource)构建PixelMap对象。 1261 1262### 属性 1263 1264**系统能力：** SystemCapability.Multimedia.Image.Core 1265 1266| 名称 | 类型 | 可读 | 可写 | 说明 | 1267| -----------------| ------- | ---- | ---- | -------------------------- | 1268| isEditable | boolean | 是 | 否 | 设定是否图像像素可被编辑。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 1269| isStrideAlignment<sup>11+</sup> | boolean | 是 | 否 | 设定图像内存是否为DMA内存。 | 1270 1271### readPixelsToBuffer<sup>7+</sup> 1272 1273readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 1274 1275按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用Promise形式返回。 1276 1277**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1278 1279**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1280 1281**系统能力：** SystemCapability.Multimedia.Image.Core 1282 1283**参数：** 1284 1285| 参数名 | 类型 | 必填 | 说明 | 1286| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 1287| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1288 1289**返回值：** 1290 1291| 类型 | 说明 | 1292| -------------- | ----------------------------------------------- | 1293| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1294 1295**示例：** 1296 1297```ts 1298import { BusinessError } from '@kit.BasicServicesKit'; 1299 1300async function ReadPixelsToBuffer() { 1301 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1302 if (pixelMap != undefined) { 1303 pixelMap.readPixelsToBuffer(readBuffer).then(() => { 1304 console.info('Succeeded in reading image pixel data.'); // 符合条件则进入。 1305 }).catch((error: BusinessError) => { 1306 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1307 }) 1308 } 1309} 1310``` 1311 1312### readPixelsToBuffer<sup>7+</sup> 1313 1314readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback\<void>): void 1315 1316按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用callback形式返回。 1317 1318**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1319 1320**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1321 1322**系统能力：** SystemCapability.Multimedia.Image.Core 1323 1324**参数：** 1325 1326| 参数名 | 类型 | 必填 | 说明 | 1327| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 1328| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1329| callback | AsyncCallback\<void> | 是 | 回调函数。当读取像素数据到ArrayBuffer成功，err为undefined，否则为错误对象。 | 1330 1331**示例：** 1332 1333```ts 1334import { BusinessError } from '@kit.BasicServicesKit'; 1335 1336async function ReadPixelsToBuffer() { 1337 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1338 if (pixelMap != undefined) { 1339 pixelMap.readPixelsToBuffer(readBuffer, (error: BusinessError, res: void) => { 1340 if(error) { 1341 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1342 return; 1343 } else { 1344 console.info('Succeeded in reading image pixel data.'); //符合条件则进入。 1345 } 1346 }) 1347 } 1348} 1349``` 1350 1351### readPixelsToBufferSync<sup>12+</sup> 1352 1353readPixelsToBufferSync(dst: ArrayBuffer): void 1354 1355按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，同步返回结果。 1356 1357**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1358 1359**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1360 1361**系统能力：** SystemCapability.Multimedia.Image.Core 1362 1363**参数：** 1364 1365| 参数名 | 类型 | 必填 | 说明 | 1366| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 1367| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1368 1369**错误码：** 1370 1371以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1372 1373| 错误码ID | 错误信息 | 1374| ------- | --------------------------------------------| 1375| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1376| 501 | Resource Unavailable | 1377 1378**示例：** 1379 1380```ts 1381import { BusinessError } from '@kit.BasicServicesKit'; 1382 1383async function ReadPixelsToBufferSync() { 1384 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1385 if (pixelMap != undefined) { 1386 pixelMap.readPixelsToBufferSync(readBuffer); 1387 } 1388} 1389``` 1390 1391### readPixels<sup>7+</sup> 1392 1393readPixels(area: PositionArea): Promise\<void> 1394 1395固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，使用Promise形式返回。 1396 1397可用公式计算PositionArea需要申请的内存大小。 1398 1399YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1400 1401RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1402 1403**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1404 1405**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1406 1407**系统能力：** SystemCapability.Multimedia.Image.Core 1408 1409**参数：** 1410 1411| 参数名 | 类型 | 必填 | 说明 | 1412| ------ | ------------------------------ | ---- | ------------------------ | 1413| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1414 1415**返回值：** 1416 1417| 类型 | 说明 | 1418| :------------- | :-------------------------------------------------- | 1419| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1420 1421**示例：** 1422 1423```ts 1424import { BusinessError } from '@kit.BasicServicesKit'; 1425 1426async function ReadPixelsRGBA() { 1427 const area: image.PositionArea = { 1428 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1429 offset: 0, 1430 stride: 8, 1431 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1432 }; 1433 if (pixelMap != undefined) { 1434 pixelMap.readPixels(area).then(() => { 1435 console.info('Succeeded in reading the image data in the area.'); //符合条件则进入。 1436 }).catch((error: BusinessError) => { 1437 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1438 }) 1439 } 1440} 1441 1442async function ReadPixelsYUV() { 1443 const area: image.PositionArea = { 1444 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1445 offset: 0, 1446 stride: 8, 1447 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1448 }; 1449 if (pixelMap != undefined) { 1450 pixelMap.readPixels(area).then(() => { 1451 console.info('Succeeded in reading the image data in the area.'); //符合条件则进入。 1452 }).catch((error: BusinessError) => { 1453 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1454 }) 1455 } 1456} 1457``` 1458 1459### readPixels<sup>7+</sup> 1460 1461readPixels(area: PositionArea, callback: AsyncCallback\<void>): void 1462 1463固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，使用callback形式返回。 1464 1465可用公式计算PositionArea需要申请的内存大小。 1466 1467YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1468 1469RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1470 1471**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1472 1473**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1474 1475**系统能力：** SystemCapability.Multimedia.Image.Core 1476 1477**参数：** 1478 1479| 参数名 | 类型 | 必填 | 说明 | 1480| -------- | ------------------------------ | ---- | ------------------------------ | 1481| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1482| callback | AsyncCallback\<void> | 是 | 回调函数。当读取区域内的图片数据成功，err为undefined，否则为错误对象。 | 1483 1484**示例：** 1485 1486```ts 1487import { BusinessError } from '@kit.BasicServicesKit'; 1488 1489async function ReadPixelsRGBA() { 1490 const area: image.PositionArea = { 1491 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1492 offset: 0, 1493 stride: 8, 1494 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1495 }; 1496 if (pixelMap != undefined) { 1497 pixelMap.readPixels(area, (error: BusinessError) => { 1498 if (error) { 1499 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 1500 return; 1501 } else { 1502 console.info('Succeeded in reading pixelmap from the specified area.'); 1503 } 1504 }) 1505 } 1506} 1507 1508async function ReadPixelsYUV() { 1509 const area: image.PositionArea = { 1510 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1511 offset: 0, 1512 stride: 8, 1513 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1514 }; 1515 if (pixelMap != undefined) { 1516 pixelMap.readPixels(area, (error: BusinessError) => { 1517 if (error) { 1518 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 1519 return; 1520 } else { 1521 console.info('Succeeded in reading pixelmap from the specified area.'); 1522 } 1523 }) 1524 } 1525} 1526``` 1527 1528### readPixelsSync<sup>12+</sup> 1529 1530readPixelsSync(area: PositionArea): void 1531 1532固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，同步返回结果。 1533 1534**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1535 1536**系统能力：** SystemCapability.Multimedia.Image.Core 1537 1538**参数：** 1539 1540| 参数名 | 类型 | 必填 | 说明 | 1541| ------ | ------------------------------ | ---- | ------------------------ | 1542| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1543 1544**错误码：** 1545 1546以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1547 1548| 错误码ID | 错误信息 | 1549| ------- | --------------------------------------------| 1550| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1551| 501 | Resource Unavailable | 1552 1553**示例：** 1554 1555```ts 1556import { BusinessError } from '@kit.BasicServicesKit'; 1557 1558async function ReadPixelsSync() { 1559 const area : image.PositionArea = { 1560 pixels: new ArrayBuffer(8), 1561 offset: 0, 1562 stride: 8, 1563 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1564 }; 1565 if (pixelMap != undefined) { 1566 pixelMap.readPixelsSync(area); 1567 } 1568} 1569``` 1570 1571### writePixels<sup>7+</sup> 1572 1573writePixels(area: PositionArea): Promise\<void> 1574 1575固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，使用Promise形式返回。 1576 1577可用公式计算PositionArea需要申请的内存大小。 1578 1579YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1580 1581RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1582 1583**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1584 1585**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1586 1587**系统能力：** SystemCapability.Multimedia.Image.Core 1588 1589**参数：** 1590 1591| 参数名 | 类型 | 必填 | 说明 | 1592| ------ | ------------------------------ | ---- | -------------------- | 1593| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1594 1595**返回值：** 1596 1597| 类型 | 说明 | 1598| :------------- | :-------------------------------------------------- | 1599| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1600 1601**示例：** 1602 1603```ts 1604import { BusinessError } from '@kit.BasicServicesKit'; 1605 1606async function WritePixelsRGBA() { 1607 const area: image.PositionArea = { 1608 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1609 offset: 0, 1610 stride: 8, 1611 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1612 }; 1613 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1614 for (let i = 0; i < bufferArr.length; i++) { 1615 bufferArr[i] = i + 1; 1616 } 1617 if (pixelMap != undefined) { 1618 pixelMap.writePixels(area).then(() => { 1619 console.info('Succeeded in writing pixelmap into the specified area.'); 1620 }).catch((error: BusinessError) => { 1621 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1622 }) 1623 } 1624} 1625 1626async function WritePixelsYUV() { 1627 const area: image.PositionArea = { 1628 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1629 offset: 0, 1630 stride: 8, 1631 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1632 }; 1633 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1634 for (let i = 0; i < bufferArr.length; i++) { 1635 bufferArr[i] = i + 1; 1636 } 1637 if (pixelMap != undefined) { 1638 pixelMap.writePixels(area).then(() => { 1639 console.info('Succeeded in writing pixelmap into the specified area.'); 1640 }).catch((error: BusinessError) => { 1641 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1642 }) 1643 } 1644} 1645``` 1646 1647### writePixels<sup>7+</sup> 1648 1649writePixels(area: PositionArea, callback: AsyncCallback\<void>): void 1650 1651固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，使用callback形式返回。 1652 1653可用公式计算PositionArea需要申请的内存大小。 1654 1655YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1656 1657RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1658 1659**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1660 1661**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1662 1663**系统能力：** SystemCapability.Multimedia.Image.Core 1664 1665**参数：** 1666 1667| 参数名 | 类型 | 必填 | 说明 | 1668| --------- | ------------------------------ | ---- | ------------------------------ | 1669| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1670| callback | AsyncCallback\<void> | 是 | 回调函数，当写入成功，err为undefined，否则为错误对象。 | 1671 1672**示例：** 1673 1674```ts 1675import { BusinessError } from '@kit.BasicServicesKit'; 1676 1677async function WritePixelsRGBA() { 1678 const area: image.PositionArea = { pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1679 offset: 0, 1680 stride: 8, 1681 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1682 }; 1683 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1684 for (let i = 0; i < bufferArr.length; i++) { 1685 bufferArr[i] = i + 1; 1686 } 1687 if (pixelMap != undefined) { 1688 pixelMap.writePixels(area, (error : BusinessError) => { 1689 if (error) { 1690 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1691 return; 1692 } else { 1693 console.info('Succeeded in writing pixelmap into the specified area.'); 1694 } 1695 }) 1696 } 1697} 1698 1699async function WritePixelsYUV() { 1700 const area: image.PositionArea = { pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1701 offset: 0, 1702 stride: 8, 1703 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1704 }; 1705 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1706 for (let i = 0; i < bufferArr.length; i++) { 1707 bufferArr[i] = i + 1; 1708 } 1709 if (pixelMap != undefined) { 1710 pixelMap.writePixels(area, (error : BusinessError) => { 1711 if (error) { 1712 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1713 return; 1714 } else { 1715 console.info('Succeeded in writing pixelmap into the specified area.'); 1716 } 1717 }) 1718 } 1719} 1720``` 1721 1722### writePixelsSync<sup>12+</sup> 1723 1724writePixelsSync(area: PositionArea): void 1725 1726固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，同步回结果。 1727 1728**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1729 1730**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1731 1732**系统能力：** SystemCapability.Multimedia.Image.Core 1733 1734**参数：** 1735 1736| 参数名 | 类型 | 必填 | 说明 | 1737| ------ | ------------------------------ | ---- | -------------------- | 1738| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1739 1740**错误码：** 1741 1742以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1743 1744| 错误码ID | 错误信息 | 1745| ------- | --------------------------------------------| 1746| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1747| 501 | Resource Unavailable | 1748 1749**示例：** 1750 1751```ts 1752import { BusinessError } from '@kit.BasicServicesKit'; 1753 1754async function WritePixelsSync() { 1755 const area: image.PositionArea = { 1756 pixels: new ArrayBuffer(8), 1757 offset: 0, 1758 stride: 8, 1759 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1760 }; 1761 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1762 for (let i = 0; i < bufferArr.length; i++) { 1763 bufferArr[i] = i + 1; 1764 } 1765 if (pixelMap != undefined) { 1766 pixelMap.writePixelsSync(area); 1767 } 1768} 1769``` 1770 1771### writeBufferToPixels<sup>7+</sup> 1772 1773writeBufferToPixels(src: ArrayBuffer): Promise\<void> 1774 1775按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用Promise形式返回。 1776 1777**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1778 1779**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1780 1781**系统能力：** SystemCapability.Multimedia.Image.Core 1782 1783**参数：** 1784 1785| 参数名 | 类型 | 必填 | 说明 | 1786| ------ | ----------- | ---- | -------------- | 1787| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1788 1789**返回值：** 1790 1791| 类型 | 说明 | 1792| -------------- | ----------------------------------------------- | 1793| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1794 1795**示例：** 1796 1797```ts 1798import { BusinessError } from '@kit.BasicServicesKit'; 1799 1800async function WriteBufferToPixels() { 1801 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1802 let bufferArr: Uint8Array = new Uint8Array(color); 1803 for (let i = 0; i < bufferArr.length; i++) { 1804 bufferArr[i] = i + 1; 1805 } 1806 if (pixelMap != undefined) { 1807 pixelMap.writeBufferToPixels(color).then(() => { 1808 console.info("Succeeded in writing data from a buffer to a PixelMap."); 1809 }).catch((error: BusinessError) => { 1810 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 1811 }) 1812 } 1813} 1814``` 1815 1816### writeBufferToPixels<sup>7+</sup> 1817 1818writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback\<void>): void 1819 1820按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用callback形式返回。 1821 1822**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1823 1824**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1825 1826**系统能力：** SystemCapability.Multimedia.Image.Core 1827 1828**参数：** 1829 1830| 参数名 | 类型 | 必填 | 说明 | 1831| -------- | -------------------- | ---- | ------------------------------ | 1832| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1833| callback | AsyncCallback\<void> | 是 | 回调函数。当缓冲区中的图像像素数据写入PixelMap成功，err为undefined，否则为错误对象。 | 1834 1835**示例：** 1836 1837```ts 1838import { BusinessError } from '@kit.BasicServicesKit'; 1839 1840async function WriteBufferToPixels() { 1841 const color: ArrayBuffer = new ArrayBuffer(96); //96为需要创建的像素buffer大小，取值为：height * width *4。 1842 let bufferArr: Uint8Array = new Uint8Array(color); 1843 for (let i = 0; i < bufferArr.length; i++) { 1844 bufferArr[i] = i + 1; 1845 } 1846 if (pixelMap != undefined) { 1847 pixelMap.writeBufferToPixels(color, (error: BusinessError) => { 1848 if (error) { 1849 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 1850 return; 1851 } else { 1852 console.info("Succeeded in writing data from a buffer to a PixelMap."); 1853 } 1854 }) 1855 } 1856} 1857``` 1858 1859### writeBufferToPixelsSync<sup>12+</sup> 1860 1861writeBufferToPixelsSync(src: ArrayBuffer): void 1862 1863按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，同步返回结果。 1864 1865**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1866 1867**系统能力：** SystemCapability.Multimedia.Image.Core 1868 1869**参数：** 1870 1871| 参数名 | 类型 | 必填 | 说明 | 1872| ------ | ----------- | ---- | -------------- | 1873| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1874 1875**错误码：** 1876 1877以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1878 1879| 错误码ID | 错误信息 | 1880| ------- | --------------------------------------------| 1881| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1882| 501 | Resource Unavailable | 1883 1884**示例：** 1885 1886```ts 1887import { BusinessError } from '@kit.BasicServicesKit'; 1888 1889async function WriteBufferToPixelsSync() { 1890 const color : ArrayBuffer = new ArrayBuffer(96); //96为需要创建的像素buffer大小，取值为：height * width *4。 1891 let bufferArr : Uint8Array = new Uint8Array(color); 1892 for (let i = 0; i < bufferArr.length; i++) { 1893 bufferArr[i] = i + 1; 1894 } 1895 if (pixelMap != undefined) { 1896 pixelMap.writeBufferToPixelsSync(color); 1897 } 1898} 1899``` 1900 1901 1902### getImageInfo<sup>7+</sup> 1903 1904getImageInfo(): Promise\<ImageInfo> 1905 1906获取图像像素信息，使用Promise形式返回获取的图像像素信息。 1907 1908**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1909 1910**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1911 1912**系统能力：** SystemCapability.Multimedia.Image.Core 1913 1914**返回值：** 1915 1916| 类型 | 说明 | 1917| --------------------------------- | ----------------------------------------------------------- | 1918| Promise\<[ImageInfo](#imageinfo)> | Promise对象，返回图像像素信息。 | 1919 1920**示例：** 1921 1922```ts 1923import { BusinessError } from '@kit.BasicServicesKit'; 1924 1925async function GetImageInfo() { 1926 if (pixelMap != undefined) { 1927 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 1928 if (imageInfo != undefined) { 1929 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 1930 } 1931 }).catch((error: BusinessError) => { 1932 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 1933 }) 1934 } 1935} 1936``` 1937 1938### getImageInfo<sup>7+</sup> 1939 1940getImageInfo(callback: AsyncCallback\<ImageInfo>): void 1941 1942获取图像像素信息，使用callback形式返回获取的图像像素信息。 1943 1944**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1945 1946**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1947 1948**系统能力：** SystemCapability.Multimedia.Image.Core 1949 1950**参数：** 1951 1952| 参数名 | 类型 | 必填 | 说明 | 1953| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 1954| callback | AsyncCallback\<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图像像素信息成功，err为undefined，data为获取到的图像像素信息；否则为错误对象。 | 1955 1956**示例:** 1957 1958```ts 1959import { BusinessError } from '@kit.BasicServicesKit'; 1960 1961async function GetImageInfo() { 1962 if (pixelMap != undefined) { 1963 pixelMap.getImageInfo((error: BusinessError, imageInfo: image.ImageInfo) => { 1964 if (error) { 1965 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 1966 return; 1967 } else { 1968 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 1969 } 1970 }) 1971 } 1972} 1973``` 1974 1975### getImageInfoSync<sup>12+</sup> 1976 1977getImageInfoSync(): ImageInfo 1978 1979以同步方法获取图像像素信息。 1980 1981**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1982 1983**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1984 1985**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1986 1987**返回值：** 1988 1989| 类型 | 说明 | 1990| --------------------------------- | ----------------------------------------------------------- | 1991| [ImageInfo](#imageinfo) | 图像像素信息。 | 1992 1993**错误码：** 1994 1995以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1996 1997| 错误码ID | 错误信息 | 1998| ------- | --------------------------------------------| 1999| 501 | Resource Unavailable | 2000 2001**示例：** 2002 2003```ts 2004import { BusinessError } from '@kit.BasicServicesKit'; 2005 2006async function GetImageInfoSync() { 2007 if (pixelMap != undefined) { 2008 let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync(); 2009 return imageInfo; 2010 } 2011 return undefined; 2012} 2013``` 2014 2015### getBytesNumberPerRow<sup>7+</sup> 2016 2017getBytesNumberPerRow(): number 2018 2019获取图像像素每行字节数。 2020 2021**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2022 2023**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2024 2025**系统能力：** SystemCapability.Multimedia.Image.Core 2026 2027**返回值：** 2028 2029| 类型 | 说明 | 2030| ------ | -------------------- | 2031| number | 图像像素的行字节数。 | 2032 2033**示例：** 2034 2035```ts 2036let rowCount: number = pixelMap.getBytesNumberPerRow(); 2037``` 2038 2039### getPixelBytesNumber<sup>7+</sup> 2040 2041getPixelBytesNumber(): number 2042 2043获取图像像素的总字节数。 2044 2045**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2046 2047**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2048 2049**系统能力：** SystemCapability.Multimedia.Image.Core 2050 2051**返回值：** 2052 2053| 类型 | 说明 | 2054| ------ | -------------------- | 2055| number | 图像像素的总字节数。 | 2056 2057**示例：** 2058 2059```ts 2060let pixelBytesNumber: number = pixelMap.getPixelBytesNumber(); 2061``` 2062 2063### getDensity<sup>9+</sup> 2064 2065getDensity():number 2066 2067获取当前图像像素的密度。 2068 2069**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2070 2071**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2072 2073**系统能力：** SystemCapability.Multimedia.Image.Core 2074 2075**返回值：** 2076 2077| 类型 | 说明 | 2078| ------ | --------------- | 2079| number | 图像像素的密度。| 2080 2081**示例：** 2082 2083```ts 2084let getDensity: number = pixelMap.getDensity(); 2085``` 2086 2087### opacity<sup>9+</sup> 2088 2089opacity(rate: number, callback: AsyncCallback\<void>): void 2090 2091通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用callback形式返回。 2092 2093**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2094 2095**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2096 2097**系统能力：** SystemCapability.Multimedia.Image.Core 2098 2099**参数：** 2100 2101| 参数名 | 类型 | 必填 | 说明 | 2102| -------- | -------------------- | ---- | ------------------------------ | 2103| rate | number | 是 | 透明比率的值。 | 2104| callback | AsyncCallback\<void> | 是 | 回调函数。当设置透明比率成功，err为undefined，否则为错误对象。 | 2105 2106**示例：** 2107 2108```ts 2109import { BusinessError } from '@kit.BasicServicesKit'; 2110 2111async function Opacity() { 2112 let rate: number = 0.5; 2113 if (pixelMap != undefined) { 2114 pixelMap.opacity(rate, (err: BusinessError) => { 2115 if (err) { 2116 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 2117 return; 2118 } else { 2119 console.info("Succeeded in setting opacity."); 2120 } 2121 }) 2122 } 2123} 2124``` 2125 2126### opacity<sup>9+</sup> 2127 2128opacity(rate: number): Promise\<void> 2129 2130通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用Promise形式返回。 2131 2132**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2133 2134**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2135 2136**系统能力：** SystemCapability.Multimedia.Image.Core 2137 2138**参数：** 2139 2140| 参数名 | 类型 | 必填 | 说明 | 2141| ------ | ------ | ---- | --------------------------- | 2142| rate | number | 是 | 透明比率的值。| 2143 2144**返回值：** 2145 2146| 类型 | 说明 | 2147| -------------- | ----------------------------------------------- | 2148| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2149 2150**示例：** 2151 2152```ts 2153import { BusinessError } from '@kit.BasicServicesKit'; 2154 2155async function Opacity() { 2156 let rate: number = 0.5; 2157 if (pixelMap != undefined) { 2158 pixelMap.opacity(rate).then(() => { 2159 console.info('Succeeded in setting opacity.'); 2160 }).catch((err: BusinessError) => { 2161 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 2162 }) 2163 } 2164} 2165``` 2166 2167### opacitySync<sup>12+</sup> 2168 2169opacitySync(rate: number): void 2170 2171设置PixelMap的透明比率，yuv图片不支持设置透明度，初始化PixelMap并同步返回结果。 2172 2173**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2174 2175**系统能力：** SystemCapability.Multimedia.Image.Core 2176 2177**参数：** 2178 2179| 参数名 | 类型 | 必填 | 说明 | 2180| -------- | -------------------- | ---- | ------------------------------ | 2181| rate | number | 是 | 透明比率的值。 | 2182 2183**错误码：** 2184 2185以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2186 2187| 错误码ID | 错误信息 | 2188| ------- | --------------------------------------------| 2189| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2190| 501 | Resource Unavailable | 2191 2192**示例：** 2193 2194```ts 2195import { BusinessError } from '@kit.BasicServicesKit'; 2196 2197async function OpacitySync() { 2198 let rate : number = 0.5; 2199 if (pixelMap != undefined) { 2200 pixelMap.opacitySync(rate); 2201 } 2202} 2203``` 2204 2205### createAlphaPixelmap<sup>9+</sup> 2206 2207createAlphaPixelmap(): Promise\<PixelMap> 2208 2209根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用Promise形式返回。 2210 2211**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2212 2213**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2214 2215**系统能力：** SystemCapability.Multimedia.Image.Core 2216 2217**返回值：** 2218 2219| 类型 | 说明 | 2220| -------------------------------- | --------------------------- | 2221| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 2222 2223**示例：** 2224 2225```ts 2226import { BusinessError } from '@kit.BasicServicesKit'; 2227 2228async function CreateAlphaPixelmap() { 2229 if (pixelMap != undefined) { 2230 pixelMap.createAlphaPixelmap().then((alphaPixelMap: image.PixelMap) => { 2231 console.info('Succeeded in creating alpha pixelmap.'); 2232 }).catch((error: BusinessError) => { 2233 console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`); 2234 }) 2235 } 2236} 2237``` 2238 2239### createAlphaPixelmap<sup>9+</sup> 2240 2241createAlphaPixelmap(callback: AsyncCallback\<PixelMap>): void 2242 2243根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用callback形式返回。 2244 2245**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2246 2247**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2248 2249**系统能力：** SystemCapability.Multimedia.Image.Core 2250 2251**参数：** 2252 2253| 参数名 | 类型 | 必填 | 说明 | 2254| -------- | ------------------------ | ---- | ------------------------ | 2255| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 2256 2257**示例：** 2258 2259```ts 2260import { BusinessError } from '@kit.BasicServicesKit'; 2261 2262async function CreateAlphaPixelmap() { 2263 if (pixelMap != undefined) { 2264 pixelMap.createAlphaPixelmap((err: BusinessError, alphaPixelMap: image.PixelMap) => { 2265 if (alphaPixelMap == undefined) { 2266 console.error(`Failed to obtain new pixel map. code is ${err.code}, message is ${err.message}`); 2267 return; 2268 } else { 2269 console.info('Succeeded in obtaining new pixel map.'); 2270 } 2271 }) 2272 } 2273} 2274``` 2275 2276### createAlphaPixelmapSync<sup>12+</sup> 2277 2278createAlphaPixelmapSync(): PixelMap 2279 2280根据Alpha通道的信息，生成一个仅包含Alpha通道信息的PixelMap，可用于阴影效果，yuv格式不支持此接口，同步返回PixelMap类型的结果。 2281 2282**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2283 2284**系统能力：** SystemCapability.Multimedia.Image.Core 2285 2286**返回值：** 2287 2288| 类型 | 说明 | 2289| -------------------------------- | --------------------- | 2290| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2291 2292**错误码：** 2293 2294以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2295 2296| 错误码ID | 错误信息 | 2297| ------- | --------------------------------------------| 2298| 401 | Parameter error. Possible causes: 1.Parameter verification failed | 2299| 501 | Resource Unavailable | 2300 2301**示例：** 2302 2303```ts 2304import { BusinessError } from '@kit.BasicServicesKit'; 2305 2306async function CreateAlphaPixelmapSync() { 2307 if (pixelMap != undefined) { 2308 let pixelmap : image.PixelMap = pixelMap.createAlphaPixelmapSync(); 2309 return pixelmap; 2310 } 2311 return undefined; 2312} 2313``` 2314 2315### scale<sup>9+</sup> 2316 2317scale(x: number, y: number, callback: AsyncCallback\<void>): void 2318 2319根据输入的宽高的缩放倍数对图片进行缩放，使用callback形式返回。 2320 2321> **说明：** 2322> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2323> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高 2324 2325**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2326 2327**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2328 2329**系统能力：** SystemCapability.Multimedia.Image.Core 2330 2331**参数：** 2332 2333| 参数名 | 类型 | 必填 | 说明 | 2334| -------- | -------------------- | ---- | ------------------------------- | 2335| x | number | 是 | 宽度的缩放倍数。| 2336| y | number | 是 | 高度的缩放倍数。| 2337| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行缩放成功，err为undefined，否则为错误对象。 | 2338 2339**示例：** 2340 2341```ts 2342import { BusinessError } from '@kit.BasicServicesKit'; 2343 2344async function Scale() { 2345 let scaleX: number = 2.0; 2346 let scaleY: number = 1.0; 2347 if (pixelMap != undefined) { 2348 pixelMap.scale(scaleX, scaleY, (err: BusinessError) => { 2349 if (err) { 2350 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2351 return; 2352 } else { 2353 console.info("Succeeded in scaling pixelmap."); 2354 } 2355 }) 2356 } 2357} 2358``` 2359 2360### scale<sup>9+</sup> 2361 2362scale(x: number, y: number): Promise\<void> 2363 2364根据输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 2365 2366> **说明：** 2367> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2368> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高 2369 2370**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2371 2372**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2373 2374**系统能力：** SystemCapability.Multimedia.Image.Core 2375 2376**参数：** 2377 2378| 参数名 | 类型 | 必填 | 说明 | 2379| ------ | ------ | ---- | ------------------------------- | 2380| x | number | 是 | 宽度的缩放倍数。| 2381| y | number | 是 | 高度的缩放倍数。| 2382 2383**返回值：** 2384 2385| 类型 | 说明 | 2386| -------------- | --------------------------- | 2387| Promise\<void> | Promise对象。无返回结果的Promise对象。| 2388 2389**示例：** 2390 2391```ts 2392import { BusinessError } from '@kit.BasicServicesKit'; 2393 2394async function Scale() { 2395 let scaleX: number = 2.0; 2396 let scaleY: number = 1.0; 2397 if (pixelMap != undefined) { 2398 pixelMap.scale(scaleX, scaleY).then(() => { 2399 console.info('Succeeded in scaling pixelmap.'); 2400 }).catch((err: BusinessError) => { 2401 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2402 2403 }) 2404 } 2405} 2406``` 2407 2408### scaleSync<sup>12+</sup> 2409 2410scaleSync(x: number, y: number): void 2411 2412根据输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 2413 2414> **说明：** 2415> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2416> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高 2417 2418**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2419 2420**系统能力：** SystemCapability.Multimedia.Image.Core 2421 2422**参数：** 2423 2424| 参数名 | 类型 | 必填 | 说明 | 2425| ------ | ------ | ---- | ------------------------------- | 2426| x | number | 是 | 宽度的缩放倍数。| 2427| y | number | 是 | 高度的缩放倍数。| 2428 2429**错误码：** 2430 2431以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2432 2433| 错误码ID | 错误信息 | 2434| ------- | --------------------------------------------| 2435| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2436| 501 | Resource Unavailable | 2437 2438**示例：** 2439 2440```ts 2441import { BusinessError } from '@kit.BasicServicesKit'; 2442 2443async function ScaleSync() { 2444 let scaleX: number = 2.0; 2445 let scaleY: number = 1.0; 2446 if (pixelMap != undefined) { 2447 pixelMap.scaleSync(scaleX, scaleY); 2448 } 2449} 2450``` 2451 2452### scale<sup>12+</sup> 2453 2454scale(x: number, y: number, level: AntiAliasingLevel): Promise\<void> 2455 2456根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 2457 2458> **说明：** 2459> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2460> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高 2461 2462**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2463 2464**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2465 2466**系统能力：** SystemCapability.Multimedia.Image.Core 2467 2468**参数：** 2469 2470| 参数名 | 类型 | 必填 | 说明 | 2471| ------ | ------ | ---- | ------------------------------- | 2472| x | number | 是 | 宽度的缩放倍数。| 2473| y | number | 是 | 高度的缩放倍数。| 2474| level | [AntiAliasingLevel](#antialiasinglevel12) | 是 | 采用的缩放算法。| 2475 2476**返回值：** 2477 2478| 类型 | 说明 | 2479| -------------- | --------------------------- | 2480| Promise\<void> | Promise对象。无返回结果的Promise对象。| 2481 2482**错误码：** 2483 2484以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2485 2486| 错误码ID | 错误信息 | 2487| ------- | --------------------------------------------| 2488| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2489| 501 | Resource Unavailable | 2490 2491**示例：** 2492 2493```ts 2494import { BusinessError } from '@kit.BasicServicesKit'; 2495 2496async function Scale() { 2497 let scaleX: number = 2.0; 2498 let scaleY: number = 1.0; 2499 if (pixelMap != undefined) { 2500 pixelMap.scale(scaleX, scaleY, image.AntiAliasingLevel.LOW).then(() => { 2501 console.info('Succeeded in scaling pixelmap.'); 2502 }).catch((err: BusinessError) => { 2503 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2504 2505 }) 2506 } 2507} 2508``` 2509 2510### scaleSync<sup>12+</sup> 2511 2512scaleSync(x: number, y: number, level: AntiAliasingLevel): void 2513 2514根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 2515 2516> **说明：** 2517> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2518> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高 2519 2520**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2521 2522**系统能力：** SystemCapability.Multimedia.Image.Core 2523 2524**参数：** 2525 2526| 参数名 | 类型 | 必填 | 说明 | 2527| ------ | ------ | ---- | ------------------------------- | 2528| x | number | 是 | 宽度的缩放倍数。| 2529| y | number | 是 | 高度的缩放倍数。| 2530| level | [AntiAliasingLevel](#antialiasinglevel12) | 是 | 采用的缩放算法。| 2531 2532**错误码：** 2533 2534以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2535 2536| 错误码ID | 错误信息 | 2537| ------- | --------------------------------------------| 2538| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2539| 501 | Resource Unavailable | 2540 2541**示例：** 2542 2543```ts 2544import { BusinessError } from '@kit.BasicServicesKit'; 2545 2546async function ScaleSync() { 2547 let scaleX: number = 2.0; 2548 let scaleY: number = 1.0; 2549 if (pixelMap != undefined) { 2550 pixelMap.scaleSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 2551 } 2552} 2553``` 2554 2555### translate<sup>9+</sup> 2556 2557translate(x: number, y: number, callback: AsyncCallback\<void>): void 2558 2559根据输入的坐标对图片进行位置变换，使用callback形式返回。 2560 2561translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2562 2563**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2564 2565**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2566 2567**系统能力：** SystemCapability.Multimedia.Image.Core 2568 2569**参数：** 2570 2571| 参数名 | 类型 | 必填 | 说明 | 2572| -------- | -------------------- | ---- | ----------------------------- | 2573| x | number | 是 | 区域横坐标。单位：像素。 | 2574| y | number | 是 | 区域纵坐标。单位：像素。 | 2575| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行位置变换成功，err为undefined，否则为错误对象。| 2576 2577**示例：** 2578 2579```ts 2580import { BusinessError } from '@kit.BasicServicesKit'; 2581 2582async function Translate() { 2583 let translateX: number = 50.0; 2584 let translateY: number = 10.0; 2585 if (pixelMap != undefined) { 2586 pixelMap.translate(translateX, translateY, (err: BusinessError) => { 2587 if (err) { 2588 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 2589 return; 2590 } else { 2591 console.info("Succeeded in translating pixelmap."); 2592 } 2593 }) 2594 } 2595} 2596``` 2597 2598### translate<sup>9+</sup> 2599 2600translate(x: number, y: number): Promise\<void> 2601 2602根据输入的坐标对图片进行位置变换，使用Promise形式返回。 2603 2604translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2605 2606**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2607 2608**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2609 2610**系统能力：** SystemCapability.Multimedia.Image.Core 2611 2612**参数：** 2613 2614| 参数名 | 类型 | 必填 | 说明 | 2615| ------ | ------ | ---- | ----------- | 2616| x | number | 是 | 区域横坐标。单位：像素。 | 2617| y | number | 是 | 区域纵坐标。单位：像素。 | 2618 2619**返回值：** 2620 2621| 类型 | 说明 | 2622| -------------- | --------------------------- | 2623| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2624 2625**示例：** 2626 2627```ts 2628import { BusinessError } from '@kit.BasicServicesKit'; 2629 2630async function Translate() { 2631 let translateX: number = 50.0; 2632 let translateY: number = 10.0; 2633 if (pixelMap != undefined) { 2634 pixelMap.translate(translateX, translateY).then(() => { 2635 console.info('Succeeded in translating pixelmap.'); 2636 }).catch((err: BusinessError) => { 2637 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 2638 }) 2639 } 2640} 2641``` 2642 2643### translateSync<sup>12+</sup> 2644 2645translateSync(x: number, y: number): void 2646 2647根据输入的坐标对图片进行位置变换，同步返回结果。 2648 2649translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2650 2651**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2652 2653**系统能力：** SystemCapability.Multimedia.Image.Core 2654 2655**参数：** 2656 2657| 参数名 | 类型 | 必填 | 说明 | 2658| -------- | -------------------- | ---- | ------------------------------- | 2659| x | number | 是 | 区域横坐标。单位：像素。 | 2660| y | number | 是 | 区域纵坐标。单位：像素。 | 2661 2662**错误码：** 2663 2664以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2665 2666| 错误码ID | 错误信息 | 2667| ------- | --------------------------------------------| 2668| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2669| 501 | Resource Unavailable | 2670 2671**示例：** 2672 2673```ts 2674import { BusinessError } from '@kit.BasicServicesKit'; 2675 2676async function TranslateSync() { 2677 let translateX : number = 50.0; 2678 let translateY : number = 10.0; 2679 if (pixelMap != undefined) { 2680 pixelMap.translateSync(translateX, translateY); 2681 } 2682} 2683``` 2684 2685### rotate<sup>9+</sup> 2686 2687rotate(angle: number, callback: AsyncCallback\<void>): void 2688 2689根据输入的角度对图片进行旋转，使用callback形式返回。 2690 2691> **说明：** 2692> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 2693> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 2694 2695**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2696 2697**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2698 2699**系统能力：** SystemCapability.Multimedia.Image.Core 2700 2701**参数：** 2702 2703| 参数名 | 类型 | 必填 | 说明 | 2704| -------- | -------------------- | ---- | ----------------------------- | 2705| angle | number | 是 | 图片旋转的角度。 | 2706| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行旋转成功，err为undefined，否则为错误对象。| 2707 2708**示例：** 2709 2710```ts 2711import { BusinessError } from '@kit.BasicServicesKit'; 2712 2713async function Rotate() { 2714 let angle: number = 90.0; 2715 if (pixelMap != undefined) { 2716 pixelMap.rotate(angle, (err: BusinessError) => { 2717 if (err) { 2718 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 2719 return; 2720 } else { 2721 console.info("Succeeded in rotating pixelmap."); 2722 } 2723 }) 2724 } 2725} 2726``` 2727 2728### rotate<sup>9+</sup> 2729 2730rotate(angle: number): Promise\<void> 2731 2732根据输入的角度对图片进行旋转，使用Promise形式返回。 2733 2734> **说明：** 2735> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 2736> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 2737 2738**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2739 2740**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2741 2742**系统能力：** SystemCapability.Multimedia.Image.Core 2743 2744**参数：** 2745 2746| 参数名 | 类型 | 必填 | 说明 | 2747| ------ | ------ | ---- | ----------------------------- | 2748| angle | number | 是 | 图片旋转的角度。 | 2749 2750**返回值：** 2751 2752| 类型 | 说明 | 2753| -------------- | --------------------------- | 2754| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2755 2756**示例：** 2757 2758```ts 2759import { BusinessError } from '@kit.BasicServicesKit'; 2760 2761async function Rotate() { 2762 let angle: number = 90.0; 2763 if (pixelMap != undefined) { 2764 pixelMap.rotate(angle).then(() => { 2765 console.info('Succeeded in rotating pixelmap.'); 2766 }).catch((err: BusinessError) => { 2767 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 2768 }) 2769 } 2770} 2771``` 2772 2773### rotateSync<sup>12+</sup> 2774 2775rotateSync(angle: number): void 2776 2777根据输入的角度对图片进行旋转，同步返回结果。 2778 2779> **说明：** 2780> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 2781> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 2782 2783**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2784 2785**系统能力：** SystemCapability.Multimedia.Image.Core 2786 2787**参数：** 2788 2789| 参数名 | 类型 | 必填 | 说明 | 2790| -------- | -------------------- | ---- | ----------------------------- | 2791| angle | number | 是 | 图片旋转的角度。 | 2792 2793**错误码：** 2794 2795以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2796 2797| 错误码ID | 错误信息 | 2798| ------- | --------------------------------------------| 2799| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2800| 501 | Resource Unavailable | 2801 2802**示例：** 2803 2804```ts 2805import { BusinessError } from '@kit.BasicServicesKit'; 2806 2807async function RotateSync() { 2808 let angle : number = 90.0; 2809 if (pixelMap != undefined) { 2810 pixelMap.rotateSync(angle); 2811 } 2812} 2813``` 2814 2815### flip<sup>9+</sup> 2816 2817flip(horizontal: boolean, vertical: boolean, callback: AsyncCallback\<void>): void 2818 2819根据输入的条件对图片进行翻转，使用callback形式返回。 2820 2821**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2822 2823**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2824 2825**系统能力：** SystemCapability.Multimedia.Image.Core 2826 2827**参数：** 2828 2829| 参数名 | 类型 | 必填 | 说明 | 2830| ---------- | -------------------- | ---- | ----------------------------- | 2831| horizontal | boolean | 是 | 水平翻转。 | 2832| vertical | boolean | 是 | 垂直翻转。 | 2833| callback | AsyncCallback\<void> | 是 | 回调函数，当对图片翻转成功，err为undefined，否则为错误对象。| 2834 2835**示例：** 2836 2837```ts 2838import { BusinessError } from '@kit.BasicServicesKit'; 2839 2840async function Flip() { 2841 let horizontal: boolean = true; 2842 let vertical: boolean = false; 2843 if (pixelMap != undefined) { 2844 pixelMap.flip(horizontal, vertical, (err: BusinessError) => { 2845 if (err) { 2846 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 2847 return; 2848 } else { 2849 console.info("Succeeded in flipping pixelmap."); 2850 } 2851 }) 2852 } 2853} 2854``` 2855 2856### flip<sup>9+</sup> 2857 2858flip(horizontal: boolean, vertical: boolean): Promise\<void> 2859 2860根据输入的条件对图片进行翻转，使用Promise形式返回。 2861 2862**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2863 2864**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2865 2866**系统能力：** SystemCapability.Multimedia.Image.Core 2867 2868**参数：** 2869 2870| 参数名 | 类型 | 必填 | 说明 | 2871| ---------- | ------- | ---- | --------- | 2872| horizontal | boolean | 是 | 水平翻转。| 2873| vertical | boolean | 是 | 垂直翻转。| 2874 2875**返回值：** 2876 2877| 类型 | 说明 | 2878| -------------- | --------------------------- | 2879| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2880 2881**示例：** 2882 2883```ts 2884import { BusinessError } from '@kit.BasicServicesKit'; 2885 2886async function Flip() { 2887 let horizontal: boolean = true; 2888 let vertical: boolean = false; 2889 if (pixelMap != undefined) { 2890 pixelMap.flip(horizontal, vertical).then(() => { 2891 console.info('Succeeded in flipping pixelmap.'); 2892 }).catch((err: BusinessError) => { 2893 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 2894 }) 2895 } 2896} 2897``` 2898 2899### flipSync<sup>12+</sup> 2900 2901flipSync(horizontal: boolean, vertical: boolean): void 2902 2903根据输入的条件对图片进行翻转并同步返回结果。 2904 2905**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2906 2907**系统能力：** SystemCapability.Multimedia.Image.Core 2908 2909**参数：** 2910 2911| 参数名 | 类型 | 必填 | 说明 | 2912| ---------- | -------------------- | ---- | ----------------------------- | 2913| horizontal | boolean | 是 | 水平翻转。 | 2914| vertical | boolean | 是 | 垂直翻转。 | 2915 2916**错误码：** 2917 2918以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2919 2920| 错误码ID | 错误信息 | 2921| ------- | --------------------------------------------| 2922| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2923| 501 | Resource Unavailable | 2924 2925**示例：** 2926 2927```ts 2928import { BusinessError } from '@kit.BasicServicesKit'; 2929 2930async function FlipSync() { 2931 let horizontal : boolean = true; 2932 let vertical : boolean = false; 2933 if (pixelMap != undefined) { 2934 pixelMap.flipSync(horizontal, vertical); 2935 } 2936} 2937``` 2938 2939### crop<sup>9+</sup> 2940 2941crop(region: Region, callback: AsyncCallback\<void>): void 2942 2943根据输入的尺寸对图片进行裁剪，使用callback形式返回。 2944 2945**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2946 2947**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2948 2949**系统能力：** SystemCapability.Multimedia.Image.Core 2950 2951**参数：** 2952 2953| 参数名 | 类型 | 必填 | 说明 | 2954| -------- | -------------------- | ---- | ----------------------------- | 2955| region | [Region](#region8) | 是 | 裁剪的尺寸。 | 2956| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行裁剪成功，err为undefined，否则为错误对象。| 2957 2958**示例：** 2959 2960```ts 2961import { BusinessError } from '@kit.BasicServicesKit'; 2962 2963async function Crop() { 2964 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 2965 if (pixelMap != undefined) { 2966 pixelMap.crop(region, (err: BusinessError) => { 2967 if (err) { 2968 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 2969 return; 2970 } else { 2971 console.info("Succeeded in cropping pixelmap."); 2972 } 2973 }) 2974 } 2975} 2976``` 2977 2978### crop<sup>9+</sup> 2979 2980crop(region: Region): Promise\<void> 2981 2982根据输入的尺寸对图片进行裁剪，使用Promise形式返回。 2983 2984**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2985 2986**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2987 2988**系统能力：** SystemCapability.Multimedia.Image.Core 2989 2990**参数：** 2991 2992| 参数名 | 类型 | 必填 | 说明 | 2993| ------ | ------------------ | ---- | ----------- | 2994| region | [Region](#region8) | 是 | 裁剪的尺寸。| 2995 2996**返回值：** 2997 2998| 类型 | 说明 | 2999| -------------- | --------------------------- | 3000| Promise\<void> | Promise对象。无返回结果的Promise对象。| 3001 3002**示例：** 3003 3004```ts 3005import { BusinessError } from '@kit.BasicServicesKit'; 3006 3007async function Crop() { 3008 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3009 if (pixelMap != undefined) { 3010 pixelMap.crop(region).then(() => { 3011 console.info('Succeeded in cropping pixelmap.'); 3012 }).catch((err: BusinessError) => { 3013 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 3014 3015 }); 3016 } 3017} 3018``` 3019 3020### cropSync<sup>12+</sup> 3021 3022cropSync(region: Region): void 3023 3024根据输入的尺寸裁剪图片。 3025 3026**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3027 3028**系统能力：** SystemCapability.Multimedia.Image.Core 3029 3030**参数：** 3031 3032| 参数名 | 类型 | 必填 | 说明 | 3033| -------- | -------------------- | ---- | ----------------------------- | 3034| region | [Region](#region8) | 是 | 裁剪的尺寸。 | 3035 3036**错误码：** 3037 3038以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3039 3040| 错误码ID | 错误信息 | 3041| ------- | --------------------------------------------| 3042| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3043| 501 | Resource Unavailable | 3044 3045**示例：** 3046 3047```ts 3048import { BusinessError } from '@kit.BasicServicesKit'; 3049 3050async function CropSync() { 3051 let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3052 if (pixelMap != undefined) { 3053 pixelMap.cropSync(region); 3054 } 3055} 3056``` 3057 3058### getColorSpace<sup>10+</sup> 3059 3060getColorSpace(): colorSpaceManager.ColorSpaceManager 3061 3062获取图像广色域信息。 3063 3064**系统能力：** SystemCapability.Multimedia.Image.Core 3065 3066**返回值：** 3067 3068| 类型 | 说明 | 3069| ----------------------------------- | ---------------- | 3070| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 图像广色域信息。 | 3071 3072**错误码：** 3073 3074以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3075 3076| 错误码ID | 错误信息 | 3077| ------- | --------------------------------------------| 3078| 62980101| If the image data abnormal. | 3079| 62980103| If the image data unsupport. | 3080| 62980115| If the image parameter invalid. | 3081 3082**示例：** 3083 3084```ts 3085async function GetColorSpace() { 3086 if (pixelMap != undefined) { 3087 let csm = pixelMap.getColorSpace(); 3088 } 3089} 3090``` 3091 3092### setColorSpace<sup>10+</sup> 3093 3094setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void 3095 3096设置图像广色域信息。 3097 3098**系统能力：** SystemCapability.Multimedia.Image.Core 3099 3100**参数：** 3101 3102| 参数名 | 类型 | 必填 | 说明 | 3103| ---------- | ----------------------------------- | ---- | --------------- | 3104| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 图像广色域信息。| 3105 3106**错误码：** 3107 3108以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3109 3110| 错误码ID | 错误信息 | 3111| ------- | --------------------------------------------| 3112| 62980111| The image source data is incomplete. | 3113| 62980115| If the image parameter invalid. | 3114 3115**示例：** 3116 3117```ts 3118import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3119async function SetColorSpace() { 3120 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3121 let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3122 if (pixelMap != undefined) { 3123 pixelMap.setColorSpace(csm); 3124 } 3125} 3126``` 3127 3128### applyColorSpace<sup>11+</sup> 3129 3130applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager, callback: AsyncCallback\<void>): void 3131 3132根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用callback形式返回。 3133 3134**系统能力：** SystemCapability.Multimedia.Image.Core 3135 3136**参数：** 3137 3138| 参数名 | 类型 | 必填 | 说明 | 3139| -------- | -------------------- | ---- | ----------------------------- | 3140| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 3141| callback | AsyncCallback\<void> | 是 | 回调函数。当对图像像素颜色进行色彩空间转换成功，err为undefined，否则为错误对象。| 3142 3143**错误码：** 3144 3145以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3146 3147| 错误码ID | 错误信息 | 3148| ------- | ------------------------------------------| 3149| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3150| 62980104| Failed to initialize the internal object. | 3151| 62980108| Failed to convert the color space. | 3152| 62980115| Invalid image parameter. | 3153 3154**示例：** 3155 3156```ts 3157import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3158import { BusinessError } from '@kit.BasicServicesKit'; 3159 3160async function ApplyColorSpace() { 3161 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3162 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3163 if (pixelMap != undefined) { 3164 pixelMap.applyColorSpace(targetColorSpace, (err: BusinessError) => { 3165 if (err) { 3166 console.error(`Failed to apply color space for pixelmap object. code is ${err.code}, message is ${err.message}`); 3167 return; 3168 } else { 3169 console.info('Succeeded in applying color space for pixelmap object.'); 3170 } 3171 }) 3172 } 3173} 3174``` 3175 3176### applyColorSpace<sup>11+</sup> 3177 3178applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void> 3179 3180根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用Promise形式返回。 3181 3182**系统能力：** SystemCapability.Multimedia.Image.Core 3183 3184**参数：** 3185 3186| 参数名 | 类型 | 必填 | 说明 | 3187| ------ | ------------------ | ---- | ----------- | 3188| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 3189 3190**返回值：** 3191 3192| 类型 | 说明 | 3193| -------------- | --------------------------- | 3194| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3195 3196**错误码：** 3197 3198以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3199 3200| 错误码ID | 错误信息 | 3201| ------- | ------------------------------------------| 3202| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3203| 62980104| Failed to initialize the internal object. | 3204| 62980108| Failed to convert the color space. | 3205| 62980115| Invalid image parameter. | 3206 3207**示例：** 3208 3209```ts 3210import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3211import { BusinessError } from '@kit.BasicServicesKit'; 3212 3213async function ApplyColorSpace() { 3214 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3215 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3216 if (pixelMap != undefined) { 3217 pixelMap.applyColorSpace(targetColorSpace).then(() => { 3218 console.info('Succeeded in applying color space for pixelmap object.'); 3219 }).catch((error: BusinessError) => { 3220 console.error(`Failed to apply color space for pixelmap object. code is ${error.code}, message is ${error.message}`); 3221 }) 3222 } 3223} 3224``` 3225 3226### toSdr<sup>12+<sup> 3227 3228toSdr(): Promise\<void> 3229 3230将HDR的图像内容转换为SDR的图像内容，异步使用Promise形式返回。 3231 3232**系统能力：** SystemCapability.Multimedia.Image.Core 3233 3234**返回值：** 3235 3236| 类型 | 说明 | 3237| -------------- | --------------------------- | 3238| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3239 3240**错误码：** 3241 3242以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3243 3244| 错误码ID | 错误信息 | 3245| ------- | --------------------------------------------| 3246| 62980137 | Invalid image operation. | 3247 3248**示例：** 3249 3250```ts 3251import image from '@ohos.multimedia.image' 3252import resourceManager from '@ohos.resourceManager' 3253import { BusinessError } from '@kit.BasicServicesKit'; 3254 3255//此处'hdr.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3256let img = getContext().resourceManager.getMediaContentSync($r('app.media.hdr')); 3257let imageSource = image.createImageSource(img.buffer.slice(0)); 3258let decodingOptions: image.DecodingOptions = { 3259 desiredDynamicRange: image.DecodingDynamicRange.AUTO 3260}; 3261let pixelmap = imageSource.createPixelMapSync(decodingOptions); 3262if (pixelmap != undefined) { 3263 console.info('Succeeded in creating pixelMap object.'); 3264 pixelmap.toSdr().then(() => { 3265 let imageInfo = pixelmap.getImageInfoSync(); 3266 console.info("after toSdr ,imageInfo isHdr:" + imageInfo.isHdr); 3267 }).catch((err: BusinessError) => { 3268 console.error(`Failed to set sdr. code is ${err.code}, message is ${err.message}`); 3269 }); 3270} else { 3271 console.info('Failed to create pixelMap.'); 3272} 3273``` 3274 3275### getMetadata<sup>12+</sup> 3276 3277getMetadata(key: HdrMetadataKey): HdrMetadataValue 3278 3279从PixelMap中获取元数据。 3280 3281**系统能力：** SystemCapability.Multimedia.Image.Core 3282 3283**参数：** 3284 3285| 参数名 | 类型 | 必填 | 说明 | 3286| ------------- | -------------------------------- | ---- | ---------------- | 3287| key | [HdrMetadataKey](#hdrmetadatakey12) | 是 | HDR元数据的关键字，可用于查询对应值。 | 3288 3289**返回值：** 3290 3291| 类型 | 说明 | 3292| --------------------------------- | --------------------------------- | 3293| [HdrMetadataValue](#hdrmetadatavalue12) | 返回元数据的值。 | 3294 3295**错误码：** 3296 3297以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3298 3299| 错误码ID | 错误信息 | 3300| ------- | --------------------------------------------| 3301| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 3302| 501 | Resource unavailable. | 3303| 62980173 | The DMA memory does not exist. | 3304| 62980302 | Memory copy failed. | 3305 3306**示例：** 3307 3308```ts 3309import { BusinessError } from '@kit.BasicServicesKit'; 3310import image from '@ohos.multimedia.image' 3311 3312// 'app.media.test'需要替换为本地hdr图片。 3313let img = getContext().resourceManager.getMediaContentSync($r('app.media.test')); 3314let imageSource = image.createImageSource(img.buffer.slice(0)); 3315let decodingOptions: image.DecodingOptions = { 3316 desiredDynamicRange: image.DecodingDynamicRange.AUTO 3317}; 3318let pixelmap = imageSource.createPixelMapSync(decodingOptions); 3319if (pixelmap != undefined) { 3320 console.info('Succeeded in creating pixelMap object.'); 3321 try { 3322 let staticMetadata = pixelmap.getMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA); 3323 console.info("getmetadata:" + JSON.stringify(staticMetadata)); 3324 } catch (e) { 3325 console.info('pixelmap create failed' + e); 3326 } 3327} else { 3328 console.info('Failed to create pixelMap.'); 3329} 3330``` 3331 3332### setMetadata<sup>12+</sup> 3333 3334setMetadata(key: HdrMetadataKey, value: HdrMetadataValue): Promise\<void> 3335 3336设置PixelMap元数据。 3337 3338**系统能力：** SystemCapability.Multimedia.Image.Core 3339 3340**参数：** 3341 3342| 参数名 | 类型 | 必填 | 说明 | 3343| ------------- | -------------------------------- | ---- | ---------------- | 3344| key | [HdrMetadataKey](#hdrmetadatakey12) | 是 | HDR元数据的关键字，用于设置对应值。 | 3345| value | [HdrMetadataValue](#hdrmetadatavalue12) | 是 | 元数据的值。 | 3346 3347**返回值：** 3348 3349| 类型 | 说明 | 3350| -------------- | --------------------- | 3351| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3352 3353**错误码：** 3354 3355以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3356 3357| 错误码ID | 错误信息 | 3358| ------- | --------------------------------------------| 3359| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 3360| 501 | Resource unavailable. | 3361| 62980173 | The DMA memory does not exist. | 3362| 62980302 | Memory copy failed. | 3363 3364**示例：** 3365 3366```ts 3367import image from '@ohos.multimedia.image' 3368import { BusinessError } from '@kit.BasicServicesKit'; 3369 3370let staticMetadata: image.HdrStaticMetadata = { 3371 displayPrimariesX: [1.1, 1.1, 1.1], 3372 displayPrimariesY: [1.2, 1.2, 1.2], 3373 whitePointX: 1.1, 3374 whitePointY: 1.2, 3375 maxLuminance: 2.1, 3376 minLuminance: 1.0, 3377 maxContentLightLevel: 2.1, 3378 maxFrameAverageLightLevel: 2.1, 3379} 3380const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 3381let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 3382image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 3383 pixelMap.setMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA, staticMetadata).then(() => { 3384 console.info('Succeeded in setting pixelMap metadata.'); 3385 }).catch((error: BusinessError) => { 3386 console.error(`Failed to set the metadata.code ${error.code},message is ${error.message}`); 3387 }) 3388}).catch((error: BusinessError) => { 3389 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 3390}) 3391 3392``` 3393 3394### setTransferDetached<sup>12+<sup> 3395 3396setTransferDetached(detached: boolean): void 3397 3398pixelmap在跨线程传输时，断开原线程的引用。适用于需立即释放pixelmap的场景。 3399 3400**系统能力：** SystemCapability.Multimedia.Image.Core 3401 3402**参数：** 3403 3404| 参数名 | 类型 | 必填 | 说明 | 3405| ------- | ------------------ | ---- | ----------------------------- | 3406| detached | boolean | 是 | 是否断开原线程引用。 | 3407 3408**错误码：** 3409 3410以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3411 3412| 错误码ID | 错误信息 | 3413| ------- | --------------------------------------------| 3414| 501 | Resource Unavailable | 3415 3416**示例：** 3417 3418```ts 3419import { BusinessError } from '@kit.BasicServicesKit'; 3420import image from '@ohos.multimedia.image'; 3421import taskpool from '@ohos.taskpool'; 3422 3423@Concurrent 3424// 子线程方法。 3425async function loadPixelMap(rawFileDescriptor: number): Promise<PixelMap> { 3426 // 创建imageSource。 3427 const imageSource = image.createImageSource(rawFileDescriptor); 3428 // 创建pixelMap。 3429 const pixelMap = imageSource.createPixelMapSync(); 3430 // 释放imageSource。 3431 imageSource.release(); 3432 // 使pixelMap在跨线程传输完成后，断开原线程的引用。 3433 pixelMap.setTransferDetached(true); 3434 // 返回pixelMap给主线程。 3435 return pixelMap; 3436} 3437 3438struct Demo { 3439 @State pixelMap: PixelMap | undefined = undefined; 3440 // 主线程方法。 3441 private loadImageFromThread(): void { 3442 const resourceMgr = getContext(this).resourceManager; 3443 // 此处‘example.jpg’仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3444 resourceMgr.getRawFd('example.jpg').then(rawFileDescriptor => { 3445 taskpool.execute(loadPixelMap, rawFileDescriptor).then(pixelMap => { 3446 if (pixelMap) { 3447 this.pixelMap = pixelMap as PixelMap; 3448 console.log('Succeeded in creating pixelMap.'); 3449 // 主线程释放pixelMap。由于子线程返回pixelMap时已调用setTransferDetached，所以此处能够立即释放pixelMap。 3450 this.pixelMap.release(); 3451 } else { 3452 console.error('Failed to create pixelMap.'); 3453 } 3454 }); 3455 }); 3456 } 3457} 3458``` 3459 3460### marshalling<sup>10+</sup> 3461 3462marshalling(sequence: rpc.MessageSequence): void 3463 3464将PixelMap序列化后写入MessageSequence。 3465 3466**系统能力：** SystemCapability.Multimedia.Image.Core 3467 3468**参数：** 3469 3470| 参数名 | 类型 | 必填 | 说明 | 3471| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 3472| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 3473 3474**错误码：** 3475 3476以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3477 3478| 错误码ID | 错误信息 | 3479| ------- | --------------------------------------------| 3480| 62980115 | Invalid image parameter. | 3481| 62980097 | IPC error. | 3482 3483**示例：** 3484 3485```ts 3486import { image } from '@kit.ImageKit'; 3487import { rpc } from '@kit.IPCKit'; 3488 3489class MySequence implements rpc.Parcelable { 3490 pixel_map: image.PixelMap; 3491 constructor(conPixelMap : image.PixelMap) { 3492 this.pixel_map = conPixelMap; 3493 } 3494 marshalling(messageSequence : rpc.MessageSequence) { 3495 this.pixel_map.marshalling(messageSequence); 3496 console.info('marshalling'); 3497 return true; 3498 } 3499 unmarshalling(messageSequence : rpc.MessageSequence) { 3500 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: image.PixelMap) => { 3501 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: image.PixelMap) => { 3502 this.pixel_map = pixelMap; 3503 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 3504 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 3505 }) 3506 }) 3507 }); 3508 return true; 3509 } 3510} 3511async function Marshalling() { 3512 const color: ArrayBuffer = new ArrayBuffer(96); 3513 let bufferArr: Uint8Array = new Uint8Array(color); 3514 for (let i = 0; i < bufferArr.length; i++) { 3515 bufferArr[i] = 0x80; 3516 } 3517 let opts: image.InitializationOptions = { 3518 editable: true, 3519 pixelFormat: image.PixelMapFormat.BGRA_8888, 3520 size: { height: 4, width: 6 }, 3521 alphaType: image.AlphaType.UNPREMUL 3522 } 3523 let pixelMap: image.PixelMap | undefined = undefined; 3524 image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 3525 pixelMap = srcPixelMap; 3526 }) 3527 if (pixelMap != undefined) { 3528 // 序列化。 3529 let parcelable: MySequence = new MySequence(pixelMap); 3530 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 3531 data.writeParcelable(parcelable); 3532 3533 // 反序列化 rpc获取到data。 3534 let ret: MySequence = new MySequence(pixelMap); 3535 data.readParcelable(ret); 3536 } 3537} 3538``` 3539 3540### unmarshalling<sup>10+</sup> 3541 3542unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap> 3543 3544从MessageSequence中获取PixelMap， 3545如需使用同步方式创建PixelMap可使用：[createPixelMapFromParcel](#imagecreatepixelmapfromparcel11)。 3546 3547**系统能力：** SystemCapability.Multimedia.Image.Core 3548 3549**参数：** 3550 3551| 参数名 | 类型 | 必填 | 说明 | 3552| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 3553| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 3554 3555**返回值：** 3556 3557| 类型 | 说明 | 3558| -------------------------------- | --------------------- | 3559| Promise\<[PixelMap](#pixelmap7)> |Promise对象，返回PixelMap。 | 3560 3561**错误码：** 3562 3563以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3564 3565| 错误码ID | 错误信息 | 3566| ------- | --------------------------------------------| 3567| 62980115 | Invalid image parameter. | 3568| 62980097 | IPC error. | 3569| 62980096 | The operation failed. | 3570 3571**示例：** 3572 3573```ts 3574import { image } from '@kit.ImageKit'; 3575import { rpc } from '@kit.IPCKit'; 3576 3577class MySequence implements rpc.Parcelable { 3578 pixel_map: image.PixelMap; 3579 constructor(conPixelMap: image.PixelMap) { 3580 this.pixel_map = conPixelMap; 3581 } 3582 marshalling(messageSequence: rpc.MessageSequence) { 3583 this.pixel_map.marshalling(messageSequence); 3584 console.info('marshalling'); 3585 return true; 3586 } 3587 unmarshalling(messageSequence: rpc.MessageSequence) { 3588 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : image.PixelMap) => { 3589 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : image.PixelMap) => { 3590 this.pixel_map = pixelMap; 3591 pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => { 3592 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 3593 }) 3594 }) 3595 }); 3596 return true; 3597 } 3598} 3599async function Unmarshalling() { 3600 const color: ArrayBuffer = new ArrayBuffer(96); 3601 let bufferArr: Uint8Array = new Uint8Array(color); 3602 for (let i = 0; i < bufferArr.length; i++) { 3603 bufferArr[i] = 0x80; 3604 } 3605 let opts: image.InitializationOptions = { 3606 editable: true, 3607 pixelFormat: image.PixelMapFormat.BGRA_8888, 3608 size: { height: 4, width: 6 }, 3609 alphaType: image.AlphaType.UNPREMUL 3610 } 3611 let pixelMap: image.PixelMap | undefined = undefined; 3612 image.createPixelMap(color, opts).then((srcPixelMap : image.PixelMap) => { 3613 pixelMap = srcPixelMap; 3614 }) 3615 if (pixelMap != undefined) { 3616 // 序列化。 3617 let parcelable: MySequence = new MySequence(pixelMap); 3618 let data : rpc.MessageSequence = rpc.MessageSequence.create(); 3619 data.writeParcelable(parcelable); 3620 3621 // 反序列化 rpc获取到data。 3622 let ret : MySequence = new MySequence(pixelMap); 3623 data.readParcelable(ret); 3624 } 3625} 3626``` 3627 3628### release<sup>7+</sup> 3629 3630release():Promise\<void> 3631 3632释放PixelMap对象，使用Promise形式返回释放结果。 3633 3634ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 3635 3636**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3637 3638**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3639 3640**系统能力：** SystemCapability.Multimedia.Image.Core 3641 3642**返回值：** 3643 3644| 类型 | 说明 | 3645| -------------- | ------------------------------- | 3646| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3647 3648**示例：** 3649 3650```ts 3651import { BusinessError } from '@kit.BasicServicesKit'; 3652 3653async function Release() { 3654 if (pixelMap != undefined) { 3655 pixelMap.release().then(() => { 3656 console.info('Succeeded in releasing pixelmap object.'); 3657 }).catch((error: BusinessError) => { 3658 console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`); 3659 }) 3660 } 3661} 3662``` 3663 3664### release<sup>7+</sup> 3665 3666release(callback: AsyncCallback\<void>): void 3667 3668释放PixelMap对象，使用callback形式返回释放结果。 3669 3670ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 3671 3672**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3673 3674**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3675 3676**系统能力：** SystemCapability.Multimedia.Image.Core 3677 3678**参数：** 3679 3680| 参数名 | 类型 | 必填 | 说明 | 3681| -------- | -------------------- | ---- | ------------------ | 3682| callback | AsyncCallback\<void> | 是 | 回调函数。当对PixelMap对象释放成功，err为undefined，否则为错误对象。 | 3683 3684**示例：** 3685 3686```ts 3687import { BusinessError } from '@kit.BasicServicesKit'; 3688 3689async function Release() { 3690 if (pixelMap != undefined) { 3691 pixelMap.release((err: BusinessError) => { 3692 if (err) { 3693 console.error(`Failed to release pixelmap object. code is ${err.code}, message is ${err.message}`); 3694 return; 3695 } else { 3696 console.info('Succeeded in releasing pixelmap object.'); 3697 } 3698 }) 3699 } 3700} 3701``` 3702 3703### convertPixelFormat<sup>12+</sup> 3704 3705convertPixelFormat(targetPixelFormat: PixelMapFormat): Promise\<void> 3706 3707YUV和RGB类型互转，目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转。 3708 3709**系统能力：** SystemCapability.Multimedia.Image.Core 3710 3711**参数：** 3712 3713| 参数名 | 类型 | 必填 | 说明 | 3714| -------- | -------------------- | ---- | ------------------ | 3715| targetPixelFormat | [PixelMapFormat](#pixelmapformat7) | 是 | 目标像素格式，用于YUV和RGB类型互转。目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转。 | 3716 3717**返回值：** 3718 3719| 类型 | 说明 | 3720| -------------- | ------------------------------- | 3721| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3722 3723**错误码：** 3724 3725以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3726 3727| 错误码ID | 错误信息 | 3728| ------- | --------------------------------------------| 3729| 62980111 | The image source data is incomplete. | 3730| 62980115 | Invalid input parameter. | 3731| 62980178 | Failed to create the pixelmap. | 3732| 62980274 | The conversion failed | 3733| 62980276 | The type to be converted is an unsupported target pixel format| 3734 3735**示例：** 3736 3737```ts 3738import { BusinessError } from '@kit.BasicServicesKit'; 3739 3740if (pixelMap != undefined) { 3741 // 设置目标像素格式为NV12。 3742 let targetPixelFormat = image.PixelMapFormat.NV12; 3743 pixelMap.convertPixelFormat(targetPixelFormat).then(() => { 3744 // pixelMap转换成NV12格式成功。 3745 console.info('PixelMapFormat convert Succeeded'); 3746 }).catch((error: BusinessError) => { 3747 // pixelMap转换成NV12格式失败。 3748 console.error(`PixelMapFormat convert Failed. code is ${error.code}, message is ${error.message}`); 3749 }) 3750} 3751``` 3752 3753### setMemoryNameSync<sup>13+</sup> 3754 3755setMemoryNameSync(name: string): void 3756 3757设置PixelMap内存标识符。 3758 3759**系统能力：** SystemCapability.Multimedia.Image.Core 3760 3761**参数：** 3762 3763| 参数名 | 类型 | 必填 | 说明 | 3764| ------------- | -------------------------------- | ---- | ---------------- | 3765| name | string | 是 | pixelmap内存标识符，只允许DMA和ASHMEM内存形式的piexelmap设置，支持1-31位长度。 | 3766 3767**错误码：** 3768 3769以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3770 3771| 错误码ID | 错误信息 | 3772| ------- | --------------------------------------------| 3773| 401 | Parameter error. Possible causes: 1.The length of the input parameter is too long. 2.Parameter verification failed. | 3774| 501 | Resource unavailable. | 3775| 62980286 | Memory format not supported. | 3776 3777**示例：** 3778 3779```ts 3780import { BusinessError } from '@ohos.base'; 3781 3782async function SetMemoryNameSync() { 3783 if (pixelMap != undefined) { 3784 try { 3785 pixelMap.setMemoryNameSync("PixelMapName Test"); 3786 } catch(e) { 3787 let error = e as BusinessError; 3788 console.error(`setMemoryNameSync error. code is ${error.code}, message is ${error.message}`); 3789 } 3790 } 3791} 3792``` 3793 3794## image.createImageSource 3795 3796createImageSource(uri: string): ImageSource 3797 3798通过传入的uri创建图片源实例。 3799 3800 3801**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3802 3803**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3804 3805**参数：** 3806 3807| 参数名 | 类型 | 必填 | 说明 | 3808| ------ | ------ | ---- | ---------------------------------- | 3809| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng .heic<sup>12+</sup>（不同硬件设备支持情况不同） [.svg<sup>10+</sup>](#svg标签说明) .ico<sup>11+</sup>。 | 3810 3811**返回值：** 3812 3813| 类型 | 说明 | 3814| --------------------------- | -------------------------------------------- | 3815| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 3816 3817**示例：** 3818 3819```ts 3820const context: Context = getContext(this); 3821//此处'test.jpg'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 3822const path: string = context.filesDir + "/test.jpg"; 3823const imageSourceApi: image.ImageSource = image.createImageSource(path); 3824``` 3825 3826## image.createImageSource<sup>9+</sup> 3827 3828createImageSource(uri: string, options: SourceOptions): ImageSource 3829 3830通过传入的uri创建图片源实例。 3831 3832**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3833 3834**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3835 3836**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3837 3838**参数：** 3839 3840| 参数名 | 类型 | 必填 | 说明 | 3841| ------- | ------------------------------- | ---- | ----------------------------------- | 3842| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng .heic<sup>12+</sup>（不同硬件设备支持情况不同）[.svg<sup>10+</sup>](#svg标签说明) .ico<sup>11+</sup>。 | 3843| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。| 3844 3845**返回值：** 3846 3847| 类型 | 说明 | 3848| --------------------------- | -------------------------------------------- | 3849| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 3850 3851**示例：** 3852 3853```ts 3854let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 3855const context: Context = getContext(this); 3856//此处'test.png'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 3857const path: string = context.filesDir + "/test.png"; 3858let imageSourceApi: image.ImageSource = image.createImageSource(path, sourceOptions); 3859``` 3860 3861## image.createImageSource<sup>7+</sup> 3862 3863createImageSource(fd: number): ImageSource 3864 3865通过传入文件描述符来创建图片源实例。 3866 3867**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3868 3869**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3870 3871**参数：** 3872 3873| 参数名 | 类型 | 必填 | 说明 | 3874| ------ | ------ | ---- | ------------- | 3875| fd | number | 是 | 文件描述符fd。| 3876 3877**返回值：** 3878 3879| 类型 | 说明 | 3880| --------------------------- | -------------------------------------------- | 3881| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 3882 3883**示例：** 3884 3885```ts 3886import { fileIo as fs } from '@kit.CoreFileKit'; 3887 3888const context: Context = getContext(this); 3889//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 3890let filePath: string = context.filesDir + "/test.jpg"; 3891let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 3892const imageSourceApi: image.ImageSource = image.createImageSource(file.fd); 3893``` 3894 3895## image.createImageSource<sup>9+</sup> 3896 3897createImageSource(fd: number, options: SourceOptions): ImageSource 3898 3899通过传入文件描述符来创建图片源实例。 3900 3901**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3902 3903**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3904 3905**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3906 3907**参数：** 3908 3909| 参数名 | 类型 | 必填 | 说明 | 3910| ------- | ------------------------------- | ---- | ----------------------------------- | 3911| fd | number | 是 | 文件描述符fd。 | 3912| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。| 3913 3914**返回值：** 3915 3916| 类型 | 说明 | 3917| --------------------------- | -------------------------------------------- | 3918| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 3919 3920**示例：** 3921 3922```ts 3923import { fileIo as fs } from '@kit.CoreFileKit'; 3924 3925let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 3926const context: Context = getContext(); 3927//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3928const filePath: string = context.filesDir + "/test.jpg"; 3929let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 3930const imageSourceApi: image.ImageSource = image.createImageSource(file.fd, sourceOptions); 3931``` 3932 3933## image.createImageSource<sup>9+</sup> 3934 3935createImageSource(buf: ArrayBuffer): ImageSource 3936 3937通过缓冲区创建图片源实例。buf数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用[image.createPixelMapSync](#createpixelmapsync12)这一类接口。 3938 3939**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3940 3941**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3942 3943**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3944 3945**参数：** 3946 3947| 参数名 | 类型 | 必填 | 说明 | 3948| ------ | ----------- | ---- | ---------------- | 3949| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 3950 3951**返回值：** 3952 3953| 类型 | 说明 | 3954| --------------------------- | -------------------------------------------- | 3955| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 3956 3957 3958**示例：** 3959 3960```ts 3961const buf: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 3962const imageSourceApi: image.ImageSource = image.createImageSource(buf); 3963``` 3964 3965## image.createImageSource<sup>9+</sup> 3966 3967createImageSource(buf: ArrayBuffer, options: SourceOptions): ImageSource 3968 3969通过缓冲区创建图片源实例。buf数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用[image.createPixelMapSync](#createpixelmapsync12)这一类接口。 3970 3971**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3972 3973**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3974 3975**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3976 3977**参数：** 3978 3979| 参数名 | 类型 | 必填 | 说明 | 3980| ------ | -------------------------------- | ---- | ------------------------------------ | 3981| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 3982| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 3983 3984**返回值：** 3985 3986| 类型 | 说明 | 3987| --------------------------- | -------------------------------------------- | 3988| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 3989 3990**示例：** 3991 3992```ts 3993const data: ArrayBuffer = new ArrayBuffer(112); 3994let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 3995const imageSourceApi: image.ImageSource = image.createImageSource(data, sourceOptions); 3996``` 3997 3998## image.createImageSource<sup>11+</sup> 3999 4000createImageSource(rawfile: resourceManager.RawFileDescriptor, options?: SourceOptions): ImageSource 4001 4002通过图像资源文件的RawFileDescriptor创建图片源实例。 4003 4004**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4005 4006**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4007 4008**参数：** 4009 4010| 参数名 | 类型 | 必填 | 说明 | 4011| ------ | -------------------------------- | ---- | ------------------------------------ | 4012| rawfile | [resourceManager.RawFileDescriptor](../apis-localization-kit/js-apis-resource-manager.md#rawfiledescriptor9) | 是 | 图像资源文件的RawFileDescriptor。 | 4013| options | [SourceOptions](#sourceoptions9) | 否 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4014 4015**返回值：** 4016 4017| 类型 | 说明 | 4018| --------------------------- | -------------------------------------------- | 4019| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4020 4021**示例：** 4022 4023```ts 4024import { resourceManager } from '@kit.LocalizationKit'; 4025 4026const context: Context = getContext(this); 4027// 获取resourceManager资源管理器。 4028const resourceMgr: resourceManager.ResourceManager = context.resourceManager; 4029//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4030resourceMgr.getRawFd('test.jpg').then((rawFileDescriptor: resourceManager.RawFileDescriptor) => { 4031 const imageSourceApi: image.ImageSource = image.createImageSource(rawFileDescriptor); 4032}).catch((error: BusinessError) => { 4033 console.error(`Failed to get RawFileDescriptor.code is ${error.code}, message is ${error.message}`); 4034}) 4035``` 4036 4037## image.CreateIncrementalSource<sup>9+</sup> 4038 4039CreateIncrementalSource(buf: ArrayBuffer): ImageSource 4040 4041通过缓冲区以增量的方式创建图片源实例，IncrementalSource不支持读写Exif信息。 4042 4043以增量方式创建的图片源实例ImageSource，仅支持使用以下功能，同步、异步callback、异步Promise均支持。 4044- 获取图片信息：指定序号-[getImageInfo](#getimageinfo)、直接获取-[getImageInfo](#getimageinfo-1) 4045- 获取图片中给定索引处图像的指定属性键的值：[getImageProperty](#getimageproperty11) 4046- 批量获取图片中的指定属性键的值：[getImageProperties](#getimageproperties12) 4047- 更新增量数据：[updateData](#updatedata9) 4048- 创建PixelMap对象：通过图片解码参数创建-[createPixelMap](#createpixelmap7)、通过默认参数创建-[createPixelMap](#createpixelmap7-1) 、通过图片解码参数-[createPixelMap](#createpixelmap7-2) 4049- 释放图片源实例：[release](#release) 4050 4051**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4052 4053**参数：** 4054 4055| 参数名 | 类型 | 必填 | 说明 | 4056| ------- | ------------| ---- | ----------| 4057| buf | ArrayBuffer | 是 | 增量数据。| 4058 4059**返回值：** 4060 4061| 类型 | 说明 | 4062| --------------------------- | --------------------------------- | 4063| [ImageSource](#imagesource) | 返回图片源，失败时返回undefined。 | 4064 4065**示例：** 4066 4067```ts 4068const context: Context = getContext(this) 4069let imageArray = context.resourceManager.getMediaContentSync($r('app.media.startIcon')) // 获取图像资源。 4070// 此处'app.media.startIcon'仅作示例，请开发者自行替换，否则imageArray创建失败会导致后续无法正常执行。 4071let splitBuff1 = imageArray.slice(0, imageArray.byteLength / 2) // 分片。 4072let splitBuff2 = imageArray.slice(imageArray.byteLength / 2) 4073const imageSourceIncrementalSApi: image.ImageSource = image.CreateIncrementalSource(new ArrayBuffer(imageArray.byteLength)); 4074imageSourceIncrementalSApi.updateData(splitBuff1, false, 0, splitBuff1.byteLength).then(() => { 4075 imageSourceIncrementalSApi.updateData(splitBuff2, true, 0, splitBuff2.byteLength).then(() => { 4076 let pixelMap = imageSourceIncrementalSApi.createPixelMapSync() 4077 let imageInfo = pixelMap.getImageInfoSync() 4078 console.info('Succeeded in creating pixelMap') 4079 }).catch((error : BusinessError) => { 4080 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`) 4081 }) 4082}).catch((error : BusinessError) => { 4083 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`) 4084}) 4085``` 4086 4087## image.CreateIncrementalSource<sup>9+</sup> 4088 4089CreateIncrementalSource(buf: ArrayBuffer, options?: SourceOptions): ImageSource 4090 4091通过缓冲区以增量的方式创建图片源实例，IncrementalSource不支持读写Exif信息。 4092 4093此接口支持的功能与[CreateIncrementalSource(buf: ArrayBuffer): ImageSource](#imagecreateincrementalsource9)所生成的实例支持的功能相同 4094 4095**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4096 4097**参数：** 4098 4099| 参数名 | 类型 | 必填 | 说明 | 4100| ------- | ------------------------------- | ---- | ------------------------------------ | 4101| buf | ArrayBuffer | 是 | 增量数据。 | 4102| options | [SourceOptions](#sourceoptions9) | 否 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4103 4104**返回值：** 4105 4106| 类型 | 说明 | 4107| --------------------------- | --------------------------------- | 4108| [ImageSource](#imagesource) | 返回图片源，失败时返回undefined。 | 4109 4110**示例：** 4111 4112```ts 4113const context: Context = getContext(this) 4114let imageArray = context.resourceManager.getMediaContentSync($r('app.media.startIcon')) // 获取图像资源。 4115// 此处'app.media.startIcon'仅作示例，请开发者自行替换，否则imageArray创建失败会导致后续无法正常执行。 4116let splitBuff1 = imageArray.slice(0, imageArray.byteLength / 2) // 分片。 4117let splitBuff2 = imageArray.slice(imageArray.byteLength / 2) 4118let sourceOptions: image.SourceOptions = { sourceDensity: 120}; 4119 4120const imageSourceIncrementalSApi: image.ImageSource = image.CreateIncrementalSource(new ArrayBuffer(imageArray.byteLength), sourceOptions); 4121imageSourceIncrementalSApi.updateData(splitBuff1, false, 0, splitBuff1.byteLength).then(() => { 4122 imageSourceIncrementalSApi.updateData(splitBuff2, true, 0, splitBuff2.byteLength).then(() => { 4123 let pixelMap = imageSourceIncrementalSApi.createPixelMapSync() 4124 let imageInfo = pixelMap.getImageInfoSync() 4125 console.info('Succeeded in creating pixelMap') 4126 }).catch((error : BusinessError) => { 4127 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`) 4128 }) 4129}).catch((error : BusinessError) => { 4130 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`) 4131}) 4132``` 4133 4134## ImageSource 4135 4136图片源类，用于获取图片相关信息。在调用ImageSource的方法前，需要先通过[createImageSource](#imagecreateimagesource)构建一个ImageSource实例。 4137 4138### 属性 4139 4140**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4141 4142| 名称 | 类型 | 可读 | 可写 | 说明 | 4143| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 4144| supportedFormats | Array\<string> | 是 | 否 | 支持的图片格式，包括：png，jpeg，bmp，gif，webp，dng，heic<sup>12+</sup>（不同硬件设备支持情况不同）。 | 4145 4146### getImageInfo 4147 4148getImageInfo(index: number, callback: AsyncCallback\<ImageInfo>): void 4149 4150获取指定序号的图片信息，使用callback形式返回图片信息。 4151 4152**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4153 4154**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4155 4156**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4157 4158**参数：** 4159 4160| 参数名 | 类型 | 必填 | 说明 | 4161| -------- | -------------------------------------- | ---- | ---------------------------------------- | 4162| index | number | 是 | 创建图片源时的序号。 | 4163| callback | AsyncCallback<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图片信息成功，err为undefined，data为获取到的图片信息；否则为错误对象。 | 4164 4165**示例：** 4166 4167```ts 4168import { BusinessError } from '@kit.BasicServicesKit'; 4169 4170imageSourceApi.getImageInfo(0, (error: BusinessError, imageInfo: image.ImageInfo) => { 4171 if (error) { 4172 console.error(`Failed to obtain the image information.code is ${error.code}, message is ${error.message}`); 4173 } else { 4174 console.info('Succeeded in obtaining the image information.'); 4175 } 4176}) 4177``` 4178 4179### getImageInfo 4180 4181getImageInfo(callback: AsyncCallback\<ImageInfo>): void 4182 4183获取图片信息，使用callback形式返回图片信息。 4184 4185**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4186 4187**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4188 4189**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4190 4191**参数：** 4192 4193| 参数名 | 类型 | 必填 | 说明 | 4194| -------- | -------------------------------------- | ---- | ---------------------------------------- | 4195| callback | AsyncCallback<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图片信息成功，err为undefined，data为获取到的图片信息；否则为错误对象。 | 4196 4197**示例：** 4198 4199```ts 4200import { BusinessError } from '@kit.BasicServicesKit'; 4201 4202imageSourceApi.getImageInfo((err: BusinessError, imageInfo: image.ImageInfo) => { 4203 if (err) { 4204 console.error(`Failed to obtain the image information.code is ${err.code}, message is ${err.message}`); 4205 } else { 4206 console.info('Succeeded in obtaining the image information.'); 4207 } 4208}) 4209``` 4210 4211### getImageInfo 4212 4213getImageInfo(index?: number): Promise\<ImageInfo> 4214 4215获取图片信息，使用Promise形式返回图片信息。 4216 4217**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4218 4219**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4220 4221**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4222 4223**参数：** 4224 4225| 参数名| 类型 | 必填 | 说明 | 4226| ----- | ------ | ---- | ------------------------------------- | 4227| index | number | 否 | 创建图片源时的序号，不选择时默认为0。 | 4228 4229**返回值：** 4230 4231| 类型 | 说明 | 4232| -------------------------------- | ---------------------- | 4233| Promise<[ImageInfo](#imageinfo)> | Promise对象，返回获取到的图片信息。 | 4234 4235**示例：** 4236 4237```ts 4238import { BusinessError } from '@kit.BasicServicesKit'; 4239 4240imageSourceApi.getImageInfo(0) 4241 .then((imageInfo: image.ImageInfo) => { 4242 console.info('Succeeded in obtaining the image information.'); 4243 }).catch((error: BusinessError) => { 4244 console.error(`Failed to obtain the image information.code is ${error.code}, message is ${error.message}`); 4245 }) 4246``` 4247 4248### getImageInfoSync<sup>12+</sup> 4249 4250getImageInfoSync(index?: number): ImageInfo 4251 4252获取指定序号的图片信息，使用同步形式返回图片信息。 4253 4254**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4255 4256**参数：** 4257 4258| 参数名| 类型 | 必填 | 说明 | 4259| ----- | ------ | ---- | ------------------------------------- | 4260| index | number | 否 | 创建图片源时的序号，不选择时默认为0。 | 4261 4262**返回值：** 4263 4264| 类型 | 说明 | 4265| -------------------------------- | ---------------------- | 4266| [ImageInfo](#imageinfo) | 同步返回获取到的图片信息。 | 4267 4268**示例：** 4269 4270```ts 4271import { image } from '@kit.ImageKit'; 4272 4273const context: Context = getContext(); 4274//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4275let filePath: string = context.filesDir + "/test.jpg"; 4276let imageSource = image.createImageSource(filePath); 4277let imageInfo = imageSource.getImageInfoSync(0); 4278if (imageInfo == undefined) { 4279 console.error('Failed to obtain the image information.'); 4280} else { 4281 console.info('Succeeded in obtaining the image information.'); 4282 console.info('imageInfo.size.height:' + imageInfo.size.height); 4283 console.info('imageInfo.size.width:' + imageInfo.size.width); 4284} 4285``` 4286 4287### getImageProperty<sup>11+</sup> 4288 4289getImageProperty(key:PropertyKey, options?: ImagePropertyOptions): Promise\<string> 4290 4291获取图片中给定索引处图像的指定属性键的值，用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4292 4293**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4294 4295**参数：** 4296 4297| 参数名 | 类型 | 必填 | 说明 | 4298| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4299| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4300| options | [ImagePropertyOptions](#imagepropertyoptions11) | 否 | 图片属性，包括图片序号与默认属性值。 | 4301 4302**返回值：** 4303 4304| 类型 | 说明 | 4305| ---------------- | ----------------------------------------------------------------- | 4306| Promise\<string> | Promise对象，返回图片属性值，如获取失败则返回属性默认值。 | 4307 4308**错误码：** 4309 4310以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4311 4312| 错误码ID | 错误信息 | 4313| ------- | --------------------------------------------| 4314| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4315| 62980096 | The operation failed. | 4316| 62980103 | The image data is not supported. | 4317| 62980110 | The image source data is incorrect. | 4318| 62980111 | The image source data is incomplete. | 4319| 62980112 | The image format does not match. | 4320| 62980113 | Unknown image format. | 4321| 62980115 | Invalid image parameter. | 4322| 62980116| Failed to decode the image. | 4323| 62980118 | Failed to create the image plugin. | 4324| 62980122 | Failed to decode the image header. | 4325| 62980123| Images in EXIF format are not supported. | 4326| 62980135| The EXIF value is invalid. | 4327 4328**示例：** 4329 4330```ts 4331import { BusinessError } from '@kit.BasicServicesKit'; 4332 4333let options: image.ImagePropertyOptions = { index: 0, defaultValue: '9999' } 4334imageSourceApi.getImageProperty(image.PropertyKey.BITS_PER_SAMPLE, options) 4335.then((data: string) => { 4336 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4337}).catch((error: BusinessError) => { 4338 console.error('Failed to get the value of the specified attribute key of the image.'); 4339}) 4340``` 4341 4342### getImageProperty<sup>(deprecated)</sup> 4343 4344getImageProperty(key:string, options?: GetImagePropertyOptions): Promise\<string> 4345 4346获取图片中给定索引处图像的指定属性键的值，用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4347 4348> **说明：** 4349> 4350> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4351 4352**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4353 4354**参数：** 4355 4356| 参数名 | 类型 | 必填 | 说明 | 4357| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4358| key | string | 是 | 图片属性名。 | 4359| options | [GetImagePropertyOptions](#getimagepropertyoptionsdeprecated) | 否 | 图片属性，包括图片序号与默认属性值。 | 4360 4361**返回值：** 4362 4363| 类型 | 说明 | 4364| ---------------- | ----------------------------------------------------------------- | 4365| Promise\<string> | Promise对象，返回图片属性值，如获取失败则返回属性默认值。 | 4366 4367**示例：** 4368 4369```ts 4370import { BusinessError } from '@kit.BasicServicesKit'; 4371 4372imageSourceApi.getImageProperty("BitsPerSample") 4373 .then((data: string) => { 4374 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4375 }).catch((error: BusinessError) => { 4376 console.error('Failed to get the value of the specified attribute key of the image.'); 4377 }) 4378``` 4379 4380### getImageProperty<sup>(deprecated)</sup> 4381 4382getImageProperty(key:string, callback: AsyncCallback\<string>): void 4383 4384获取图片中给定索引处图像的指定属性键的值，用callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4385 4386> **说明：** 4387> 4388> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4389 4390**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4391 4392**参数：** 4393 4394| 参数名 | 类型 | 必填 | 说明 | 4395| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4396| key | string | 是 | 图片属性名。 | 4397| callback | AsyncCallback\<string> | 是 | 回调函数，当获取图片属性值成功，err为undefined，data为获取到的图片属性值；否则为错误对象。 | 4398 4399**示例：** 4400 4401```ts 4402import { BusinessError } from '@kit.BasicServicesKit'; 4403 4404imageSourceApi.getImageProperty("BitsPerSample", (error: BusinessError, data: string) => { 4405 if (error) { 4406 console.error('Failed to get the value of the specified attribute key of the image.'); 4407 } else { 4408 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4409 } 4410}) 4411``` 4412 4413### getImageProperty<sup>(deprecated)</sup> 4414 4415getImageProperty(key:string, options: GetImagePropertyOptions, callback: AsyncCallback\<string>): void 4416 4417获取图片指定属性键的值，callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4418 4419> **说明：** 4420> 4421> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4422 4423**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4424 4425**参数：** 4426 4427| 参数名 | 类型 | 必填 | 说明 | 4428| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------- | 4429| key | string | 是 | 图片属性名。 | 4430| options | [GetImagePropertyOptions](#getimagepropertyoptionsdeprecated) | 是 | 图片属性，包括图片序号与默认属性值。 | 4431| callback | AsyncCallback\<string> | 是 | 回调函数，当获取图片属性值成功，err为undefined，data为获取到的图片属性值；否则为错误对象。| 4432 4433**示例：** 4434 4435```ts 4436import { BusinessError } from '@kit.BasicServicesKit'; 4437 4438let property: image.GetImagePropertyOptions = { index: 0, defaultValue: '9999' } 4439imageSourceApi.getImageProperty("BitsPerSample", property, (error: BusinessError, data: string) => { 4440 if (error) { 4441 console.error('Failed to get the value of the specified attribute key of the image.'); 4442 } else { 4443 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4444 } 4445}) 4446``` 4447 4448### getImageProperties<sup>12+</sup> 4449 4450getImageProperties(key: Array<PropertyKey>): Promise<Record<PropertyKey, string|null>> 4451 4452批量获取图片中的指定属性键的值，用Promise形式返回结果。仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4453 4454**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4455 4456**参数：** 4457 4458| 参数名 | 类型 | 必填 | 说明 | 4459| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4460| key | Array\<[PropertyKey](#propertykey7)> | 是 | 图片属性名的数组。 | 4461 4462**返回值：** 4463 4464| 类型 | 说明 | 4465| ---------------- | ----------------------------------------------------------------- | 4466| Promise\<Record<[PropertyKey](#propertykey7), string \| null>> | Promise对象，返回图片属性值，如获取失败则返回null。 | 4467 4468**错误码：** 4469 4470以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4471 4472| 错误码ID | 错误信息 | 4473| ------- | --------------------------------------------| 4474| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4475| 62980096| The operation failed. | 4476| 62980110| The image source data is incorrect. | 4477| 62980113| Unknown image format. | 4478| 62980116| Failed to decode the image. | 4479 4480**示例：** 4481 4482```ts 4483import { image } from '@kit.ImageKit'; 4484import { BusinessError } from '@kit.BasicServicesKit'; 4485 4486let key = [image.PropertyKey.IMAGE_WIDTH, image.PropertyKey.IMAGE_LENGTH]; 4487imageSourceApi.getImageProperties(key).then((data) => { 4488 console.info(JSON.stringify(data)); 4489}).catch((err: BusinessError) => { 4490 console.error(JSON.stringify(err)); 4491}); 4492``` 4493 4494### modifyImageProperty<sup>11+</sup> 4495 4496modifyImageProperty(key: PropertyKey, value: string): Promise\<void> 4497 4498通过指定的键修改图片属性的值，使用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4499 4500> **说明：** 4501> 4502> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4503 4504**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4505 4506**参数：** 4507 4508| 参数名 | 类型 | 必填 | 说明 | 4509| ------- | ------ | ---- | ------------ | 4510| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4511| value | string | 是 | 属性值。 | 4512 4513**返回值：** 4514 4515| 类型 | 说明 | 4516| -------------- | --------------------------- | 4517| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4518 4519**错误码：** 4520 4521以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4522 4523| 错误码ID | 错误信息 | 4524| ------- | --------------------------------------------| 4525| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 4526| 62980123| The image does not support EXIF decoding. | 4527| 62980133| The EXIF data is out of range. | 4528| 62980135| The EXIF value is invalid. | 4529| 62980146| The EXIF data failed to be written to the file. | 4530 4531**示例：** 4532 4533```ts 4534import { BusinessError } from '@kit.BasicServicesKit'; 4535 4536imageSourceApi.modifyImageProperty(image.PropertyKey.IMAGE_WIDTH, "120").then(() => { 4537 imageSourceApi.getImageProperty(image.PropertyKey.IMAGE_WIDTH).then((width: string) => { 4538 console.info(`ImageWidth is :${width}`); 4539 }).catch((error: BusinessError) => { 4540 console.error('Failed to get the Image Width.'); 4541 }) 4542}).catch((error: BusinessError) => { 4543 console.error('Failed to modify the Image Width'); 4544}) 4545``` 4546 4547### modifyImageProperty<sup>(deprecated)</sup> 4548 4549modifyImageProperty(key: string, value: string): Promise\<void> 4550 4551通过指定的键修改图片属性的值，使用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4552 4553> **说明：** 4554> 4555> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4556> 4557> 从API version 11开始不再维护，建议使用[modifyImageProperty](#modifyimageproperty11)代替。 4558 4559**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4560 4561**参数：** 4562 4563| 参数名 | 类型 | 必填 | 说明 | 4564| ------- | ------ | ---- | ------------ | 4565| key | string | 是 | 图片属性名。 | 4566| value | string | 是 | 属性值。 | 4567 4568**返回值：** 4569 4570| 类型 | 说明 | 4571| -------------- | --------------------------- | 4572| Promise\<void> | Promise对象。无返回结果的Promise对象。| 4573 4574**示例：** 4575 4576```ts 4577import { BusinessError } from '@kit.BasicServicesKit'; 4578 4579imageSourceApi.modifyImageProperty("ImageWidth", "120").then(() => { 4580 imageSourceApi.getImageProperty("ImageWidth").then((width: string) => { 4581 console.info(`ImageWidth is :${width}`); 4582 }).catch((error: BusinessError) => { 4583 console.error('Failed to get the Image Width.'); 4584 }) 4585}).catch((error: BusinessError) => { 4586 console.error('Failed to modify the Image Width'); 4587}) 4588``` 4589 4590### modifyImageProperty<sup>(deprecated)</sup> 4591 4592modifyImageProperty(key: string, value: string, callback: AsyncCallback\<void>): void 4593 4594通过指定的键修改图片属性的值，callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4595 4596> **说明：** 4597> 4598> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4599> 4600>从API version 11开始不再维护，建议使用[modifyImageProperty](#modifyimageproperty11)代替。 4601 4602**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4603 4604**参数：** 4605 4606| 参数名 | 类型 | 必填 | 说明 | 4607| -------- | ------------------- | ---- | ------------------------------ | 4608| key | string | 是 | 图片属性名。 | 4609| value | string | 是 | 属性值。 | 4610| callback | AsyncCallback\<void> | 是 | 回调函数，当修改图片属性值成功，err为undefined，否则为错误对象。 | 4611 4612**示例：** 4613 4614```ts 4615import { BusinessError } from '@kit.BasicServicesKit'; 4616 4617imageSourceApi.modifyImageProperty("ImageWidth", "120", (err: BusinessError) => { 4618 if (err) { 4619 console.error(`Failed to modify the Image Width.code is ${err.code}, message is ${err.message}`); 4620 } else { 4621 console.info('Succeeded in modifying the Image Width.'); 4622 } 4623}) 4624``` 4625 4626### modifyImageProperties<sup>12+</sup> 4627 4628modifyImageProperties(records: Record<PropertyKey, string|null>): Promise\<void> 4629 4630批量通过指定的键修改图片属性的值，使用Promise形式返回结果。仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4631 4632> **说明：** 4633> 4634> 调用modifyImageProperties修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperties会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4635> 4636 4637**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4638 4639**参数：** 4640 4641| 参数名 | 类型 | 必填 | 说明 | 4642| ------- | ------ | ---- | ------------ | 4643| records | Record<[PropertyKey](#propertykey7), string \| null> | 是 | 包含图片属性名和属性值的数组。 | 4644 4645**返回值：** 4646 4647| 类型 | 说明 | 4648| -------------- | --------------------------- | 4649| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4650 4651**错误码：** 4652 4653以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4654 4655| 错误码ID | 错误信息 | 4656| ------- | --------------------------------------------| 4657| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4658| 62980123| The image does not support EXIF decoding. | 4659| 62980133| The EXIF data is out of range. | 4660| 62980135| The EXIF value is invalid. | 4661| 62980146| The EXIF data failed to be written to the file. | 4662 4663**示例：** 4664 4665```ts 4666import { image } from '@kit.ImageKit'; 4667import { BusinessError } from '@kit.BasicServicesKit'; 4668 4669let keyValues: Record<PropertyKey, string|null> = { 4670 [image.PropertyKey.IMAGE_WIDTH] : "1024", 4671 [image.PropertyKey.IMAGE_LENGTH] : "1024" 4672}; 4673let checkKey = [image.PropertyKey.IMAGE_WIDTH, image.PropertyKey.IMAGE_LENGTH]; 4674imageSourceApi.modifyImageProperties(keyValues).then(() => { 4675 imageSourceApi.getImageProperties(checkKey).then((data) => { 4676 console.info(JSON.stringify(data)); 4677 }).catch((err: BusinessError) => { 4678 console.error(JSON.stringify(err)); 4679 }); 4680}).catch((err: BusinessError) => { 4681 console.error(JSON.stringify(err)); 4682}); 4683``` 4684 4685### updateData<sup>9+</sup> 4686 4687updateData(buf: ArrayBuffer, isFinished: boolean, offset: number, length: number): Promise\<void> 4688 4689更新增量数据，使用Promise形式返回结果。 4690 4691**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4692 4693**参数：** 4694 4695| 参数名 | 类型 | 必填 | 说明 | 4696| ---------- | ----------- | ---- | ------------ | 4697| buf | ArrayBuffer | 是 | 增量数据。 | 4698| isFinished | boolean | 是 | 是否更新完。 | 4699| offset | number | 是 | 偏移量。 | 4700| length | number | 是 | 数组长。 | 4701 4702**返回值：** 4703 4704| 类型 | 说明 | 4705| -------------- | -------------------------- | 4706| Promise\<void> | Promise对象。无返回结果的Promise对象。| 4707 4708**示例：** 4709 4710```ts 4711import { BusinessError } from '@kit.BasicServicesKit'; 4712 4713const array: ArrayBuffer = new ArrayBuffer(100); 4714imageSourceApi.updateData(array, false, 0, 10).then(() => { 4715 console.info('Succeeded in updating data.'); 4716}).catch((err: BusinessError) => { 4717 console.error(`Failed to update data.code is ${err.code},message is ${err.message}`); 4718}) 4719``` 4720 4721 4722### updateData<sup>9+</sup> 4723 4724updateData(buf: ArrayBuffer, isFinished: boolean, offset: number, length: number, callback: AsyncCallback\<void>): void 4725 4726更新增量数据，callback形式返回结果。 4727 4728**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4729 4730**参数：** 4731 4732| 参数名 | 类型 | 必填 | 说明 | 4733| ---------- | ------------------- | ---- | -------------------- | 4734| buf | ArrayBuffer | 是 | 增量数据。 | 4735| isFinished | boolean | 是 | 是否更新完。 | 4736| offset | number | 是 | 偏移量。 | 4737| length | number | 是 | 数组长。 | 4738| callback | AsyncCallback\<void> | 是 | 回调函数，当更新增量数据成功，err为undefined，否则为错误对象。 | 4739 4740**示例：** 4741 4742```ts 4743import { BusinessError } from '@kit.BasicServicesKit'; 4744 4745const array: ArrayBuffer = new ArrayBuffer(100); 4746imageSourceApi.updateData(array, false, 0, 10, (err: BusinessError) => { 4747 if (err) { 4748 console.error(`Failed to update data.code is ${err.code},message is ${err.message}`); 4749 } else { 4750 console.info('Succeeded in updating data.'); 4751 } 4752}) 4753``` 4754 4755### createPicture<sup>13+</sup> 4756 4757createPicture(options?: DecodingOptionsForPicture): Promise\<Picture> 4758 4759通过图片解码参数创建Picture对象,使用Promise形式返回。 4760 4761**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4762 4763**参数：** 4764 4765| 参数名 | 类型 | 必填 | 说明 | 4766| ------- | ------------------------------------------------------ | ---- | ---------- | 4767| options | [DecodingOptionsForPicture](#decodingoptionsforpicture13) | 否 | 解码参数。 | 4768 4769**返回值：** 4770 4771| 类型 | 说明 | 4772| ---------------------------- | -------------------------- | 4773| Promise\<[Picture](#picture13)> | Promise对象，返回Picture。 | 4774 4775**错误码：** 4776 4777以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4778 4779| 错误码ID | 错误信息 | 4780| -------- | ------------------------------------------------------------ | 4781| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified.2.Incorrect parameter types; 3.Parameter verification failed. | 4782| 7700301 | Decode failed. | 4783 4784**示例：** 4785 4786```ts 4787import { image } from '@kit.ImageKit'; 4788 4789async function CreatePicture() { 4790 let options: image.DecodingOptionsForPicture = { 4791 desiredAuxiliaryPictures: [image.AuxiliaryPictureType.GAINMAP] //GAINMAP为需要解码的辅助图类型。 4792 }; 4793 let pictureObj: image.Picture = await imageSourceApi.createPicture(options); 4794 if (pictureObj != null) { 4795 console.info('Create picture succeeded'); 4796 } else { 4797 console.info('Create picture failed'); 4798 } 4799} 4800``` 4801 4802### createPixelMap<sup>7+</sup> 4803 4804createPixelMap(options?: DecodingOptions): Promise\<PixelMap> 4805 4806通过图片解码参数创建PixelMap对象。 4807 4808**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4809 4810**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4811 4812**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4813 4814**参数：** 4815 4816| 参数名 | 类型 | 必填 | 说明 | 4817| ------- | ------------------------------------ | ---- | ---------- | 4818| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 4819 4820**返回值：** 4821 4822| 类型 | 说明 | 4823| -------------------------------- | --------------------- | 4824| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 4825 4826**示例：** 4827 4828```ts 4829import { BusinessError } from '@kit.BasicServicesKit'; 4830 4831imageSourceApi.createPixelMap().then((pixelMap: image.PixelMap) => { 4832 console.info('Succeeded in creating pixelMap object through image decoding parameters.'); 4833}).catch((error: BusinessError) => { 4834 console.error('Failed to create pixelMap object through image decoding parameters.'); 4835}) 4836``` 4837 4838### createPixelMap<sup>7+</sup> 4839 4840createPixelMap(callback: AsyncCallback\<PixelMap>): void 4841 4842通过默认参数创建PixelMap对象，使用callback形式返回结果。 4843 4844**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4845 4846**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4847 4848**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4849 4850**参数：** 4851 4852| 参数名 | 类型 | 必填 | 说明 | 4853| -------- | ------------------------------------- | ---- | -------------------------- | 4854| callback | AsyncCallback<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap对象成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 4855 4856**示例：** 4857 4858```ts 4859import { BusinessError } from '@kit.BasicServicesKit'; 4860 4861imageSourceApi.createPixelMap((err: BusinessError, pixelMap: image.PixelMap) => { 4862 if (err) { 4863 console.error(`Failed to create pixelMap.code is ${err.code},message is ${err.message}`); 4864 } else { 4865 console.info('Succeeded in creating pixelMap object.'); 4866 } 4867}) 4868``` 4869 4870### createPixelMap<sup>7+</sup> 4871 4872createPixelMap(options: DecodingOptions, callback: AsyncCallback\<PixelMap>): void 4873 4874通过图片解码参数创建PixelMap对象。 4875 4876**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4877 4878**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4879 4880**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4881 4882**参数：** 4883 4884| 参数名 | 类型 | 必填 | 说明 | 4885| -------- | ------------------------------------- | ---- | -------------------------- | 4886| options | [DecodingOptions](#decodingoptions7) | 是 | 解码参数。 | 4887| callback | AsyncCallback<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap对象成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 4888 4889**示例：** 4890 4891```ts 4892import { BusinessError } from '@kit.BasicServicesKit'; 4893 4894let decodingOptions: image.DecodingOptions = { 4895 sampleSize: 1, 4896 editable: true, 4897 desiredSize: { width: 1, height: 2 }, 4898 rotate: 10, 4899 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 4900 desiredRegion: { size: { height: 1, width: 2 }, x: 0, y: 0 }, 4901 index: 0 4902}; 4903imageSourceApi.createPixelMap(decodingOptions, (err: BusinessError, pixelMap: image.PixelMap) => { 4904 if (err) { 4905 console.error(`Failed to create pixelMap.code is ${err.code},message is ${err.message}`); 4906 } else { 4907 console.info('Succeeded in creating pixelMap object.'); 4908 } 4909}) 4910``` 4911 4912### createPixelMapSync<sup>12+</sup> 4913 4914createPixelMapSync(options?: DecodingOptions): PixelMap 4915 4916通过图片解码参数同步创建PixelMap对象。 4917 4918**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4919 4920**参数：** 4921 4922| 参数名 | 类型 | 必填 | 说明 | 4923| -------- | ------------------------------------- | ---- | -------------------------- | 4924| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 4925 4926**返回值：** 4927 4928| 类型 | 说明 | 4929| -------------------------------- | --------------------- | 4930| [PixelMap](#pixelmap7) | 用于同步返回创建结果。 | 4931 4932**示例：** 4933 4934```ts 4935import { image } from '@kit.ImageKit'; 4936 4937const context: Context = getContext(); 4938//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4939let filePath: string = context.filesDir + "/test.jpg"; 4940let imageSource = image.createImageSource(filePath); 4941let decodingOptions: image.DecodingOptions = { 4942 sampleSize: 1, 4943 editable: true, 4944 desiredSize: { width: 1, height: 2 }, 4945 rotate: 10, 4946 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 4947 desiredRegion: { size: { height: 1, width: 2 }, x: 0, y: 0 }, 4948 index: 0 4949}; 4950let pixelmap = imageSource.createPixelMapSync(decodingOptions); 4951if (pixelmap != undefined) { 4952 console.info('Succeeded in creating pixelMap object.'); 4953} else { 4954 console.info('Failed to create pixelMap.'); 4955} 4956``` 4957 4958### createPixelMapList<sup>10+</sup> 4959 4960createPixelMapList(options?: DecodingOptions): Promise<Array\<PixelMap>> 4961 4962通过图片解码参数创建PixelMap数组。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 4963 4964> **注意：** 4965> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 4966 4967**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4968 4969**参数：** 4970 4971| 参数名 | 类型 | 必填 | 说明 | 4972| -------- | ------------------------------------- | ---- | -------------------------- | 4973| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 4974 4975**返回值：** 4976 4977| 类型 | 说明 | 4978| -------------------------------- | --------------------- | 4979| Promise<Array<[PixelMap](#pixelmap7)>> | 异步返回PixeMap数组。 | 4980 4981**错误码：** 4982 4983以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4984 4985| 错误码ID | 错误信息 | 4986| ------- | --------------------------------------------| 4987| 62980096| The operation failed. | 4988| 62980099 | The shared memory data is abnormal. | 4989| 62980101 | The image data is abnormal. | 4990| 62980103| The image data is not supported. | 4991| 62980106 | The image is too large. | 4992| 62980109 | Failed to crop the image. | 4993| 62980110| The image source data is incorrect. | 4994| 62980111| The image source data is incomplete. | 4995| 62980112 | The image format does not match. | 4996| 62980113 | Unknown image format. | 4997| 62980115 | Invalid image parameter. | 4998| 62980116 | Failed to decode the image. | 4999| 62980118| Failed to create the image plugin. | 5000| 62980122 | Failed to decode the image header. | 5001| 62980137 | Invalid media operation. | 5002| 62980173 | The DMA memory does not exist. | 5003| 62980174 | The DMA memory data is abnormal. | 5004 5005**示例：** 5006 5007```ts 5008import { BusinessError } from '@kit.BasicServicesKit'; 5009 5010let decodeOpts: image.DecodingOptions = { 5011 sampleSize: 1, 5012 editable: true, 5013 desiredSize: { width: 198, height: 202 }, 5014 rotate: 0, 5015 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5016 index: 0, 5017}; 5018imageSourceApi.createPixelMapList(decodeOpts).then((pixelMapList: Array<image.PixelMap>) => { 5019 console.info('Succeeded in creating pixelMapList object.'); 5020}).catch((err: BusinessError) => { 5021 console.error(`Failed to create pixelMapList object.code is ${err.code},message is ${err.message}`); 5022}) 5023``` 5024 5025### createPixelMapList<sup>10+</sup> 5026 5027createPixelMapList(callback: AsyncCallback<Array\<PixelMap>>): void 5028 5029通过默认参数创建PixelMap数组，使用callback形式返回结果。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5030 5031> **注意：** 5032> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5033 5034**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5035 5036**参数：** 5037 5038| 参数名 | 类型 | 必填 | 说明 | 5039| -------- | ------------------------------------- | ---- | -------------------------- | 5040| callback | AsyncCallback<Array<[PixelMap](#pixelmap7)>> | 是 | 回调函数，当创建PixelMap对象数组成功，err为undefined，data为获取到的PixelMap对象数组；否则为错误对象。 | 5041 5042**错误码：** 5043 5044以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5045 5046| 错误码ID | 错误信息 | 5047| ------- | --------------------------------------------| 5048| 62980096 | The operation failed. | 5049| 62980099 | The shared memory data is abnormal. | 5050| 62980101 | The image data is abnormal. | 5051| 62980103 | The image data is not supported. | 5052| 62980106 | The image is too large. | 5053| 62980109 | Failed to crop the image. | 5054| 62980110 | The image source data is incorrect. | 5055| 62980111 | The image source data is incomplete. | 5056| 62980112 | The image format does not match. | 5057| 62980113 | Unknown image format. | 5058| 62980115 | Invalid image parameter. | 5059| 62980116 | Failed to decode the image. | 5060| 62980118 | Failed to create the image plugin. | 5061| 62980122 | Failed to decode the image header. | 5062| 62980137 | Invalid media operation. | 5063| 62980173 | The DMA memory does not exist. | 5064| 62980174 | The DMA memory data is abnormal. | 5065 5066**示例：** 5067 5068```ts 5069import { BusinessError } from '@kit.BasicServicesKit'; 5070 5071imageSourceApi.createPixelMapList((err: BusinessError, pixelMapList: Array<image.PixelMap>) => { 5072 if (err) { 5073 console.error(`Failed to create pixelMapList object.code is ${err.code},message is ${err.message}`); 5074 } else { 5075 console.info('Succeeded in creating pixelMapList object.'); 5076 } 5077}) 5078``` 5079 5080### createPixelMapList<sup>10+</sup> 5081 5082createPixelMapList(options: DecodingOptions, callback: AsyncCallback<Array\<PixelMap>>): void 5083 5084通过图片解码参数创建PixelMap数组，使用callback形式返回结果。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5085 5086> **注意：** 5087> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5088 5089**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5090 5091**参数：** 5092 5093| 参数名 | 类型 | 必填 | 说明 | 5094| -------- | -------------------- | ---- | ---------------------------------- | 5095| options | [DecodingOptions](#decodingoptions7) | 是 | 解码参数。 | 5096| callback | AsyncCallback<Array<[PixelMap](#pixelmap7)>> | 是 | 回调函数，当创建PixelMap对象数组成功，err为undefined，data为获取到的PixelMap对象数组；否则为错误对象。 | 5097 5098**错误码：** 5099 5100以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5101 5102| 错误码ID | 错误信息 | 5103| ------- | --------------------------------------------| 5104| 62980096 | The operation failed. | 5105| 62980099 | The shared memory data is abnormal. | 5106| 62980101 | The image data is abnormal. | 5107| 62980103 | The image data is not supported. | 5108| 62980106 | The image is too large. | 5109| 62980109 | Failed to crop the image. | 5110| 62980110 | The image source data is incorrect. | 5111| 62980111 | The image source data is incomplete. | 5112| 62980112 | The image format does not match. | 5113| 62980113 | Unknown image format. | 5114| 62980115 | Invalid image parameter. | 5115| 62980116 | Failed to decode the image. | 5116| 62980118 | Failed to create the image plugin. | 5117| 62980122 | Failed to decode the image header. | 5118| 62980137 | Invalid media operation. | 5119| 62980173 | The DMA memory does not exist. | 5120| 62980174 | The DMA memory data is abnormal. | 5121 5122**示例：** 5123 5124```ts 5125import { BusinessError } from '@kit.BasicServicesKit'; 5126 5127let decodeOpts: image.DecodingOptions = { 5128 sampleSize: 1, 5129 editable: true, 5130 desiredSize: { width: 198, height: 202 }, 5131 rotate: 0, 5132 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5133 index: 0, 5134}; 5135imageSourceApi.createPixelMapList(decodeOpts, (err: BusinessError, pixelMapList: Array<image.PixelMap>) => { 5136 if (err) { 5137 console.error(`Failed to create pixelMapList object.code is ${err.code},message is ${err.message}`); 5138 } else { 5139 console.info('Succeeded in creating pixelMapList object.'); 5140 } 5141}) 5142``` 5143### createPixelMapUsingAllocator<sup>15+</sup> 5144 5145createPixelMapUsingAllocator(option?: DecodingOptions, allocatorType?: AllocatorType): Promise\<PixelMap\> 5146 5147使用指定的分配器根据图像解码参数异步创建PixelMap对象。使用Promise返回对象。 5148 5149**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5150 5151**参数：** 5152 5153| 参数名 | 类型 | 必填 | 说明 | 5154| ------------- | ------------------------------------ | ---- | ------------------------ | 5155| option | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5156| allocatorType | [AllocatorType](#allocatortype15) | 否 | 用于图像解码的内存类型。默认值为AllocatorType.AUTO。 | 5157 5158**返回值：** 5159 5160| 类型 | 说明 | 5161| -------------------------------- | --------------------------- | 5162| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 5163 5164**错误码：** 5165 5166以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5167 5168| 错误码ID | 错误信息 | 5169| -------- | ------------------------------------------------------------ | 5170| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types;3.Parameter verification failed. | 5171| 7700101 | Bad source. | 5172| 7700102 | Unsupported mimetype. | 5173| 7700103 | Image too large. | 5174| 7700201 | Unsupported allocator type, e.g., use share memory to decode a HDR image as only DMA supported hdr metadata. | 5175| 7700203 | Unsupported options, e.g., cannot convert image into desired pixel format. | 5176| 7700301 | Decode failed. | 5177| 7700302 | Memory allocation failed. | 5178 5179**示例：** 5180 5181```ts 5182import image from '@ohos.multimedia.image'; 5183 5184const context: Context = getContext(this); 5185// 此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5186let filePath: string = context.filesDir + "/test.jpg"; 5187let imageSource = image.createImageSource(filePath); 5188let decodingOptions: image.DecodingOptions = { 5189 editable: true, 5190 desiredSize: { width: 3072, height: 4096 }, 5191 rotate: 10, 5192 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5193 desiredRegion: { size: { height: 3072, width: 4096 }, x: 0, y: 0 }, 5194 index: 0 5195}; 5196let pixelmap = await imageSource.createPixelMapUsingAllocator(decodingOptions, image.AllocatorType.AUTO); 5197if (pixelmap != undefined) { 5198 console.info('Succeeded in creating pixelMap object.'); 5199} else { 5200 console.info('Failed to create pixelMap.'); 5201} 5202``` 5203 5204### createPixelMapUsingAllocatorSync<sup>15+</sup> 5205 5206createPixelMapUsingAllocatorSync(option?: DecodingOptions, allocatorType?: AllocatorType): PixelMap 5207 5208根据指定的分配器同步创建一个基于图像解码参数的PixelMap对象。 5209 5210**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5211 5212**参数：** 5213 5214| 参数名 | 类型 | 必填 | 说明 | 5215| ------------- | ------------------------------------ | ---- | ------------------------ | 5216| option | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5217| allocatorType | [AllocatorType](#allocatortype15) | 否 | 用于图像解码的内存类型。默认值为AllocatorType.AUTO。 | 5218 5219**返回值：** 5220 5221| 类型 | 说明 | 5222| ---------------------- | ---------------------- | 5223| [PixelMap](#pixelmap7) | 用于同步返回创建结果。 | 5224 5225**错误码：** 5226 5227以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5228 5229| 错误码ID | 错误信息 | 5230| -------- | ------------------------------------------------------------ | 5231| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types;3.Parameter verification failed. | 5232| 7700101 | Bad source. | 5233| 7700102 | Unsupported mimetype. | 5234| 7700103 | Image too large. | 5235| 7700201 | Unsupported allocator type, e.g., use share memory to decode a HDR image as only DMA supported hdr metadata. | 5236| 7700203 | Unsupported options, e.g., cannot convert image into desired pixel format. | 5237| 7700301 | Decode failed. | 5238| 7700302 | Memory allocation failed. | 5239 5240**示例：** 5241 5242```ts 5243import image from '@ohos.multimedia.image'; 5244 5245const context: Context = getContext(this); 5246// 此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5247let filePath: string = context.filesDir + "/test.jpg"; 5248let imageSource = image.createImageSource(filePath); 5249let decodingOptions: image.DecodingOptions = { 5250 editable: true, 5251 desiredSize: { width: 3072, height: 4096 }, 5252 rotate: 10, 5253 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5254 desiredRegion: { size: { height: 3072, width: 4096 }, x: 0, y: 0 }, 5255 index: 0 5256}; 5257let pixelmap = imageSource.createPixelMapUsingAllocatorSync(decodingOptions, image.AllocatorType.AUTO); 5258if (pixelmap != undefined) { 5259 console.info('Succeeded in creating pixelMap object.'); 5260} else { 5261 console.info('Failed to create pixelMap.'); 5262} 5263``` 5264 5265### getDelayTimeList<sup>10+</sup> 5266 5267getDelayTimeList(callback: AsyncCallback<Array\<number>>): void 5268 5269获取图像延迟时间数组，使用callback形式返回结果。此接口仅用于gif图片和webp图片。 5270 5271**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5272 5273**参数：** 5274 5275| 参数名 | 类型 | 必填 | 说明 | 5276| -------- | -------------------- | ---- | ---------------------------------- | 5277| callback | AsyncCallback<Array\<number>> | 是 | 回调函数，当获取图像延迟时间数组成功，err为undefined，data为获取到的图像延时时间数组；否则为错误对象。 | 5278 5279**错误码：** 5280 5281以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5282 5283| 错误码ID | 错误信息 | 5284| ------- | --------------------------------------------| 5285| 62980096| The operation failed. | 5286| 62980110| The image source data is incorrect. | 5287| 62980111| The image source data is incomplete. | 5288| 62980112 | The image format does not match. | 5289| 62980113| Unknown image format. | 5290| 62980115 | Invalid image parameter. | 5291| 62980116| Failed to decode the image. | 5292| 62980118| Failed to create the image plugin. | 5293| 62980122| Failed to decode the image header. | 5294| 62980137 | Invalid media operation. | 5295| 62980149 | Invalid MIME type for the image source. | 5296 5297**示例：** 5298 5299```ts 5300import { BusinessError } from '@kit.BasicServicesKit'; 5301 5302imageSourceApi.getDelayTimeList((err: BusinessError, delayTimes: Array<number>) => { 5303 if (err) { 5304 console.error(`Failed to get delayTimes object.code is ${err.code},message is ${err.message}`); 5305 } else { 5306 console.info('Succeeded in getting delayTimes object.'); 5307 } 5308}) 5309``` 5310 5311### getDelayTimeList<sup>10+</sup> 5312 5313getDelayTimeList(): Promise<Array\<number>> 5314 5315获取图像延迟时间数组，使用Promise形式返回结果。此接口仅用于gif图片和webp图片。 5316 5317**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5318 5319**返回值：** 5320 5321| 类型 | 说明 | 5322| -------------- | --------------------------- | 5323| Promise<Array\<number>> | Promise对象，返回延迟时间数组。 | 5324 5325**错误码：** 5326 5327以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5328 5329| 错误码ID | 错误信息 | 5330| ------- | --------------------------------------------| 5331| 62980096 | The operation failed. | 5332| 62980110 | The image source data is incorrect. | 5333| 62980111 | The image source data is incomplete. | 5334| 62980112 | The image format does not match. | 5335| 62980113 | Unknown image format. | 5336| 62980115 | Invalid image parameter. | 5337| 62980116 | Failed to decode the image. | 5338| 62980118 | Failed to create the image plugin. | 5339| 62980122 | Failed to decode the image header. | 5340| 62980137 | Invalid media operation. | 5341| 62980149 | Invalid MIME type for the image source. | 5342 5343**示例：** 5344 5345```ts 5346import { BusinessError } from '@kit.BasicServicesKit'; 5347 5348imageSourceApi.getDelayTimeList().then((delayTimes: Array<number>) => { 5349 console.info('Succeeded in getting delayTimes object.'); 5350}).catch((err: BusinessError) => { 5351 console.error(`Failed to get delayTimes object.code is ${err.code},message is ${err.message}`); 5352}) 5353``` 5354 5355### getFrameCount<sup>10+</sup> 5356 5357getFrameCount(callback: AsyncCallback\<number>): void 5358 5359获取图像帧数，使用callback形式返回结果。 5360 5361**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5362 5363**参数：** 5364 5365| 参数名 | 类型 | 必填 | 说明 | 5366| -------- | -------------------- | ---- | ---------------------------------- | 5367| callback | AsyncCallback\<number> | 是 | 回调函数，当获取图像帧数成功，err为undefined，data为获取到的图像帧数；否则为错误对象。 | 5368 5369**错误码：** 5370 5371以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5372 5373| 错误码ID | 错误信息 | 5374| ------- | --------------------------------------------| 5375| 62980096| The operation failed. | 5376| 62980110| The image source data is incorrect. | 5377| 62980111| The image source data is incomplete. | 5378| 62980112| The image format does not match. | 5379| 62980113| Unknown image format. | 5380| 62980115| Invalid image parameter. | 5381| 62980116| Failed to decode the image. | 5382| 62980118| Failed to create the image plugin. | 5383| 62980122| Failed to decode the image header. | 5384| 62980137| Invalid media operation. | 5385 5386**示例：** 5387 5388```ts 5389import { BusinessError } from '@kit.BasicServicesKit'; 5390 5391imageSourceApi.getFrameCount((err: BusinessError, frameCount: number) => { 5392 if (err) { 5393 console.error(`Failed to get frame count.code is ${err.code},message is ${err.message}`); 5394 } else { 5395 console.info('Succeeded in getting frame count.'); 5396 } 5397}) 5398``` 5399 5400### getFrameCount<sup>10+</sup> 5401 5402getFrameCount(): Promise\<number> 5403 5404获取图像帧数，使用Promise形式返回结果。 5405 5406**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5407 5408**返回值：** 5409 5410| 类型 | 说明 | 5411| -------------- | --------------------------- | 5412| Promise\<number> | Promise对象，返回图像帧数。 | 5413 5414**错误码：** 5415 5416以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5417 5418| 错误码ID | 错误信息 | 5419| ------- | --------------------------------------------| 5420| 62980096 | The operation failed. | 5421| 62980110 | The image source data is incorrect. | 5422| 62980111 | The image source data is incomplete. | 5423| 62980112 | The image format does not match. | 5424| 62980113 | Unknown image format. | 5425| 62980115 | Invalid image parameter. | 5426| 62980116 | Failed to decode the image. | 5427| 62980118 | Failed to create the image plugin. | 5428| 62980122 | Failed to decode the image header. | 5429| 62980137 | Invalid media operation. | 5430 5431**示例：** 5432 5433```ts 5434import { BusinessError } from '@kit.BasicServicesKit'; 5435 5436imageSourceApi.getFrameCount().then((frameCount: number) => { 5437 console.info('Succeeded in getting frame count.'); 5438}).catch((err: BusinessError) => { 5439 console.error(`Failed to get frame count.code is ${err.code},message is ${err.message}`); 5440}) 5441``` 5442 5443### getDisposalTypeList<sup>12+</sup> 5444 5445getDisposalTypeList(): Promise\<Array\<number>> 5446 5447获取图像帧过渡模式数组，使用Promise形式返回结果。此接口仅用于gif图片。 5448 5449**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5450 5451**返回值：** 5452 5453| 类型 | 说明 | 5454| -------------- | --------------------------- | 5455| Promise\<Array\<number>> | Promise对象，返回帧过渡模式数组。 | 5456 5457**错误码：** 5458 5459以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5460 5461| 错误码ID | 错误信息 | 5462| ------- | --------------------------------------------| 5463| 62980096 | The operation failed. | 5464| 62980101 | The image data is abnormal. | 5465| 62980137 | Invalid media operation. | 5466| 62980149 | Invalid MIME type for the image source. | 5467 5468**示例：** 5469 5470```ts 5471import { BusinessError } from '@kit.BasicServicesKit'; 5472imageSourceApi.getDisposalTypeList().then((disposalTypes: Array<number>) => { 5473 console.info('Succeeded in getting disposalTypes object.'); 5474}).catch((err: BusinessError) => { 5475 console.error(`Failed to get disposalTypes object.code ${err.code},message is ${err.message}`); 5476}) 5477``` 5478 5479### release 5480 5481release(callback: AsyncCallback\<void>): void 5482 5483释放图片源实例，使用callback形式返回结果。 5484 5485ArkTS有内存回收机制，ImageSource对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5486 5487**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5488 5489**参数：** 5490 5491| 参数名 | 类型 | 必填 | 说明 | 5492| -------- | -------------------- | ---- | ---------------------------------- | 5493| callback | AsyncCallback\<void> | 是 | 回调函数，当资源释放成功，err为undefined，否则为错误对象。 | 5494 5495**示例：** 5496 5497```ts 5498import { BusinessError } from '@kit.BasicServicesKit'; 5499 5500imageSourceApi.release((err: BusinessError) => { 5501 if (err) { 5502 console.error(`Failed to release the image source instance.code ${err.code},message is ${err.message}`); 5503 } else { 5504 console.info('Succeeded in releasing the image source instance.'); 5505 } 5506}) 5507``` 5508 5509### release 5510 5511release(): Promise\<void> 5512 5513释放图片源实例，使用Promise形式返回结果。 5514 5515ArkTS有内存回收机制，ImageSource对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5516 5517**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5518 5519**返回值：** 5520 5521| 类型 | 说明 | 5522| -------------- | --------------------------- | 5523| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 5524 5525**示例：** 5526 5527```ts 5528import { BusinessError } from '@kit.BasicServicesKit'; 5529 5530imageSourceApi.release().then(() => { 5531 console.info('Succeeded in releasing the image source instance.'); 5532}).catch((error: BusinessError) => { 5533 console.error(`Failed to release the image source instance.code ${error.code},message is ${error.message}`); 5534}) 5535``` 5536 5537## image.createImagePacker 5538 5539createImagePacker(): ImagePacker 5540 5541创建ImagePacker实例。 5542 5543**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5544 5545**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5546 5547**返回值：** 5548 5549| 类型 | 说明 | 5550| --------------------------- | --------------------- | 5551| [ImagePacker](#imagepacker) | 返回ImagePacker实例。 | 5552 5553**示例：** 5554 5555```ts 5556const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5557``` 5558 5559## ImagePacker 5560 5561图片打包器类，用于图片压缩和打包。在调用ImagePacker的方法前，需要先通过[createImagePacker](#imagecreateimagepacker)构建一个ImagePacker实例，当前支持格式有：jpeg、webp、png、heif<sup>12+</sup>（不同硬件设备支持情况不同）。 5562 5563### 属性 5564 5565**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5566 5567| 名称 | 类型 | 可读 | 可写 | 说明 | 5568| ---------------- | -------------- | ---- | ---- | -------------------------- | 5569| supportedFormats | Array\<string> | 是 | 否 | 图片打包支持的格式 jpeg、webp、png、heic<sup>12+</sup>（不同硬件设备支持情况不同）。 | 5570 5571### packToData<sup>13+</sup> 5572 5573packToData(source: ImageSource, options: PackingOption): Promise\<ArrayBuffer> 5574 5575图片压缩或重新打包，使用Promise形式返回结果。 5576 5577**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 5578 5579**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5580 5581**参数：** 5582 5583| 参数名 | 类型 | 必填 | 说明 | 5584| ------ | ------------------------------- | ---- | -------------- | 5585| source | [ImageSource](#imagesource) | 是 | 打包的图片源。 | 5586| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5587 5588**错误码：** 5589 5590以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5591 5592| 错误码ID | 错误信息 | 5593| ------- | --------------------------------------------| 5594| 401 | If the parameter is invalid. | 5595| 62980096| The Operation failed. | 5596| 62980101 | The image data is abnormal. | 5597| 62980106 | The image is too large. | 5598| 62980113 | Unknown image format. | 5599| 62980119 | If encoder occur error during encoding. | 5600| 62980120 | Add pixelmap out of range. | 5601| 62980172 | Failed to encode icc. | 5602| 62980252 | Failed to create surface. | 5603 5604**返回值：** 5605 5606| 类型 | 说明 | 5607| ---------------------------- | --------------------------------------------- | 5608| Promise\<ArrayBuffer> | Promise对象，返回压缩或打包后的数据。 | 5609 5610**示例：** 5611 5612```ts 5613import { BusinessError } from '@kit.BasicServicesKit'; 5614 5615const context: Context = getContext(); 5616//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 5617let filePath: string = context.filesDir + "/test.jpg"; 5618const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 5619let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5620const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5621imagePackerApi.packToData(imageSourceApi, packOpts) 5622 .then((data: ArrayBuffer) => { 5623 console.info('Succeeded in packing the image.'); 5624 }).catch((error: BusinessError) => { 5625 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 5626 }) 5627``` 5628 5629### packToData<sup>13+</sup> 5630 5631packToData(source: PixelMap, options: PackingOption): Promise\<ArrayBuffer> 5632 5633图片压缩或重新打包，使用Promise形式返回结果。 5634 5635> **注意：** 5636> 接口如果返回401错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 5637 5638**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 5639 5640**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5641 5642**参数：** 5643 5644| 参数名 | 类型 | 必填 | 说明 | 5645| ------ | ------------------------------- | ---- | ------------------ | 5646| source | [PixelMap](#pixelmap7) | 是 | 打包的PixelMap源。 | 5647| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5648 5649**返回值：** 5650 5651| 类型 | 说明 | 5652| --------------------- | -------------------------------------------- | 5653| Promise\<ArrayBuffer> | Promise对象，返回压缩或打包后的数据。| 5654 5655**错误码：** 5656 5657以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5658 5659| 错误码ID | 错误信息 | 5660| ------- | --------------------------------------------| 5661| 401 | If the parameter is invalid. | 5662| 62980096| The Operation failed. | 5663| 62980101 | The image data is abnormal. | 5664| 62980106 | The image is too large. | 5665| 62980113 | Unknown image format. | 5666| 62980119 | If encoder occur error during encoding. | 5667| 62980120 | Add pixelmap out of range. | 5668| 62980172 | Failed to encode icc. | 5669| 62980252 | Failed to create surface. | 5670 5671**示例：** 5672 5673```ts 5674import { BusinessError } from '@kit.BasicServicesKit'; 5675 5676const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 5677let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 5678image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 5679 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5680 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5681 imagePackerApi.packToData(pixelMap, packOpts) 5682 .then((data: ArrayBuffer) => { 5683 console.info('Succeeded in packing the image.'); 5684 }).catch((error: BusinessError) => { 5685 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 5686 }) 5687}).catch((error: BusinessError) => { 5688 console.error(`Failed to create PixelMap.code ${error.code},message is ${error.message}`); 5689}) 5690``` 5691 5692### packing<sup>13+</sup> 5693 5694packing(picture: Picture, options: PackingOption): Promise\<ArrayBuffer> 5695 5696将图像压缩或重新打包，使用Promise形式返回结果。 5697 5698**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5699 5700**参数：** 5701 5702| 参数名 | 类型 | 必填 | 说明 | 5703| ---------------- | ---------------------------------------------------- | ---- | -------------------- | 5704| picture | [Picture](#picture13) | 是 | 打包的Picture对象。 | 5705| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5706 5707**返回值：** 5708 5709| 类型 | 说明 | 5710| --------------------- | ------------------------------------- | 5711| Promise\<ArrayBuffer> | Promise对象，返回压缩或打包后的数据。 | 5712 5713**错误码：** 5714 5715以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5716 5717| 错误码ID | 错误信息 | 5718| -------- | ------------------------------------------------------------ | 5719| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 5720| 7800301 | Encode failed. | 5721 5722**示例：** 5723 5724```ts 5725import { BusinessError } from '@kit.BasicServicesKit'; 5726import { image } from '@kit.ImageKit'; 5727 5728async function Packing() { 5729 const context = getContext(); 5730 const resourceMgr = context.resourceManager; 5731 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 5732 let ops: image.SourceOptions = { 5733 sourceDensity: 98, 5734 } 5735 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 5736 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 5737 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 5738 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5739 let funcName = "Packing"; 5740 if (imagePackerApi != null) { 5741 let opts: image.PackingOption = { 5742 format: "image/jpeg", 5743 quality: 98, 5744 bufferSize: 10, 5745 desiredDynamicRange: image.PackingDynamicRange.AUTO, 5746 needsPackProperties: true}; 5747 await imagePackerApi.packing(pictureObj, opts).then((data: ArrayBuffer) => { 5748 console.info(funcName, 'Succeeded in packing the image.'+ data); 5749 }).catch((error: BusinessError) => { 5750 console.error(funcName, 'Failed to pack the image.code ${error.code},message is ${error.message}'); 5751 }); 5752 } 5753} 5754``` 5755 5756### packing<sup>(deprecated)</sup> 5757 5758packing(source: ImageSource, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 5759 5760图片压缩或重新打包，使用callback形式返回结果。 5761 5762> **说明：** 5763> 5764> 从API version 6开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 5765 5766**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5767 5768**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5769 5770**参数：** 5771 5772| 参数名 | 类型 | 必填 | 说明 | 5773| -------- | ---------------------------------- | ---- | ---------------------------------- | 5774| source | [ImageSource](#imagesource) | 是 | 打包的图片源。 | 5775| option | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5776| callback | AsyncCallback\<ArrayBuffer> | 是 | 回调函数，当图片打包成功，err为undefined，data为获取到的压缩或打包数据；否则为错误对象。 | 5777 5778**示例：** 5779 5780```ts 5781import { BusinessError } from '@kit.BasicServicesKit'; 5782 5783const context: Context = getContext(); 5784//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 5785let filePath: string = context.filesDir + "/test.jpg"; 5786const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 5787let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 5788const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5789imagePackerApi.packing(imageSourceApi, packOpts, (err: BusinessError, data: ArrayBuffer) => { 5790 if (err) { 5791 console.error(`Failed to pack the image.code ${err.code},message is ${err.message}`); 5792 } else { 5793 console.info('Succeeded in packing the image.'); 5794 } 5795}) 5796``` 5797 5798### packing<sup>(deprecated)</sup> 5799 5800packing(source: ImageSource, option: PackingOption): Promise\<ArrayBuffer> 5801 5802图片压缩或重新打包，使用Promise形式返回结果。 5803 5804> **说明：** 5805> 5806> 从API version 6开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 5807 5808**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5809 5810**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5811 5812**参数：** 5813 5814| 参数名 | 类型 | 必填 | 说明 | 5815| ------ | ------------------------------- | ---- | -------------- | 5816| source | [ImageSource](#imagesource) | 是 | 打包的图片源。 | 5817| option | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5818 5819**返回值：** 5820 5821| 类型 | 说明 | 5822| ---------------------------- | --------------------------------------------- | 5823| Promise\<ArrayBuffer> | Promise对象，返回压缩或打包后的数据。 | 5824 5825**示例：** 5826 5827```ts 5828import { BusinessError } from '@kit.BasicServicesKit'; 5829 5830const context: Context = getContext(); 5831//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 5832let filePath: string = context.filesDir + "/test.jpg"; 5833const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 5834let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5835const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5836imagePackerApi.packing(imageSourceApi, packOpts) 5837 .then((data: ArrayBuffer) => { 5838 console.info('Succeeded in packing the image.'); 5839 }).catch((error: BusinessError) => { 5840 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 5841 }) 5842``` 5843 5844### packing<sup>(deprecated)</sup> 5845 5846packing(source: PixelMap, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 5847 5848图片压缩或重新打包，使用callback形式返回结果。 5849 5850> **说明：** 5851> 5852> 从API version 8开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 5853 5854> **注意：** 5855> 接口如果返回"PixelMap mismatch"，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 5856 5857**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5858 5859**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5860 5861**参数：** 5862 5863| 参数名 | 类型 | 必填 | 说明 | 5864| -------- | ------------------------------- | ---- | ---------------------------------- | 5865| source | [PixelMap](#pixelmap7) | 是 | 打包的PixelMap资源。 | 5866| option | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5867| callback | AsyncCallback\<ArrayBuffer> | 是 | 回调函数，当图片打包成功，err为undefined，data为获取到的压缩或打包数据；否则为错误对象。 | 5868 5869**示例：** 5870 5871```ts 5872import { BusinessError } from '@kit.BasicServicesKit'; 5873 5874const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 5875let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 5876image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 5877 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5878 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5879 imagePackerApi.packing(pixelMap, packOpts, (err: BusinessError, data: ArrayBuffer) => { 5880 if (err) { 5881 console.error(`Failed to pack the image.code ${err.code},message is ${err.message}`); 5882 } else { 5883 console.info('Succeeded in packing the image.'); 5884 } 5885 }) 5886}).catch((error: BusinessError) => { 5887 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 5888}) 5889``` 5890 5891### packing<sup>(deprecated)</sup> 5892 5893packing(source: PixelMap, option: PackingOption): Promise\<ArrayBuffer> 5894 5895图片压缩或重新打包，使用Promise形式返回结果。 5896 5897> **说明：** 5898> 5899> 从API version 8开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 5900 5901> **注意：** 5902> 接口如果返回"PixelMap mismatch"，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 5903 5904**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5905 5906**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5907 5908**参数：** 5909 5910| 参数名 | 类型 | 必填 | 说明 | 5911| ------ | ------------------------------- | ---- | ------------------ | 5912| source | [PixelMap](#pixelmap7) | 是 | 打包的PixelMap源。 | 5913| option | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 5914 5915**返回值：** 5916 5917| 类型 | 说明 | 5918| --------------------- | -------------------------------------------- | 5919| Promise\<ArrayBuffer> | Promise对象，返回压缩或打包后的数据。| 5920 5921**示例：** 5922 5923```ts 5924import { BusinessError } from '@kit.BasicServicesKit'; 5925 5926const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 5927let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 5928image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 5929 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5930 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5931 imagePackerApi.packing(pixelMap, packOpts) 5932 .then((data: ArrayBuffer) => { 5933 console.info('Succeeded in packing the image.'); 5934 }).catch((error: BusinessError) => { 5935 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 5936 }) 5937}).catch((error: BusinessError) => { 5938 console.error(`Failed to create PixelMap.code ${error.code},message is ${error.message}`); 5939}) 5940``` 5941 5942### release 5943 5944release(callback: AsyncCallback\<void>): void 5945 5946释放图片打包实例，使用callback形式返回结果。 5947 5948ArkTS有内存回收机制，ImagePacker对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5949 5950**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5951 5952**参数：** 5953 5954| 参数名 | 类型 | 必填 | 说明 | 5955| -------- | -------------------- | ---- | ------------------------------ | 5956| callback | AsyncCallback\<void> | 是 | 回调函数，当释放图片打包实例成功，err为undefined，否则为错误对象。 | 5957 5958**示例：** 5959 5960```ts 5961import { BusinessError } from '@kit.BasicServicesKit'; 5962 5963const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5964imagePackerApi.release((err: BusinessError)=>{ 5965 if (err) { 5966 console.error(`Failed to release image packaging.code ${err.code},message is ${err.message}`); 5967 } else { 5968 console.info('Succeeded in releasing image packaging.'); 5969 } 5970}) 5971``` 5972 5973### release 5974 5975release(): Promise\<void> 5976 5977释放图片打包实例，使用Promise形式返回释放结果。 5978 5979ArkTS有内存回收机制，ImagePacker对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5980 5981**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5982 5983**返回值：** 5984 5985| 类型 | 说明 | 5986| -------------- | ------------------------------------------------------ | 5987| Promise\<void> | Promise对象。无返回结果的Promise对象。| 5988 5989**示例：** 5990 5991```ts 5992import { BusinessError } from '@kit.BasicServicesKit'; 5993 5994const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5995imagePackerApi.release().then(() => { 5996 console.info('Succeeded in releasing image packaging.'); 5997}).catch((error: BusinessError) => { 5998 console.error(`Failed to release image packaging.code ${error.code},message is ${error.message}`); 5999}) 6000``` 6001 6002### packToFile<sup>11+</sup> 6003 6004packToFile(source: ImageSource, fd: number, options: PackingOption, callback: AsyncCallback\<void>): void 6005 6006指定打包参数，将ImageSource图片源编码后直接打包进文件。使用callback形式返回结果。 6007 6008**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6009 6010**参数：** 6011 6012| 参数名 | 类型 | 必填 | 说明 | 6013| -------- | ------------------------------- | ---- | ------------------------------ | 6014| source | [ImageSource](#imagesource) | 是 | 打包的图片源。 | 6015| fd | number | 是 | 文件描述符。 | 6016| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 6017| callback | AsyncCallback\<void> | 是 | 回调函数，当打包进文件成功，err为undefined，否则为错误对象。 | 6018 6019**错误码：** 6020 6021以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6022 6023| 错误码ID | 错误信息 | 6024| ------- | --------------------------------------------| 6025| 62980096| The Operation failed. | 6026| 62980101 | The image data is abnormal. | 6027| 62980106 | The image is too large. | 6028| 62980113 | Unknown image format. | 6029| 62980115 | If the parameter is invalid. | 6030| 62980119 | If encoder occur error during encoding. | 6031| 62980120 | Add pixelmap out of range. | 6032| 62980172 | Failed to encode icc. | 6033| 62980252 | Failed to create surface. | 6034 6035**示例：** 6036 6037```ts 6038import { BusinessError } from '@kit.BasicServicesKit'; 6039import { fileIo as fs } from '@kit.CoreFileKit'; 6040 6041const context: Context = getContext(this); 6042//此处'test.png'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6043const path: string = context.filesDir + "/test.png"; 6044const imageSourceApi: image.ImageSource = image.createImageSource(path); 6045let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6046const filePath: string = context.filesDir + "/image_source.jpg"; 6047let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6048const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6049imagePackerApi.packToFile(imageSourceApi, file.fd, packOpts, (err: BusinessError) => { 6050 if (err) { 6051 console.error(`Failed to pack the image to file.code ${err.code},message is ${err.message}`); 6052 } else { 6053 console.info('Succeeded in packing the image to file.'); 6054 } 6055}) 6056``` 6057 6058### packToFile<sup>11+</sup> 6059 6060packToFile (source: ImageSource, fd: number, options: PackingOption): Promise\<void> 6061 6062指定打包参数，将ImageSource图片源编码后直接打包进文件。使用Promise形式返回结果。 6063 6064**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6065 6066**参数：** 6067 6068| 参数名 | 类型 | 必填 | 说明 | 6069| ------ | ------------------------------- | ---- | -------------- | 6070| source | [ImageSource](#imagesource) | 是 | 打包的图片源。 | 6071| fd | number | 是 | 文件描述符。 | 6072| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 6073 6074**返回值：** 6075 6076| 类型 | 说明 | 6077| -------------- | --------------------------------- | 6078| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6079 6080**错误码：** 6081 6082以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6083 6084| 错误码ID | 错误信息 | 6085| ------- | --------------------------------------------| 6086| 62980096| The Operation failed. | 6087| 62980101 | The image data is abnormal. | 6088| 62980106 | The image is too large. | 6089| 62980113 | Unknown image format. | 6090| 62980115 | If the parameter is invalid. | 6091| 62980119 | If encoder occur error during encoding. | 6092| 62980120 | Add pixelmap out of range. | 6093| 62980172 | Failed to encode icc. | 6094| 62980252 | Failed to create surface. | 6095 6096**示例：** 6097 6098```ts 6099import { BusinessError } from '@kit.BasicServicesKit'; 6100import { fileIo as fs } from '@kit.CoreFileKit'; 6101 6102const context: Context = getContext(this); 6103//此处'test.png'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6104const path: string = context.filesDir + "/test.png"; 6105const imageSourceApi: image.ImageSource = image.createImageSource(path); 6106let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6107const filePath: string = context.filesDir + "/image_source.jpg"; 6108let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6109const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6110imagePackerApi.packToFile(imageSourceApi, file.fd, packOpts).then(() => { 6111 console.info('Succeeded in packing the image to file.'); 6112}).catch((error: BusinessError) => { 6113 console.error(`Failed to pack the image to file.code ${error.code},message is ${error.message}`); 6114}) 6115``` 6116 6117### packToFile<sup>11+</sup> 6118 6119packToFile (source: PixelMap, fd: number, options: PackingOption, callback: AsyncCallback\<void>): void; 6120 6121指定打包参数，将PixelMap图片源编码后直接打包进文件。使用callback形式返回结果。 6122 6123> **注意：** 6124> 接口如果返回62980115错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6125 6126**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6127 6128**参数：** 6129 6130| 参数名 | 类型 | 必填 | 说明 | 6131| -------- | ------------------------------- | ---- | ------------------------------ | 6132| source | [PixelMap](#pixelmap7) | 是 | 打包的PixelMap资源。 | 6133| fd | number | 是 | 文件描述符。 | 6134| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 6135| callback | AsyncCallback\<void> | 是 | 回调函数，当打包图片进文件成功，err为undefined，否则为错误对象。 | 6136 6137**错误码：** 6138 6139以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6140 6141| 错误码ID | 错误信息 | 6142| ------- | --------------------------------------------| 6143| 62980096| The Operation failed. | 6144| 62980101 | The image data is abnormal. | 6145| 62980106 | The image is too large. | 6146| 62980113 | Unknown image format. | 6147| 62980115 | If the parameter is invalid. | 6148| 62980119 | If encoder occur error during encoding. | 6149| 62980120 | Add pixelmap out of range. | 6150| 62980172 | Failed to encode icc. | 6151| 62980252 | Failed to create surface. | 6152 6153**示例：** 6154 6155```ts 6156import { BusinessError } from '@kit.BasicServicesKit'; 6157import { fileIo as fs } from '@kit.CoreFileKit'; 6158 6159const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6160let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6161const context: Context = getContext(this); 6162const path: string = context.filesDir + "/pixel_map.jpg"; 6163image.createPixelMap(color, opts).then((pixelmap: image.PixelMap) => { 6164 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6165 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6166 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6167 imagePackerApi.packToFile(pixelmap, file.fd, packOpts, (err: BusinessError) => { 6168 if (err) { 6169 console.error(`Failed to pack the image to file.code ${err.code},message is ${err.message}`); 6170 } else { 6171 console.info('Succeeded in packing the image to file.'); 6172 } 6173 }) 6174}) 6175``` 6176 6177### packToFile<sup>11+</sup> 6178 6179packToFile (source: PixelMap, fd: number, options: PackingOption): Promise\<void> 6180 6181指定打包参数，将PixelMap图片源编码后直接打包进文件。使用Promise形式返回结果。 6182 6183> **注意：** 6184> 接口如果返回62980115错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6185 6186**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6187 6188**参数：** 6189 6190| 参数名 | 类型 | 必填 | 说明 | 6191| ------ | ------------------------------- | ---- | -------------------- | 6192| source | [PixelMap](#pixelmap7) | 是 | 打包的PixelMap资源。 | 6193| fd | number | 是 | 文件描述符。 | 6194| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 6195 6196**返回值：** 6197 6198| 类型 | 说明 | 6199| -------------- | --------------------------------- | 6200| Promise\<void> | Promise对象。无返回结果的Promise对象。| 6201 6202**错误码：** 6203 6204以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6205 6206| 错误码ID | 错误信息 | 6207| ------- | --------------------------------------------| 6208| 62980096| The Operation failed. | 6209| 62980101 | The image data is abnormal. | 6210| 62980106 | The image is too large. | 6211| 62980113 | Unknown image format. | 6212| 62980115 | If the parameter is invalid. | 6213| 62980119 | If encoder occur error during encoding. | 6214| 62980120 | Add pixelmap out of range. | 6215| 62980172 | Failed to encode icc. | 6216| 62980252 | Failed to create surface. | 6217 6218**示例：** 6219 6220```ts 6221import { BusinessError } from '@kit.BasicServicesKit'; 6222import { fileIo as fs } from '@kit.CoreFileKit'; 6223 6224const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6225let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6226const context: Context = getContext(this); 6227const path: string = context.filesDir + "/pixel_map.jpg"; 6228image.createPixelMap(color, opts).then((pixelmap: image.PixelMap) => { 6229 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6230 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6231 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6232 imagePackerApi.packToFile(pixelmap, file.fd, packOpts) 6233 .then(() => { 6234 console.info('Succeeded in packing the image to file.'); 6235 }).catch((error: BusinessError) => { 6236 console.error(`Failed to pack the image to file.code ${error.code},message is ${error.message}`); 6237 }) 6238}) 6239``` 6240 6241### packToFile<sup>13+</sup> 6242 6243packToFile(picture: Picture, fd: number, options: PackingOption): Promise\<void> 6244 6245指定打包参数，将Picture图片源编码后直接打包进文件。使用Promise形式返回结果。 6246 6247**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6248 6249**参数：** 6250 6251| 参数名 | 类型 | 必填 | 说明 | 6252| ------- | ---------------------------- | ---- | -------------------- | 6253| picture | [Picture](#picture13) | 是 | 打包的Picture资源。 | 6254| fd | number | 是 | 文件描述符。 | 6255| options | [PackingOption](#packingoption) | 是 | 设置打包参数。 | 6256 6257**返回值：** 6258 6259| 类型 | 说明 | 6260| -------------- | ------------------------- | 6261| Promise\<void> | 无返回结果的Promise对象。 | 6262 6263**错误码：** 6264 6265以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6266 6267| 错误码ID | 错误信息 | 6268| -------- | ------------------------------------------------------------ | 6269| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6270| 7800301 | Encode failed. | 6271 6272**示例：** 6273 6274```ts 6275import { BusinessError } from '@kit.BasicServicesKit'; 6276import { image } from '@kit.ImageKit'; 6277import { fileIo as fs } from '@kit.CoreFileKit'; 6278 6279async function PackToFile() { 6280 const context = getContext(); 6281 const resourceMgr = context.resourceManager; 6282 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 6283 let ops: image.SourceOptions = { 6284 sourceDensity: 98, 6285 } 6286 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6287 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6288 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6289 6290 let funcName = "PackToFile"; 6291 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6292 if (imagePackerApi != null) { 6293 const context: Context = getContext(); 6294 const filePath: string = context.filesDir + "/test.jpg"; 6295 let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6296 let packOpts: image.PackingOption = { 6297 format: "image/jpeg", 6298 quality: 98, 6299 bufferSize: 10, 6300 desiredDynamicRange: image.PackingDynamicRange.AUTO, 6301 needsPackProperties: true}; 6302 await imagePackerApi.packToFile(pictureObj, file.fd, packOpts).then(() => { 6303 console.info(funcName, 'Succeeded in packing the image to file.'); 6304 }).catch((error: BusinessError) => { 6305 console.error(funcName, 'Failed to pack the image to file.code ${error.code},message is ${error.message}'); 6306 }); 6307 } 6308} 6309``` 6310 6311## image.createAuxiliaryPicture<sup>13+</sup> 6312 6313createAuxiliaryPicture(buffer: ArrayBuffer, size: Size, type: AuxiliaryPictureType): AuxiliaryPicture 6314 6315通过ArrayBuffer图片数据、辅助图尺寸、辅助图类型创建AuxiliaryPicture实例。 6316 6317**系统能力：** SystemCapability.Multimedia.Image.Core 6318 6319**参数：** 6320 6321| 参数名 | 类型 | 必填 | 说明 | 6322| ------ | ----------------------------------------------- | ---- | ---------------------------- | 6323| buffer | ArrayBuffer | 是 | 以buffer形式存放的图像数据。 | 6324| size | [Size](#size) | 是 | 辅助图的尺寸。 | 6325| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 6326 6327**返回值：** 6328 6329| 类型 | 说明 | 6330| --------------------------------------- | ------------------------------------------ | 6331| [AuxiliaryPicture](#auxiliarypicture13) | 如果操作成功，则返回AuxiliaryPicture实例。 | 6332 6333**错误码：** 6334 6335以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6336 6337| 错误码ID | 错误信息 | 6338| -------- | ------------------------------------------------------------ | 6339| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6340 6341**示例：** 6342 6343```ts 6344import { image } from '@kit.ImageKit'; 6345 6346async function CreateAuxiliaryPicture() { 6347 let funcName = "CreateAuxiliaryPicture"; 6348 const context = getContext(); 6349 const resourceMgr = context.resourceManager; 6350 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 6351 let auxBuffer: ArrayBuffer = rawFile.buffer as ArrayBuffer; 6352 let auxSize: Size = { 6353 height: 180, 6354 width: 240 6355 }; 6356 let auxType: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 6357 let auxPictureObj: image.AuxiliaryPicture | null = image.createAuxiliaryPicture(auxBuffer, auxSize, auxType); 6358 if(auxPictureObj != null) { 6359 let type: image.AuxiliaryPictureType = auxPictureObj.getType(); 6360 console.info(funcName, 'CreateAuxiliaryPicture succeeded this.Aux_picture.type.' + JSON.stringify(type)); 6361 } else { 6362 console.error(funcName, 'CreateAuxiliaryPicture failed'); 6363 } 6364} 6365``` 6366 6367## AuxiliaryPicture<sup>13+</sup> 6368 6369辅助图一般用于辅助主图进行特殊信息的展示，使图像包含更丰富的信息。辅助图图像类，用于读取或写入图像的辅助图数据以及获取图像的辅助图信息。在调用AuxiliaryPicture的方法前，需要先通过[createAuxiliaryPicture](#imagecreateauxiliarypicture13)创建一个AuxiliaryPicture实例。 6370 6371### 属性 6372 6373**系统能力：** SystemCapability.Multimedia.Image.Core 6374 6375### writePixelsFromBuffer<sup>13+</sup> 6376 6377writePixelsFromBuffer(data: ArrayBuffer): Promise\<void> 6378 6379读取ArrayBuffer中的辅助图片数据，并将数据写入AuxiliaryPicture对象，使用Promise形式返回。 6380 6381**系统能力：** SystemCapability.Multimedia.Image.Core 6382 6383**参数：** 6384 6385| 参数名 | 类型 | 必填 | 说明 | 6386| ------ | ----------- | ---- | ---------------- | 6387| data | ArrayBuffer | 是 | 辅助图像素数据。 | 6388 6389**返回值：** 6390 6391| 类型 | 说明 | 6392| -------------- | -------------------------------------- | 6393| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6394 6395**错误码：** 6396 6397以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6398 6399| 错误码ID | 错误信息 | 6400| -------- | ------------------------------------------------------------ | 6401| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6402| 7600301 | Memory alloc failed. | 6403| 7600302 | Memory copy failed. | 6404 6405**示例:** 6406 6407```ts 6408import { image } from '@kit.ImageKit'; 6409 6410async function WritePixelsFromBuffer() { 6411 const context = getContext(); 6412 const resourceMgr = context.resourceManager; 6413 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 6414 let ops: image.SourceOptions = { 6415 sourceDensity: 98, 6416 } 6417 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6418 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6419 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6420 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP); 6421 if(auxPictureObj != null) { 6422 let auxBuffer: ArrayBuffer = await auxPictureObj.readPixelsToBuffer(); 6423 await auxPictureObj.writePixelsFromBuffer(auxBuffer); 6424 console.info('Write pixels from buffer success.'); 6425 } else { 6426 console.error('AuxPictureObj is null.'); 6427 } 6428} 6429``` 6430 6431### readPixelsToBuffer<sup>13+</sup> 6432 6433readPixelsToBuffer(): Promise\<ArrayBuffer> 6434 6435读取图像像素映射数据并将数据写入ArrayBuffer，使用Promise形式返回。 6436 6437**系统能力：** SystemCapability.Multimedia.Image.Core 6438 6439**返回值：** 6440 6441| 类型 | 说明 | 6442| --------------------- | --------------------------------- | 6443| Promise\<ArrayBuffer> | Promise对象。返回辅助图像素数据。 | 6444 6445**错误码：** 6446 6447以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6448 6449| 错误码ID | 错误信息 | 6450| -------- | -------------------- | 6451| 7600301 | Memory alloc failed. | 6452| 7600302 | Memory copy failed. | 6453 6454**示例：** 6455 6456```ts 6457import { BusinessError } from '@kit.BasicServicesKit'; 6458import { image } from '@kit.ImageKit'; 6459 6460async function ReadPixelsToBuffer() { 6461 const context = getContext(); 6462 const resourceMgr = context.resourceManager; 6463 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 6464 let ops: image.SourceOptions = { 6465 sourceDensity: 98, 6466 } 6467 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6468 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6469 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6470 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP); 6471 if(auxPictureObj != null) { 6472 await auxPictureObj.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => { 6473 console.info('Read pixels to buffer success.' ); 6474 }).catch((error: BusinessError) => { 6475 console.error('Read pixels to buffer failed error.code: ' + JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 6476 }); 6477 } else { 6478 console.error('AuxPictureObj is null.'); 6479 } 6480} 6481``` 6482 6483### getType<sup>13+</sup> 6484 6485getType(): AuxiliaryPictureType 6486 6487获取辅助图的类型。 6488 6489**系统能力：** SystemCapability.Multimedia.Image.Core 6490 6491**返回值：** 6492 6493| 类型 | 说明 | 6494| ----------------------------------------------- | ---------------------------- | 6495| [AuxiliaryPictureType](#auxiliarypicturetype13) | 操作成功，返回辅助图的类型。 | 6496 6497**示例：** 6498 6499```ts 6500import { image } from '@kit.ImageKit'; 6501 6502async function GetAuxiliaryPictureType() { 6503 if (auxPictureObj != null) { 6504 let type: image.AuxiliaryPictureType = auxPictureObj.getType(); 6505 console.info('Success get auxiliary picture type ' + JSON.stringify(type)); 6506 } else { 6507 console.info('Failed get auxiliary picture type '); 6508 } 6509} 6510``` 6511 6512### setMetadata<sup>13+</sup> 6513 6514setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void> 6515 6516设置辅助图元数据。 6517 6518**系统能力：** SystemCapability.Multimedia.Image.Core 6519 6520**参数：** 6521 6522| 参数名 | 类型 | 必填 | 说明 | 6523| ------------ | ------------------------------- | ---- | ------------------------------------ | 6524| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据的类型，用于设置对应的元数据。 | 6525| metadata | [Metadata](#metadata13) | 是 | 元数据对象。 | 6526 6527**返回值：** 6528 6529| 类型 | 说明 | 6530| -------------- | -------------------------------------- | 6531| Promise\<void> | Promise对象，无返回结果的Promise对象。 | 6532 6533**错误码：** 6534 6535以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6536 6537| 错误码ID | 错误信息 | 6538| -------- | ------------------------------------------------------------ | 6539| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6540| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 6541 6542**示例：** 6543 6544```ts 6545import { BusinessError } from '@kit.BasicServicesKit'; 6546import { image } from '@kit.ImageKit'; 6547 6548async function SetAuxPictureObjMetadata() { 6549 const exifContext = getContext(); 6550 const exifResourceMgr = exifContext.resourceManager; 6551 const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");//图片包含exif metadata。 6552 let exifOps: image.SourceOptions = { 6553 sourceDensity: 98, 6554 } 6555 let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps); 6556 let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap(); 6557 let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap); 6558 if (exifPictureObj != null) { 6559 console.info('Create picture succeeded'); 6560 } else { 6561 console.info('Create picture failed'); 6562 } 6563 6564 if (auxPictureObj != null) { 6565 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6566 let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType); 6567 auxPictureObj.setMetadata(metadataType, exifMetaData).then(() => { 6568 console.info('Set metadata success'); 6569 }).catch((error: BusinessError) => { 6570 console.error('Set metadata failed.error.code: ${error.code}, error.message: ${error.message}'); 6571 }); 6572 } else { 6573 console.info('AuxPictureObjMetaData is null'); 6574 } 6575} 6576``` 6577 6578### getMetadata<sup>13+</sup> 6579 6580getMetadata(metadataType: MetadataType): Promise\<Metadata> 6581 6582从辅助图中获取元数据。 6583 6584**系统能力：** SystemCapability.Multimedia.Image.Core 6585 6586**参数：** 6587 6588| 参数名 | 类型 | 必填 | 说明 | 6589| ------------ | ------------------------------- | ---- | -------------------------------------- | 6590| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型，用于获取对应类型的元数据。 | 6591 6592**返回值：** 6593 6594| 类型 | 说明 | 6595| -------------------------------- | ---------------- | 6596| Promise<[Metadata](#metadata13)> | 返回元数据对象。 | 6597 6598**错误码：** 6599 6600以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6601 6602| 错误码ID | 错误信息 | 6603| -------- | ------------------------------------------------------------ | 6604| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6605| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 6606 6607**示例：** 6608 6609```ts 6610import { image } from '@kit.ImageKit'; 6611 6612async function GetAuxPictureObjMetadata() { 6613 if (auxPictureObj != null) { 6614 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6615 let auxPictureObjMetaData: image.Metadata | null = await auxPictureObj.getMetadata(metadataType); 6616 if (auxPictureObjMetaData != null) { 6617 console.info('Get auxpictureobj Metadata success' ); 6618 } else { 6619 console.info('Get auxpictureobj Metadata failed'); 6620 } 6621 } else { 6622 console.info('Get auxpictureobj is null.'); 6623 } 6624} 6625``` 6626 6627### getAuxiliaryPictureinfo<sup>13+</sup> 6628 6629getAuxiliaryPictureInfo(): AuxiliaryPictureInfo 6630 6631获取有关此辅助图的图像信息。 6632 6633**系统能力：** SystemCapability.Multimedia.Image.Core 6634 6635**返回值：** 6636 6637| 类型 | 说明 | 6638| ----------------------------------------------- | --------------------------------- | 6639| [AuxiliaryPictureInfo](#auxiliarypictureinfo13) | Promise对象，返回辅助图图像信息。 | 6640 6641**示例：** 6642 6643```ts 6644import { image } from '@kit.ImageKit'; 6645 6646async function GetAuxiliaryPictureInfo() { 6647 if(auxPictureObj != null) { 6648 let auxinfo: image.AuxiliaryPictureInfo = auxPictureObj.getAuxiliaryPictureInfo(); 6649 console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType + 6650 ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width + 6651 ' rowStride: ' + auxinfo.rowStride + ' pixelFormat: ' + auxinfo.pixelFormat + 6652 ' colorSpace: ' + auxinfo.colorSpace); 6653 } else { 6654 console.info('Get auxiliary picture information failed'); 6655 } 6656} 6657``` 6658 6659### setAuxiliaryPictureinfo<sup>13+</sup> 6660 6661setAuxiliaryPictureInfo(info: AuxiliaryPictureInfo): void 6662 6663设置辅助图的图像信息。 6664 6665**系统能力：** SystemCapability.Multimedia.Image.Core 6666 6667**参数：** 6668 6669| 参数名 | 类型 | 必填 | 说明 | 6670| ------ | ----------------------------------------------- | ---- | ------------------ | 6671| info | [AuxiliaryPictureInfo](#auxiliarypictureinfo13) | 是 | 辅助图的图像信息。 | 6672 6673**错误码：** 6674 6675以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6676 6677| 错误码ID | 错误信息 | 6678| -------- | :----------------------------------------------------------- | 6679| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6680 6681**示例：** 6682 6683```ts 6684import { colorSpaceManager } from '@kit.ArkGraphics2D'; 6685import { image } from '@kit.ImageKit'; 6686 6687async function SetAuxiliaryPictureInfo() { 6688 if(auxPictureObj != null) { 6689 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 6690 let info: image.AuxiliaryPictureInfo = { 6691 auxiliaryPictureType: image.AuxiliaryPictureType.GAINMAP, 6692 size: {height: 100, width: 200}, 6693 pixelFormat: image.PixelMapFormat.RGBA_8888, 6694 rowStride: 0, 6695 colorSpace: colorSpaceManager.create(colorSpaceName), 6696 }; 6697 auxPictureObj.setAuxiliaryPictureInfo(info); 6698 } 6699} 6700``` 6701 6702### release<sup>13+</sup> 6703 6704release():void 6705 6706释放辅助图对象，无返回值。 6707 6708**系统能力：** SystemCapability.Multimedia.Image.Core 6709 6710**示例：** 6711 6712```ts 6713import { image } from '@kit.ImageKit'; 6714 6715async function Release() { 6716 let funcName = "Release"; 6717 if (auxPictureObj != null) { 6718 auxPictureObj.release(); 6719 if (auxPictureObj.getType() == null) { 6720 console.info(funcName, 'Success !'); 6721 } else { 6722 console.info(funcName, 'Failed !'); 6723 } 6724 } else { 6725 console.info('PictureObj is null'); 6726 } 6727} 6728``` 6729 6730## Metadata<sup>13+</sup> 6731 6732图像元数据类，用于存储图像的元数据。目前支持的元数据类型可参考[MetadataType](#metadatatype13)。 6733 6734### 属性 6735 6736**系统能力：** SystemCapability.Multimedia.Image.Core 6737 6738### getProperties<sup>13+</sup> 6739 6740getProperties(key: Array\<string>): Promise\<Record\<string, string | null>> 6741 6742获取图像中属性的值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 6743 6744**系统能力：** SystemCapability.Multimedia.Image.Core 6745 6746**参数：** 6747 6748| 参数名 | 类型 | 必填 | 说明 | 6749| ------ | -------------- | ---- | ------------------------ | 6750| key | Array\<string> | 是 | 要获取其值的属性的名称。 | 6751 6752**返回值：** 6753 6754| 类型 | 说明 | 6755| ---------------------------------------- | ------------------------------------------------------------ | 6756| Promise\<Record<string, string \| null>> | Promise对象，返回元数据要获取的属性的值，如获取失败则返回错误码。 | 6757 6758**错误码：** 6759 6760以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6761 6762| 错误码ID | 错误信息 | 6763| -------- | ------------------------------------------------------------ | 6764| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 6765| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 6766 6767**示例：** 6768 6769```ts 6770import { BusinessError } from '@kit.BasicServicesKit'; 6771import { image } from '@kit.ImageKit'; 6772 6773async function GetProperties() { 6774 const context = getContext(); 6775 const resourceMgr = context.resourceManager; 6776 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 6777 let ops: image.SourceOptions = { 6778 sourceDensity: 98, 6779 } 6780 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6781 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6782 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6783 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6784 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 6785 if (metaData != null) { 6786 await metaData.getProperties(["ImageWidth", "ImageLength"]).then((data2) => { 6787 console.info('Get properties ',JSON.stringify(data2)); 6788 }).catch((error: BusinessError) => { 6789 console.info('Get properties failed error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 6790 }); 6791 } else { 6792 console.info('Metadata is null.'); 6793 } 6794} 6795``` 6796 6797### setProperties<sup>13+</sup> 6798 6799setProperties(records: Record\<string, string | null>): Promise\<void> 6800 6801批量设置图片元数据中的指定属性的值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 6802 6803**系统能力：** SystemCapability.Multimedia.Image.Core 6804 6805**参数：** 6806 6807| 参数名 | 类型 | 必填 | 说明 | 6808| ------- | ------------------------------ | ---- | ------------------------ | 6809| records | Record<string, string \| null> | 是 | 要修改的属性和值的数组。 | 6810 6811**返回值：** 6812 6813| 类型 | 说明 | 6814| -------------- | ------------------------------------- | 6815| Promise\<void> | Promise对象，如获取失败则返回错误码。 | 6816 6817**错误码：** 6818 6819以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6820 6821| 错误码ID | 错误信息 | 6822| -------- | ------------------------------------------------------------ | 6823| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 6824| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 6825 6826**示例：** 6827 6828```ts 6829import { BusinessError } from '@kit.BasicServicesKit'; 6830import { image } from '@kit.ImageKit'; 6831 6832async function SetProperties() { 6833 const context = getContext(); 6834 const resourceMgr = context.resourceManager; 6835 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 6836 let ops: image.SourceOptions = { 6837 sourceDensity: 98, 6838 } 6839 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6840 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6841 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6842 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6843 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 6844 if (metaData != null) { 6845 let setkey: Record<string, string | null> = { 6846 "ImageWidth": "200", 6847 "ImageLength": "300" 6848 }; 6849 await metaData.setProperties(setkey).then(async () => { 6850 console.info('Set auxpictureobj properties success.'); 6851 }).catch((error: BusinessError) => { 6852 console.error('Failed to set metadata Properties. code is ${error.code}, message is ${error.message}'); 6853 }) 6854 } else { 6855 console.info('AuxPictureObj metadata is null. '); 6856 } 6857} 6858``` 6859 6860### getAllProperties<sup>13+</sup> 6861 6862getAllProperties(): Promise\<Record<string, string | null>> 6863 6864获取图片中所有元数据的属性和值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 6865 6866**系统能力：** SystemCapability.Multimedia.Image.Core 6867 6868**返回值：** 6869 6870| 类型 | 说明 | 6871| ---------------------------------------- | ------------------------------------------- | 6872| Promise\<Record<string, string \| null>> | Promise对象，返回元数据拥有的所有属性的值。 | 6873 6874**示例：** 6875 6876```ts 6877import { BusinessError } from '@kit.BasicServicesKit'; 6878import { image } from '@kit.ImageKit'; 6879 6880async function GetAllProperties() { 6881 const context = getContext(); 6882 const resourceMgr = context.resourceManager; 6883 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 6884 let ops: image.SourceOptions = { 6885 sourceDensity: 98, 6886 } 6887 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6888 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6889 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6890 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6891 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 6892 if (metaData != null) { 6893 await metaData.getAllProperties().then((data2) => { 6894 const count = Object.keys(data2).length; 6895 console.info('Metadata have ', count, ' properties'); 6896 console.info('Get metadata all properties: ', JSON.stringify(data2)); 6897 }).catch((error: BusinessError) => { 6898 console.error('Get metadata all properties failed error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 6899 }); 6900 } else { 6901 console.info('Metadata is null.'); 6902 } 6903} 6904``` 6905 6906### clone<sup>13+</sup> 6907 6908clone(): Promise\<Metadata> 6909 6910对元数据进行克隆，用Promise形式返回结果。 6911 6912**系统能力：** SystemCapability.Multimedia.Image.Core 6913 6914**返回值：** 6915 6916| 类型 | 说明 | 6917| --------------------------------- | --------------------------------- | 6918| Promise\<[Metadata](#metadata13)> | Promise对象，成功返回元数据实例。 | 6919 6920**错误码：** 6921 6922以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6923 6924| 错误码ID | 错误信息 | 6925| -------- | -------------------- | 6926| 7600301 | Memory alloc failed. | 6927| 7600302 | Memory copy failed. | 6928 6929**示例：** 6930 6931```ts 6932import { BusinessError } from '@kit.BasicServicesKit'; 6933import { image } from '@kit.ImageKit'; 6934 6935async function clone() { 6936 const context = getContext(); 6937 const resourceMgr = context.resourceManager; 6938 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 6939 let ops: image.SourceOptions = { 6940 sourceDensity: 98, 6941 } 6942 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6943 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6944 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6945 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6946 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 6947 if (metaData != null) { 6948 let new_metadata: image.Metadata = await metaData.clone(); 6949 new_metadata.getProperties(["ImageWidth"]).then((data1) => { 6950 console.info('Clone new_metadata and get Properties.', JSON.stringify(data1)); 6951 }).catch((err: BusinessError) => { 6952 console.error('Clone new_metadata failed.', JSON.stringify(err)); 6953 }); 6954 } else { 6955 console.info('Metadata is null.'); 6956 } 6957} 6958``` 6959 6960## image.createImageReceiver<sup>11+</sup> 6961 6962createImageReceiver(size: Size, format: ImageFormat, capacity: number): ImageReceiver 6963 6964通过图片大小、图片格式、容量创建ImageReceiver实例。 6965 6966**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 6967 6968**参数：** 6969 6970| 参数名 | 类型 | 必填 | 说明 | 6971| -------- | ------ | ---- | ---------------------- | 6972| size | [Size](#size) | 是 | 图像的默认大小。 | 6973| format | [ImageFormat](#imageformat9) | 是 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机）。 | 6974| capacity | number | 是 | 同时访问的最大图像数。 | 6975 6976**返回值：** 6977 6978| 类型 | 说明 | 6979| -------------------------------- | --------------------------------------- | 6980| [ImageReceiver](#imagereceiver9) | 如果操作成功，则返回ImageReceiver实例。 | 6981 6982**错误码：** 6983 6984以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6985 6986| 错误码ID | 错误信息 | 6987| ------- | --------------------------------------------| 6988| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 6989 6990**示例：** 6991 6992```ts 6993let size: image.Size = { 6994 height: 8192, 6995 width: 8 6996} 6997let receiver: image.ImageReceiver = image.createImageReceiver(size, image.ImageFormat.JPEG, 8); 6998``` 6999 7000## image.createImageReceiver<sup>(deprecated)</sup> 7001 7002createImageReceiver(width: number, height: number, format: number, capacity: number): ImageReceiver 7003 7004通过宽、高、图片格式、容量创建ImageReceiver实例。 7005 7006> **说明：** 7007> 7008> 从API version 11开始不再维护，建议使用[createImageReceiver](#imagecreateimagereceiver11)代替。 7009 7010**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7011 7012**参数：** 7013 7014| 参数名 | 类型 | 必填 | 说明 | 7015| -------- | ------ | ---- | ---------------------- | 7016| width | number | 是 | 图像的默认宽度。 | 7017| height | number | 是 | 图像的默认高度。 | 7018| format | number | 是 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机）。 | 7019| capacity | number | 是 | 同时访问的最大图像数。 | 7020 7021**返回值：** 7022 7023| 类型 | 说明 | 7024| -------------------------------- | --------------------------------------- | 7025| [ImageReceiver](#imagereceiver9) | 如果操作成功，则返回ImageReceiver实例。 | 7026 7027**示例：** 7028 7029```ts 7030let receiver: image.ImageReceiver = image.createImageReceiver(8192, 8, image.ImageFormat.JPEG, 8); 7031``` 7032 7033## ImageReceiver<sup>9+</sup> 7034 7035图像接收类，用于获取组件surface id，接收最新的图片和读取下一张图片，以及释放ImageReceiver实例。 7036 7037在调用以下方法前需要先创建ImageReceiver实例。 7038 7039### 属性 7040 7041**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7042 7043| 名称 | 类型 | 可读 | 可写 | 说明 | 7044| -------- | ---------------------------- | ---- | ---- | ------------------ | 7045| size | [Size](#size) | 是 | 否 | 图片大小。 | 7046| capacity | number | 是 | 否 | 同时访问的图像数。 | 7047| format | [ImageFormat](#imageformat9) | 是 | 否 | 图像格式。 | 7048 7049### getReceivingSurfaceId<sup>9+</sup> 7050 7051getReceivingSurfaceId(callback: AsyncCallback\<string>): void 7052 7053用于获取一个surface id供Camera或其他组件使用。使用callback返回结果。 7054 7055**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7056 7057**参数：** 7058 7059| 参数名 | 类型 | 必填 | 说明 | 7060| -------- | ---------------------- | ---- | -------------------------- | 7061| callback | AsyncCallback\<string> | 是 | 回调函数，当获取surface id成功，err为undefined，data为获取到的surface id；否则为错误对象。 | 7062 7063**示例:** 7064 7065```ts 7066import { BusinessError } from '@kit.BasicServicesKit'; 7067 7068receiver.getReceivingSurfaceId((err: BusinessError, id: string) => { 7069 if (err) { 7070 console.error(`Failed to get the ReceivingSurfaceId.code ${err.code},message is ${err.message}`); 7071 } else { 7072 console.info('Succeeded in getting the ReceivingSurfaceId.'); 7073 } 7074}); 7075``` 7076 7077### getReceivingSurfaceId<sup>9+</sup> 7078 7079getReceivingSurfaceId(): Promise\<string> 7080 7081用于获取一个surface id供Camera或其他组件使用。使用promise返回结果。 7082 7083**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7084 7085**返回值：** 7086 7087| 类型 | 说明 | 7088| ---------------- | -------------------- | 7089| Promise\<string> | Promise对象，返回surface id。 | 7090 7091**示例：** 7092 7093```ts 7094import { BusinessError } from '@kit.BasicServicesKit'; 7095 7096receiver.getReceivingSurfaceId().then((id: string) => { 7097 console.info('Succeeded in getting the ReceivingSurfaceId.'); 7098}).catch((error: BusinessError) => { 7099 console.error(`Failed to get the ReceivingSurfaceId.code ${error.code},message is ${error.message}`); 7100}) 7101``` 7102 7103### readLatestImage<sup>9+</sup> 7104 7105readLatestImage(callback: AsyncCallback\<Image>): void 7106 7107从ImageReceiver读取最新的图片，并使用callback返回结果。 7108 7109**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7110 7111**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7112 7113**参数：** 7114 7115| 参数名 | 类型 | 必填 | 说明 | 7116| -------- | ------------------------------- | ---- | ------------------------ | 7117| callback | AsyncCallback<[Image](#image9)> | 是 | 回调函数，当读取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 7118 7119**示例：** 7120 7121```ts 7122import { BusinessError } from '@kit.BasicServicesKit'; 7123 7124receiver.readLatestImage((err: BusinessError, img: image.Image) => { 7125 if (err) { 7126 console.error(`Failed to read the latest Image.code ${err.code},message is ${err.message}`); 7127 } else { 7128 console.info('Succeeded in reading the latest Image.'); 7129 } 7130}); 7131``` 7132 7133### readLatestImage<sup>9+</sup> 7134 7135readLatestImage(): Promise\<Image> 7136 7137从ImageReceiver读取最新的图片，并使用promise返回结果。 7138 7139**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7140 7141**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7142 7143**返回值：** 7144 7145| 类型 | 说明 | 7146| ------------------------- | ------------------ | 7147| Promise<[Image](#image9)> | Promise对象，返回最新图片。 | 7148 7149**示例：** 7150 7151```ts 7152import { BusinessError } from '@kit.BasicServicesKit'; 7153 7154receiver.readLatestImage().then((img: image.Image) => { 7155 console.info('Succeeded in reading the latest Image.'); 7156}).catch((error: BusinessError) => { 7157 console.error(`Failed to read the latest Image.code ${error.code},message is ${error.message}`); 7158}) 7159``` 7160 7161### readNextImage<sup>9+</sup> 7162 7163readNextImage(callback: AsyncCallback\<Image>): void 7164 7165从ImageReceiver读取下一张图片，并使用callback返回结果。 7166 7167**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7168 7169**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7170 7171**参数：** 7172 7173| 参数名 | 类型 | 必填 | 说明 | 7174| -------- | ------------------------------- | ---- | -------------------------- | 7175| callback | AsyncCallback<[Image](#image9)> | 是 | 回调函数，当获取下一张图片成功，err为undefined，data为获取到的下一张图片；否则为错误对象。 | 7176 7177**示例：** 7178 7179```ts 7180import { BusinessError } from '@kit.BasicServicesKit'; 7181 7182receiver.readNextImage((err: BusinessError, img: image.Image) => { 7183 if (err) { 7184 console.error(`Failed to read the next Image.code ${err.code},message is ${err.message}`); 7185 } else { 7186 console.info('Succeeded in reading the next Image.'); 7187 } 7188}); 7189``` 7190 7191### readNextImage<sup>9+</sup> 7192 7193readNextImage(): Promise\<Image> 7194 7195从ImageReceiver读取下一张图片，并使用promise返回结果。 7196 7197**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7198 7199**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7200 7201**返回值：** 7202 7203| 类型 | 说明 | 7204| ------------------------- | -------------------- | 7205| Promise<[Image](#image9)> | Promise对象，返回下一张图片。 | 7206 7207**示例：** 7208 7209```ts 7210import { BusinessError } from '@kit.BasicServicesKit'; 7211 7212receiver.readNextImage().then((img: image.Image) => { 7213 console.info('Succeeded in reading the next Image.'); 7214}).catch((error: BusinessError) => { 7215 console.error(`Failed to read the next Image.code ${error.code},message is ${error.message}`); 7216}) 7217``` 7218 7219### on<sup>9+</sup> 7220 7221on(type: 'imageArrival', callback: AsyncCallback\<void>): void 7222 7223接收图片时注册回调。 7224 7225**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7226 7227**参数：** 7228 7229| 参数名 | 类型 | 必填 | 说明 | 7230| -------- | -------------------- | ---- | ------------------------------------------------------ | 7231| type | string | 是 | 注册事件的类型，固定为'imageArrival'，接收图片时触发。 | 7232| callback | AsyncCallback\<void> | 是 | 回调函数，当注册事件触发成功，err为undefined，否则为错误对象。 | 7233 7234**示例：** 7235 7236```ts 7237receiver.on('imageArrival', () => { 7238 // image arrival, do something. 7239}) 7240``` 7241 7242### off<sup>13+</sup> 7243 7244off(type: 'imageArrival', callback?: AsyncCallback\<void>): void 7245 7246释放buffer时移除注册回调。 7247 7248**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7249 7250**参数：** 7251 7252| 参数名 | 类型 | 必填 | 说明 | 7253| -------- | -------------------- |----|----------------------------------------| 7254| type | string | 是 | 注册事件的类型，固定为'imageArrival'，释放buffer时触发。 | 7255| callback | AsyncCallback\<void> | 否 | 移除的回调函数。 | 7256 7257**示例：** 7258 7259```ts 7260let callbackFunc = ()=>{ 7261 // do something. 7262} 7263receiver.on('imageArrival', callbackFunc) 7264receiver.off('imageArrival', callbackFunc) 7265``` 7266 7267### release<sup>9+</sup> 7268 7269release(callback: AsyncCallback\<void>): void 7270 7271释放ImageReceiver实例并使用回调返回结果。 7272 7273ArkTS有内存回收机制，ImageReceiver对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7274 7275**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7276 7277**参数：** 7278 7279| 参数名 | 类型 | 必填 | 说明 | 7280| -------- | -------------------- | ---- | ------------------------ | 7281| callback | AsyncCallback\<void> | 是 | 回调函数，当释放ImageReceiver实例成功，err为undefined，否则为错误对象。 | 7282 7283**示例：** 7284 7285```ts 7286import { BusinessError } from '@kit.BasicServicesKit'; 7287 7288receiver.release((err: BusinessError) => { 7289 if (err) { 7290 console.error(`Failed to release the receiver.code ${err.code},message is ${err.message}`); 7291 } else { 7292 console.info('Succeeded in releasing the receiver.'); 7293 } 7294}) 7295``` 7296 7297### release<sup>9+</sup> 7298 7299release(): Promise\<void> 7300 7301释放ImageReceiver实例并使用promise返回结果。 7302 7303ArkTS有内存回收机制，ImageReceiver对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7304 7305**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7306 7307**返回值：** 7308 7309| 类型 | 说明 | 7310| -------------- | ------------------ | 7311| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7312 7313**示例：** 7314 7315```ts 7316import { BusinessError } from '@kit.BasicServicesKit'; 7317 7318receiver.release().then(() => { 7319 console.info('Succeeded in releasing the receiver.'); 7320}).catch((error: BusinessError) => { 7321 console.error(`Failed to release the receiver.code ${error.code},message is ${error.message}`); 7322}) 7323``` 7324 7325## image.createImageCreator<sup>11+</sup> 7326 7327createImageCreator(size: Size, format: ImageFormat, capacity: number): ImageCreator 7328 7329通过图片大小、图片格式、容量创建ImageCreator实例。 7330 7331**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7332 7333**参数：** 7334 7335| 参数名 | 类型 | 必填 | 说明 | 7336| -------- | ------ | ---- | ---------------------- | 7337| size | [Size](#size) | 是 | 图像的默认大小。 | 7338| format | [ImageFormat](#imageformat9) | 是 | 图像格式，如YCBCR_422_SP，JPEG。 | 7339| capacity | number | 是 | 同时访问的最大图像数。 | 7340 7341**返回值：** 7342 7343| 类型 | 说明 | 7344| ------------------------------ | --------------------------------------- | 7345| [ImageCreator](#imagecreator9) | 如果操作成功，则返回ImageCreator实例。 | 7346 7347 7348**错误码：** 7349 7350以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7351 7352| 错误码ID | 错误信息 | 7353| ------- | --------------------------------------------| 7354| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 7355 7356**示例：** 7357 7358```ts 7359let size: image.Size = { 7360 height: 8192, 7361 width: 8 7362} 7363let creator: image.ImageCreator = image.createImageCreator(size, image.ImageFormat.JPEG, 8); 7364``` 7365 7366## image.createImageCreator<sup>(deprecated)</sup> 7367 7368createImageCreator(width: number, height: number, format: number, capacity: number): ImageCreator 7369 7370通过宽、高、图片格式、容量创建ImageCreator实例。 7371 7372> **说明：** 7373> 7374> 从API version 11开始不再维护，建议使用[createImageCreator](#imagecreateimagecreator11)代替。 7375 7376**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7377 7378**参数：** 7379 7380| 参数名 | 类型 | 必填 | 说明 | 7381| -------- | ------ | ---- | ---------------------- | 7382| width | number | 是 | 图像的默认宽度。 | 7383| height | number | 是 | 图像的默认高度。 | 7384| format | number | 是 | 图像格式，如YCBCR_422_SP，JPEG。 | 7385| capacity | number | 是 | 同时访问的最大图像数。 | 7386 7387**返回值：** 7388 7389| 类型 | 说明 | 7390| ------------------------------ | --------------------------------------- | 7391| [ImageCreator](#imagecreator9) | 如果操作成功，则返回ImageCreator实例。 | 7392 7393**示例：** 7394 7395```ts 7396let creator: image.ImageCreator = image.createImageCreator(8192, 8, image.ImageFormat.JPEG, 8); 7397``` 7398 7399## ImageCreator<sup>9+</sup> 7400 7401图像创建模块，用于请求图像原生数据区域，并开放给应用编译原生图像数据的能力。 7402在调用以下方法前需要先创建[ImageCreator](#imagecreator9)实例，ImageCreator不支持多线程。 7403 7404### 属性 7405 7406**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7407 7408| 名称 | 类型 | 可读 | 可写 | 说明 | 7409| -------- | ---------------------------- | ---- | ---- | ------------------ | 7410| capacity | number | 是 | 否 | 同时访问的图像数。 | 7411| format | [ImageFormat](#imageformat9) | 是 | 否 | 图像格式。 | 7412 7413### dequeueImage<sup>9+</sup> 7414 7415dequeueImage(callback: AsyncCallback\<Image>): void 7416 7417从空闲队列中获取buffer图片，用于绘制UI内容，并使用callback返回结果。 7418 7419**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7420 7421**参数：** 7422 7423| 参数名 | 类型 | 必填 | 说明 | 7424| ------------- | ---------------------------------------| ---- | -------------------- | 7425| callback | AsyncCallback\<[Image](#image9)> | 是 | 回调函数，当获取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 7426 7427**示例：** 7428 7429```ts 7430import { BusinessError } from '@kit.BasicServicesKit'; 7431 7432creator.dequeueImage((err: BusinessError, img: image.Image) => { 7433 if (err) { 7434 console.error(`Failed to dequeue the Image.code ${err.code},message is ${err.message}`); 7435 } else { 7436 console.info('Succeeded in dequeuing the Image.'); 7437 } 7438}); 7439``` 7440 7441### dequeueImage<sup>9+</sup> 7442 7443dequeueImage(): Promise\<Image> 7444 7445从空闲队列中获取buffer图片，用于绘制UI内容，并使用promise返回结果。 7446 7447**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7448 7449**返回值：** 7450 7451| 类型 | 说明 | 7452| --------------- | ------------- | 7453| Promise\<[Image](#image9)> | Promise对象，返回最新图片。 | 7454 7455**示例：** 7456 7457```ts 7458import { BusinessError } from '@kit.BasicServicesKit'; 7459 7460creator.dequeueImage().then((img: image.Image) => { 7461 console.info('Succeeded in dequeuing the Image.'); 7462}).catch((error: BusinessError) => { 7463 console.error(`Failed to dequeue the Image.code ${error.code},message is ${error.message}`); 7464}) 7465``` 7466 7467### queueImage<sup>9+</sup> 7468 7469queueImage(interface: Image, callback: AsyncCallback\<void>): void 7470 7471将绘制好的图片放入Dirty队列，并使用callback返回结果。 7472 7473**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7474 7475**参数：** 7476 7477| 参数名 | 类型 | 必填 | 说明 | 7478| ------------- | -------------------------| ---- | -------------------- | 7479| interface | [Image](#image9) | 是 | 绘制好的buffer图像。 | 7480| callback | AsyncCallback\<void> | 是 | 回调函数，当将图片放入Dirty队列成功，err为undefined，否则为错误对象。 | 7481 7482**示例：** 7483 7484```ts 7485import { BusinessError } from '@kit.BasicServicesKit'; 7486 7487creator.dequeueImage().then((img: image.Image) => { 7488 //绘制图片。 7489 img.getComponent(4).then((component : image.Component) => { 7490 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 7491 for (let i = 0; i < bufferArr.length; i += 4) { 7492 bufferArr[i] = 0; //B 7493 bufferArr[i + 1] = 0; //G 7494 bufferArr[i + 2] = 255; //R 7495 bufferArr[i + 3] = 255; //A 7496 } 7497 }) 7498 creator.queueImage(img, (err: BusinessError) => { 7499 if (err) { 7500 console.error(`Failed to queue the Image.code ${err.code},message is ${err.message}`); 7501 } else { 7502 console.info('Succeeded in queuing the Image.'); 7503 } 7504 }) 7505}) 7506 7507``` 7508 7509### queueImage<sup>9+</sup> 7510 7511queueImage(interface: Image): Promise\<void> 7512 7513将绘制好的图片放入Dirty队列，并使用promise返回结果。 7514 7515**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7516 7517**参数：** 7518 7519| 参数名 | 类型 | 必填 | 说明 | 7520| ------------- | --------| ---- | ------------------- | 7521| interface | [Image](#image9) | 是 | 绘制好的buffer图像。 | 7522 7523**返回值：** 7524 7525| 类型 | 说明 | 7526| -------------- | ------------- | 7527| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7528 7529**示例：** 7530 7531```ts 7532import { BusinessError } from '@kit.BasicServicesKit'; 7533 7534creator.dequeueImage().then((img: image.Image) => { 7535 //绘制图片。 7536 img.getComponent(4).then((component: image.Component) => { 7537 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 7538 for (let i = 0; i < bufferArr.length; i += 4) { 7539 bufferArr[i] = 0; //B 7540 bufferArr[i + 1] = 0; //G 7541 bufferArr[i + 2] = 255; //R 7542 bufferArr[i + 3] = 255; //A 7543 } 7544 }) 7545 creator.queueImage(img).then(() => { 7546 console.info('Succeeded in queuing the Image.'); 7547 }).catch((error: BusinessError) => { 7548 console.error(`Failed to queue the Image.code ${error.code},message is ${error.message}`); 7549 }) 7550}) 7551 7552``` 7553 7554### on<sup>9+</sup> 7555 7556on(type: 'imageRelease', callback: AsyncCallback\<void>): void 7557 7558监听imageRelease事件，并使用callback返回结果。 7559 7560**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7561 7562**参数：** 7563 7564| 参数名 | 类型 | 必填 | 说明 | 7565| ------------- | -------------------------| ---- | -------------------- | 7566| type | string | 是 | 监听事件类型，如'imageRelease'。 | 7567| callback | AsyncCallback\<void> | 是 | 回调函数，当监听事件触发成功，err为undefined，否则为错误对象。 | 7568 7569**示例：** 7570 7571```ts 7572import { BusinessError } from '@kit.BasicServicesKit'; 7573 7574creator.on('imageRelease', (err: BusinessError) => { 7575 if (err) { 7576 console.error(`Failed to get the imageRelease callback.code ${err.code},message is ${err.message}`); 7577 } else { 7578 console.info('Succeeded in getting imageRelease callback.'); 7579 } 7580}) 7581``` 7582 7583### off<sup>13+</sup> 7584 7585off(type: 'imageRelease', callback?: AsyncCallback\<void>): void 7586 7587释放buffer时，移除注册的回调函数。 7588 7589**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7590 7591**参数：** 7592 7593| 参数名 | 类型 | 必填 | 说明 | 7594| ------------- | -------------------------|----|--------------------------------------------| 7595| type | string | 是 | 监听事件类型，如'imageRelease'。 | 7596| callback | AsyncCallback\<void> | 否 | 将被移除的回调函数。 | 7597 7598**示例：** 7599 7600```ts 7601let callbackFunc = ()=>{ 7602 // do something. 7603} 7604creator.on('imageRelease', callbackFunc) 7605creator.off('imageRelease', callbackFunc) 7606``` 7607 7608### release<sup>9+</sup> 7609 7610release(callback: AsyncCallback\<void>): void 7611 7612释放当前图像，并使用callback返回结果。 7613 7614ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7615 7616**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7617 7618**参数：** 7619 7620| 参数名 | 类型 | 必填 | 说明 | 7621| ------------- | -------------------------| ---- | -------------------- | 7622| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 7623 7624**示例：** 7625 7626```ts 7627import { BusinessError } from '@kit.BasicServicesKit'; 7628 7629creator.release((err: BusinessError) => { 7630 if (err) { 7631 console.error(`Failed to release the creator.code ${err.code},message is ${err.message}`); 7632 } else { 7633 console.info('Succeeded in releasing creator.'); 7634 } 7635}); 7636``` 7637### release<sup>9+</sup> 7638 7639release(): Promise\<void> 7640 7641释放当前图像，并使用promise返回结果。 7642 7643ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7644 7645**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7646 7647**返回值：** 7648 7649| 类型 | 说明 | 7650| -------------- | ------------- | 7651| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7652 7653**示例：** 7654 7655```ts 7656import { BusinessError } from '@kit.BasicServicesKit'; 7657 7658creator.release().then(() => { 7659 console.info('Succeeded in releasing creator.'); 7660}).catch((error: BusinessError) => { 7661 console.error(`Failed to release the creator.code ${error.code},message is ${error.message}`); 7662}) 7663``` 7664 7665## Image<sup>9+</sup> 7666 7667提供基本的图像操作，包括获取图像信息、读写图像数据。调用[readNextImage](#readnextimage9)和[readLatestImage](#readlatestimage9)接口时会返回image。 7668 7669### 属性 7670 7671**系统能力：** SystemCapability.Multimedia.Image.Core 7672 7673| 名称 | 类型 | 可读 | 可写 | 说明 | 7674| -------- | ------------------ | ---- | ---- | -------------------------------------------------- | 7675| clipRect | [Region](#region8) | 是 | 是 | 要裁剪的图像区域。 | 7676| 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)。 | 7677| format | number | 是 | 否 | 图像格式，参考[OH_NativeBuffer_Format](../apis-arkgraphics2d/_o_h___native_buffer.md#oh_nativebuffer_format)。 | 7678| timestamp<sup>12+</sup> | number | 是 | 否 | 图像时间戳。时间戳以纳秒为单位，通常是单调递增的。时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。如果要获取某张照片的生成时间，可以通过[getImageProperty](#getimageproperty11)接口读取相关的EXIF信息。| 7679 7680### getComponent<sup>9+</sup> 7681 7682getComponent(componentType: ComponentType, callback: AsyncCallback\<Component>): void 7683 7684根据图像的组件类型从图像中获取组件缓存并使用callback返回结果。 7685 7686**系统能力：** SystemCapability.Multimedia.Image.Core 7687 7688**参数：** 7689 7690| 参数名 | 类型 | 必填 | 说明 | 7691| ------------- | --------------------------------------- | ---- | -------------------- | 7692| componentType | [ComponentType](#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机） | 7693| callback | AsyncCallback<[Component](#component9)> | 是 | 回调函数，当返回组件缓冲区成功，err为undefined，data为获取到的组件缓冲区；否则为错误对象。 | 7694 7695**示例：** 7696 7697```ts 7698import { BusinessError } from '@kit.BasicServicesKit'; 7699 7700img.getComponent(4, (err: BusinessError, component: image.Component) => { 7701 if (err) { 7702 console.error(`Failed to get the component.code ${err.code},message is ${err.message}`); 7703 } else { 7704 console.info('Succeeded in getting component.'); 7705 } 7706}) 7707``` 7708 7709### getComponent<sup>9+</sup> 7710 7711getComponent(componentType: ComponentType): Promise\<Component> 7712 7713根据图像的组件类型从图像中获取组件缓存并使用Promise方式返回结果。 7714 7715**系统能力：** SystemCapability.Multimedia.Image.Core 7716 7717**参数：** 7718 7719| 参数名 | 类型 | 必填 | 说明 | 7720| ------------- | -------------------------------- | ---- | ---------------- | 7721| componentType | [ComponentType](#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机） | 7722 7723**返回值：** 7724 7725| 类型 | 说明 | 7726| --------------------------------- | --------------------------------- | 7727| Promise<[Component](#component9)> | Promise对象，返回组件缓冲区。 | 7728 7729**示例：** 7730 7731```ts 7732import { BusinessError } from '@kit.BasicServicesKit'; 7733 7734img.getComponent(4).then((component: image.Component) => { 7735 console.info('Succeeded in getting component.'); 7736}).catch((error: BusinessError) => { 7737 console.error(`Failed to get the component.code ${error.code},message is ${error.message}`); 7738}) 7739``` 7740 7741### release<sup>9+</sup> 7742 7743release(callback: AsyncCallback\<void>): void 7744 7745释放当前图像并使用callback返回结果。 7746 7747在接收另一个图像前必须先释放对应资源。 7748 7749ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7750 7751**系统能力：** SystemCapability.Multimedia.Image.Core 7752 7753**参数：** 7754 7755| 参数名 | 类型 | 必填 | 说明 | 7756| -------- | -------------------- | ---- | -------------- | 7757| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 7758 7759**示例：** 7760 7761```ts 7762import { BusinessError } from '@kit.BasicServicesKit'; 7763 7764img.release((err: BusinessError) => { 7765 if (err) { 7766 console.error(`Failed to release the image instance.code ${err.code},message is ${err.message}`); 7767 } else { 7768 console.info('Succeeded in releasing the image instance.'); 7769 } 7770}) 7771``` 7772 7773### release<sup>9+</sup> 7774 7775release(): Promise\<void> 7776 7777释放当前图像并使用Promise方式返回结果。 7778 7779在接收另一个图像前必须先释放对应资源。 7780 7781ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7782 7783**系统能力：** SystemCapability.Multimedia.Image.Core 7784 7785**返回值：** 7786 7787| 类型 | 说明 | 7788| -------------- | --------------------- | 7789| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7790 7791**示例：** 7792 7793```ts 7794import { BusinessError } from '@kit.BasicServicesKit'; 7795 7796img.release().then(() => { 7797 console.info('Succeeded in releasing the image instance.'); 7798}).catch((error: BusinessError) => { 7799 console.error(`Failed to release the image instance.code ${error.code},message is ${error.message}`); 7800}) 7801``` 7802 7803## PositionArea<sup>7+</sup> 7804 7805表示图片指定区域内的数据。 7806 7807**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 7808 7809**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 7810 7811**系统能力：** SystemCapability.Multimedia.Image.Core 7812 7813| 名称 | 类型 | 只读| 可选| 说明 | 7814| ------ | ------------------ | ---| -----|------------------------------------------------------- | 7815| pixels | ArrayBuffer | 否 | 否 | 像素。仅支持BGRA_8888格式的图像像素数据。 | 7816| offset | number | 否 | 否 | 偏移量。 | 7817| stride | number | 否 | 否 | 跨距，内存中每行像素所占的空间。stride >= region.size.width*4。 | 7818| region | [Region](#region8) | 否 | 否 |区域，按照区域读写。写入的区域宽度加X坐标不能大于原图的宽度，写入的区域高度加Y坐标不能大于原图的高度。 | 7819 7820## ImageInfo 7821 7822表示图片信息。 7823 7824**系统能力：** SystemCapability.Multimedia.Image.Core 7825 7826| 名称 | 类型 | 只读 | 可选 | 说明 | 7827| ---- | ------------- | --- |-----|---------- | 7828| size<sup>6+</sup> | [Size](#size) | 否 | 否 |图片大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7829| density<sup>9+</sup> | number | 否 | 否 |像素密度，单位为ppi。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7830| stride<sup>11+</sup> | number | 否 | 否 | 跨距，内存中每行像素所占的空间。stride >= region.size.width*4 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7831| pixelFormat<sup>12+</sup> | [PixelMapFormat](#pixelmapformat7) | 否 | 否 | 像素格式。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7832| alphaType<sup>12+</sup> | [AlphaType](#alphatype9) | 否 | 否 |透明度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7833| mimeType<sup>12+</sup> | string | 否 | 否 |图片真实格式（MIME type）。 | 7834| isHdr<sup>12+</sup> | boolean | 否 | 否 | 图片是否为高动态范围（HDR）。对于[ImageSource](#imagesource)，代表源图片是否为HDR；对于[PixelMap](#pixelmap7)，代表解码后的pixelmap是否为HDR。 | 7835 7836## Size 7837 7838表示图片尺寸。 7839 7840**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 7841 7842**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 7843 7844**系统能力：** SystemCapability.Multimedia.Image.Core 7845 7846| 名称 | 类型 | 只读 | 可选 |说明 | 7847| ------ | ------ | -- |-----| -------------- | 7848| height | number | 否 | 否 |输出图片的高，单位：像素。 | 7849| width | number | 否 | 否 | 输出图片的宽，单位：像素。 | 7850 7851## PixelMapFormat<sup>7+</sup> 7852 7853枚举，图片像素格式。 7854 7855**系统能力：** SystemCapability.Multimedia.Image.Core 7856 7857| 名称 | 值 | 说明 | 7858| ---------------------- | ------ | ----------------- | 7859| UNKNOWN | 0 | 未知格式。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7860| 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卡片中使用。 | 7861| RGBA_8888 | 3 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，每个部分占8位，总共占32位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7862| 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卡片中使用。 | 7863| RGB_888<sup>9+</sup> | 5 | 颜色信息由R（Red），G（Green），B（Blue）三部分组成，每个部分占8位，总共占24位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7864| ALPHA_8<sup>9+</sup> | 6 | 颜色信息仅包含透明度（Alpha），每个像素占8位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7865| 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卡片中使用。 | 7866| NV21<sup>9+</sup> | 8 | 颜色信息由亮度分量Y和交错排列的色度分量V和U组成，其中Y分量占8位，UV分量因4：2：0采样平均占4位，总共平均占12位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7867| NV12<sup>9+</sup> | 9 | 颜色信息由亮度分量Y和交错排列的色度分量U和V组成，其中Y分量占8位，UV分量因4：2：0采样平均占4位，总共平均占12位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7868| RGBA_1010102<sup>12+</sup> | 10 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，其中R、G、B分别占10位，透明度占2位，总共占32位。 | 7869| YCBCR_P010<sup>12+</sup> | 11 | 颜色信息由亮度分量Y和色度分量Cb与Cr组成，每个分量有效10位，实际存储时，Y平面每个像素占16位数据（10位有效），UV平面交错排列，每4个像素占32位数据（每色度分量10位有效），平均有效占15位。 7870| YCRCB_P010<sup>12+</sup> | 12 | 颜色信息由亮度分量Y和色度分量Cr与Cb组成，每个分量有效10位，实际存储时，Y平面每个像素占16位数据（10位有效），UV平面交错排列，每4个像素占32位数据（每色度分量10位有效），平均有效占15位。 | 7871 7872## AlphaType<sup>9+</sup> 7873 7874枚举，图像的透明度类型。 7875 7876**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 7877 7878**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 7879 7880**系统能力：** SystemCapability.Multimedia.Image.Core 7881 7882| 名称 | 值 | 说明 | 7883| -------- | ------ | ----------------------- | 7884| UNKNOWN | 0 | 未知透明度。 | 7885| OPAQUE | 1 | 没有alpha或图片不透明。 | 7886| PREMUL | 2 | RGB预乘alpha。 | 7887| UNPREMUL | 3 | RGB非预乘alpha。 | 7888 7889## AuxiliaryPictureType<sup>13+</sup> 7890 7891枚举，辅助图的图像类型。 7892 7893**系统能力：** SystemCapability.Multimedia.Image.Core 7894 7895| 名称 | 值 | 说明 | 7896| ------------- | ---- | ------------ | 7897| GAINMAP | 1 | 增益图，代表了一种增强SDR图像以产生具有可变显示调整能力的HDR图像的机制。它是一组描述如何应用gainmap元数据的组合。 | 7898| DEPTH_MAP | 2 | 深度图，储存图像的深度数据，通过捕捉每个像素与摄像机之间的距离，提供场景的三维结构信息，通常用于3D重建和场景理解。 | 7899| UNREFOCUS_MAP | 3 | 人像未对焦的原图，提供了一种在人像拍摄中突出背景模糊效果的方式，能够帮助用户在后期处理中选择焦点区域，增加创作自由度。 | 7900| LINEAR_MAP | 4 | 线性图，用于提供额外的数据视角或补充信息，通常用于视觉效果的增强，它可以包含场景中光照、颜色或其他视觉元素的线性表示。 | 7901| FRAGMENT_MAP | 5 | 水印裁剪图，表示在原图中被水印覆盖的区域，该图像用于修复或移除水印影响，恢复图像的完整性和可视性。 | 7902 7903## AuxiliaryPictureInfo<sup>13+</sup> 7904 7905表示辅助图图像信息。 7906 7907**系统能力：** SystemCapability.Multimedia.Image.Core 7908 7909| 名称 | 类型 | 只读 | 可选 | 说明 | 7910| ------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 7911| auxiliaryPictureType | [AuxiliaryPictureType](#auxiliarypicturetype13) | 否 | 否 | 辅助图的图像类型。 | 7912| size | [Size](#size) | 否 | 否 | 图片大小。 | 7913| rowStride | number | 否 | 否 | 行距。 | 7914| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 否 | 像素格式。 | 7915| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 否 | 否 | 目标色彩空间。 | 7916 7917## MetadataType<sup>13+</sup> 7918 7919枚举，图片元数据类型。 7920 7921**系统能力：** SystemCapability.Multimedia.Image.Core 7922 7923| 名称 | 值 | 说明 | 7924| ----------------- | ---- | ------------------ | 7925| EXIF_METADATA | 1 | exif数据。 | 7926| FRAGMENT_METADATA | 2 | 水印裁剪图元数据。 | 7927 7928## ScaleMode<sup>9+</sup> 7929 7930枚举，图像的缩放模式。 7931 7932**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 7933 7934**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 7935 7936**系统能力：** SystemCapability.Multimedia.Image.Core 7937 7938| 名称 | 值 | 说明 | 7939| --------------- | ------ | -------------------------------------------------- | 7940| CENTER_CROP | 1 | 缩放图像以填充目标图像区域并居中裁剪区域外的效果。 | 7941| FIT_TARGET_SIZE | 0 | 图像适合目标尺寸的效果。 | 7942 7943## SourceOptions<sup>9+</sup> 7944 7945ImageSource的初始化选项。 7946 7947**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 7948 7949**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 7950 7951**系统能力：** SystemCapability.Multimedia.Image.Core 7952 7953| 名称 | 类型 | 只读 | 可选 | 说明 | 7954| ----------------- | ---------------------------------- | ---- | ---- | ------------------ | 7955| sourceDensity | number | 否 | 否 | 图片资源像素密度，单位DPI。<br>在解码参数[DecodingOptions](#decodingoptions7)未设置desiredSize的前提下，当前参数SourceOptions.sourceDensity与DecodingOptions.fitDensity非零时将对解码输出的pixelmap进行缩放。<br>缩放后宽计算公式如下(高同理)：(width * fitDensity + (sourceDensity >> 1)) / sourceDensity。| 7956| sourcePixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 图片像素格式，默认值为UNKNOWN。 | 7957| sourceSize | [Size](#size) | 否 | 是 | 图像像素大小，默认值为空。 | 7958 7959 7960## InitializationOptions<sup>8+</sup> 7961 7962PixelMap的初始化选项。 7963 7964**系统能力：** SystemCapability.Multimedia.Image.Core 7965 7966| 名称 | 类型 | 只读 |可选 | 说明 | 7967| ------------------------ | ---------------------------------- | ----| -----| -------------- | 7968| alphaType<sup>9+</sup> | [AlphaType](#alphatype9) | 否 | 是| 透明度。默认值为IMAGE_ALPHA_TYPE_PREMUL。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7969| editable | boolean | 否 | 是| 是否可编辑。默认值为false。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。| 7970| srcPixelFormat<sup>12+</sup> | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 传入的buffer数据的像素格式。默认值为BGRA_8888。| 7971| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是| 生成的pixelMap的像素格式。默认值为RGBA_8888。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7972| scaleMode<sup>9+</sup> | [ScaleMode](#scalemode9) | 否 | 是 | 缩略值。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7973| size | [Size](#size) | 否 | 否|创建图片大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7974 7975## DecodingOptions<sup>7+</sup> 7976 7977图像解码设置选项。 7978 7979**系统能力：** SystemCapability.Multimedia.Image.ImageSource 7980 7981| 名称 | 类型 | 只读 | 可选 | 说明 | 7982| ------------------ | ---------------------------------- | ---- | ---- | ---------------- | 7983| sampleSize | number | 否 | 是 | 缩略图采样大小，默认值为1。当前只能取1。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7984| rotate | number | 否 | 是 | 旋转角度。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7985| editable | boolean | 否 | 是 | 是否可编辑。默认值为false。当取值为false时，图片不可二次编辑，如writepixels操作将失败。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7986| desiredSize | [Size](#size) | 否 | 是 | 期望输出大小，必须为正整数，若与原尺寸比例不一致，则会进行拉伸/缩放到指定尺寸，默认为原始尺寸。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7987| desiredRegion | [Region](#region8) | 否 | 是 | 解码图像中由Region指定的矩形区域，当原始图像很大而只需要解码图像的一部分时，可以设置该参数，有助于提升性能，默认为原始大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7988| 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卡片中使用。 | 7989| index | number | 否 | 是 | 解码图片序号。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7990| fitDensity<sup>9+</sup> | number | 否 | 是 | 图像像素密度，单位为ppi。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 7991| desiredColorSpace<sup>11+</sup> | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 否 | 是 | 目标色彩空间。默认值为UNKNOWN。 | 7992| desiredDynamicRange<sup>12+</sup> | [DecodingDynamicRange](#decodingdynamicrange12) | 否 | 是 | 目标动态范围，默认值为SDR。<br>通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource不支持设置此属性，默认解码为SDR内容。<br>如果平台不支持HDR，设置无效，默认解码为SDR内容。 | 7993 7994## DecodingOptionsForPicture<sup>13+</sup> 7995 7996图像解码设置选项。 7997 7998**系统能力：** SystemCapability.Multimedia.Image.ImageSource 7999 8000| 名称 | 类型 | 只读 | 可选 | 说明 | 8001| ------------------------ | ------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | 8002| desiredAuxiliaryPictures | Array\<[AuxiliaryPictureType](#auxiliarypicturetype13)> | 否 | 否 | 设置AuxiliaryPicture类型，默认解码所有AuxiliaryPicture类型。 | 8003 8004## Region<sup>8+</sup> 8005 8006表示区域信息。 8007 8008**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8009 8010**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8011 8012**系统能力：** SystemCapability.Multimedia.Image.Core 8013 8014| 名称 | 类型 | 只读 | 可选| 说明 | 8015| ---- | ------------- | ---- | ---- | ------------ | 8016| size<sup>7+</sup> | [Size](#size) | 否 | 否 | 区域大小。 | 8017| x<sup>7+</sup> | number | 否 | 否 | 区域左上角横坐标。 | 8018| y<sup>7+</sup> | number | 否 | 否 | 区域左上角纵坐标。 | 8019 8020## PackingOption 8021 8022表示图片打包选项。 8023 8024**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 8025 8026| 名称 | 类型 | 只读 | 可选 | 说明 | 8027| ------- | ------ | ---- | ---- | --------------------------------------------------- | 8028| format | string | 否 | 否 | 目标格式。</br>当前只支持"image/jpeg"、"image/webp"、"image/png"和"image/heic(或者image/heif)"<sup>12+</sup>（不同硬件设备支持情况不同）。<br>**说明：** 因为jpeg不支持透明通道，若使用带透明通道的数据编码jpeg格式，透明色将变为黑色。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8029| quality | number | 否 | 否 | JPEG编码中设定输出图片质量的参数，取值范围为0-100。0质量最低，100质量最高，质量越高生成图片所占空间越大。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8030| bufferSize<sup>9+</sup> | number | 否 | 是 | 接收编码数据的缓冲区大小，单位为Byte。如果不设置大小，默认为25M。如果编码图片超过25M，需要指定大小。bufferSize需大于编码后图片大小。使用[packToFile](#packtofile11)不受此参数限制。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8031| desiredDynamicRange<sup>12+</sup> | [PackingDynamicRange](#packingdynamicrange12) | 否 | 是 | 目标动态范围。默认值为SDR。 | 8032| needsPackProperties<sup>12+</sup> | boolean | 否 | 是 | 是否需要编码图片属性信息，例如EXIF。默认值为false。 | 8033 8034## ImagePropertyOptions<sup>11+</sup> 8035 8036表示查询图片属性的索引。 8037 8038**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8039 8040| 名称 | 类型 | 只读 | 可选 | 说明 | 8041| ------------ | ------ | ---- | ---- | ------------ | 8042| index | number | 是 | 是 | 图片序号。默认值为0。 | 8043| defaultValue | string | 是 | 是 | 默认属性值。默认值为空。 | 8044 8045## GetImagePropertyOptions<sup>(deprecated)</sup> 8046 8047表示查询图片属性的索引。 8048 8049> **说明：** 8050> 8051> 从API version 11开始不再维护，建议使用[ImagePropertyOptions](#imagepropertyoptions11)代替。 8052 8053**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8054 8055| 名称 | 类型 | 只读 | 可选 | 说明 | 8056| ------------ | ------ | ---- | ---- | ------------ | 8057| index | number | 否 | 是 | 图片序号。默认值为0。 | 8058| defaultValue | string | 否 | 是 | 默认属性值。默认值为空。 | 8059 8060## PropertyKey<sup>7+</sup> 8061 8062枚举，Exif（Exchangeable image file format）图片信息。 8063 8064**系统能力：** SystemCapability.Multimedia.Image.Core 8065 8066| 名称 | 值 | 说明 | 8067| ----------------- | ----------------------- |---------------------------| 8068| NEW_SUBFILE_TYPE <sup>12+</sup> | "NewSubfileType" | **读写能力：** 可读写<br> 在Exif中，"NewSubfileType"字段用于标识子文件的数据类型，如全分辨率图像、缩略图或多帧图像的一部分。其值是位掩码，0代表全分辨率图像，1代表缩略图，2代表多帧图像的一部分。| 8069| SUBFILE_TYPE <sup>12+</sup> | "SubfileType" | **读写能力：** 可读写<br> 此标签指示此子文件中的数据类型。标签已弃用，请使用NewSubfileType替代。| 8070| IMAGE_WIDTH | "ImageWidth" | **读写能力：** 可读写<br> 图片宽度。| 8071| IMAGE_LENGTH | "ImageLength" | **读写能力：** 可读写<br> 图片长度。| 8072| BITS_PER_SAMPLE | "BitsPerSample" | **读写能力：** 可读写<br> 像素各分量的位数，如RGB，3分量，格式是8, 8, 8。| 8073| COMPRESSION <sup>12+</sup> | "Compression" | **读写能力：** 可读写<br> 图像压缩方案。| 8074| PHOTOMETRIC_INTERPRETATION <sup>12+</sup> | "PhotometricInterpretation" | **读写能力：** 可读写<br> 像素构成，例如 RGB 或 YCbCr。| 8075| IMAGE_DESCRIPTION<sup>10+</sup> | "ImageDescription" | **读写能力：** 可读写<br> 图像信息描述。| 8076| MAKE<sup>10+</sup> | "Make" | **读写能力：** 可读写<br> 生产商。| 8077| MODEL<sup>10+</sup> | "Model" | **读写能力：** 可读写<br> 设备型号。| 8078| STRIP_OFFSETS <sup>12+</sup> | "StripOffsets" | **读写能力：** 可读写<br> 每个strip的字节偏移量。| 8079| 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。| 8080| SAMPLES_PER_PIXEL <sup>12+</sup> | "SamplesPerPixel" | **读写能力：** 可读写<br> 每个像素的分量数。由于该标准适用于 RGB 和 YCbCr 图像，因此该标签的值设置为 3。在 JPEG 压缩数据中，使用 JPEG 标记代替该标签。| 8081| ROWS_PER_STRIP <sup>12+</sup> | "RowsPerStrip" | **读写能力：** 可读写<br> 每个strip的图像数据行数。| 8082| STRIP_BYTE_COUNTS <sup>12+</sup> | "StripByteCounts" | **读写能力：** 可读写<br> 每个图像数据带的总字节数。| 8083| X_RESOLUTION <sup>12+</sup> | "XResolution" | **读写能力：** 可读写<br> 图像宽度方向的分辨率。| 8084| Y_RESOLUTION <sup>12+</sup> | "YResolution" | **读写能力：** 可读写<br> 图像高度方向的分辨率。| 8085| PLANAR_CONFIGURATION <sup>12+</sup> | "PlanarConfiguration" | **读写能力：** 可读写<br> 表示像素组件的记录格式，chunky格式或是planar格式。| 8086| RESOLUTION_UNIT <sup>12+</sup> | "ResolutionUnit" | **读写能力：** 可读写<br> 用于测量XResolution和YResolution的单位。| 8087| TRANSFER_FUNCTION <sup>12+</sup> | "TransferFunction" | **读写能力：** 可读写<br> 图像的传递函数，通常用于颜色校正。| 8088| SOFTWARE <sup>12+</sup> | "Software" | **读写能力：** 可读写<br> 用于生成图像的软件的名称和版本。| 8089| DATE_TIME<sup>10+</sup> | "DateTime" | **读写能力：** 可读写<br> 日期时间。格式如2024:01:25 05:51:34。| 8090| ARTIST <sup>12+</sup> | "Artist" | **读写能力：** 可读写<br> 创建图像的用户名称。| 8091| WHITE_POINT <sup>12+</sup> | "WhitePoint" | **读写能力：** 可读写<br> 图像的白点色度。| 8092| PRIMARY_CHROMATICITIES <sup>12+</sup> | "PrimaryChromaticities" | **读写能力：** 可读写<br> 图像的主要颜色的色度。| 8093| PHOTO_MODE<sup>10+</sup> | "PhotoMode" | **读写能力：** 可读写<br> 拍照模式。| 8094| JPEG_INTERCHANGE_FORMAT <sup>12+</sup> | "JPEGInterchangeFormat" | **读写能力：** 可读写<br> JPEG压缩缩略图数据开始字节（SOI）的偏移。| 8095| JPEG_INTERCHANGE_FORMAT_LENGTH <sup>12+</sup> | "JPEGInterchangeFormatLength" | **读写能力：** 可读写<br> JPEG压缩缩略图数据的字节数。| 8096| YCBCR_COEFFICIENTS <sup>12+</sup> | "YCbCrCoefficients" | **读写能力：** 可读写<br> 从RGB到YCbCr图像数据的转换矩阵系数。| 8097| YCBCR_SUB_SAMPLING <sup>12+</sup> | "YCbCrSubSampling" | **读写能力：** 可读写<br> 色度分量与亮度分量的采样比率。| 8098| YCBCR_POSITIONING <sup>12+</sup> | "YCbCrPositioning" | **读写能力：** 可读写<br> 色度分量相对于亮度分量的位置。| 8099| REFERENCE_BLACK_WHITE <sup>12+</sup> | "ReferenceBlackWhite" | **读写能力：** 可读写<br> 参考黑点值和参考白点值。| 8100| COPYRIGHT <sup>12+</sup> | "Copyright" | **读写能力：** 可读写<br> 图像的版权信息。| 8101| EXPOSURE_TIME<sup>9+</sup> | "ExposureTime" | **读写能力：** 可读写<br> 曝光时间，例如1/33 sec。| 8102| F_NUMBER<sup>9+</sup> | "FNumber" | **读写能力：** 可读写<br> 光圈值，例如f/1.8。| 8103| EXPOSURE_PROGRAM <sup>12+</sup> | "ExposureProgram" | **读写能力：** 可读写<br> 拍照时相机用来设置曝光的程序的类别。| 8104| SPECTRAL_SENSITIVITY <sup>12+</sup> | "SpectralSensitivity" | **读写能力：** 可读写<br> 表示所用相机的每个通道的光谱灵敏度。| 8105| GPS_VERSION_ID <sup>12+</sup> | "GPSVersionID" | **读写能力：** 可读写<br> GPSInfoIFD的版本。| 8106| GPS_LATITUDE_REF | "GPSLatitudeRef" | **读写能力：** 可读写<br> 纬度引用，例如N或S。| 8107| GPS_LATITUDE | "GPSLatitude" | **读写能力：** 可读写<br> 图片纬度。修改时应按"度,分,秒"格式传入，如"39,54,7.542"| 8108| GPS_LONGITUDE_REF | "GPSLongitudeRef" | **读写能力：** 可读写<br> 经度引用，例如W或E。| 8109| GPS_LONGITUDE | "GPSLongitude" | **读写能力：** 可读写<br> 图片经度。修改时应按"度,分,秒"格式传入，如"116,19,42.16"| 8110| GPS_ALTITUDE_REF <sup>12+</sup> | "GPSAltitudeRef" | **读写能力：** 可读写<br> 用于GPS高度的参照高度。| 8111| GPS_ALTITUDE <sup>12+</sup> | "GPSAltitude" | **读写能力：** 可读写<br> 基于GPSAltitudeRef的高度。| 8112| GPS_TIME_STAMP<sup>10+</sup> | "GPSTimeStamp" | **读写能力：** 可读写<br> GPS时间戳。| 8113| GPS_SATELLITES <sup>12+</sup> | "GPSSatellites" | **读写能力：** 可读写<br> 用于测量的GPS卫星。| 8114| GPS_STATUS <sup>12+</sup> | "GPSStatus" | **读写能力：** 可读写<br> 录制图像时GPS接收器的状态。| 8115| GPS_MEASURE_MODE <sup>12+</sup> | "GPSMeasureMode" | **读写能力：** 可读写<br> GPS测量模式。| 8116| GPS_DOP <sup>12+</sup> | "GPSDOP" | **读写能力：** 可读写<br> GPS DOP（数据精度等级）。| 8117| GPS_SPEED_REF <sup>12+</sup> | "GPSSpeedRef" | **读写能力：** 可读写<br> 用来表示GPS接收器移动速度的单位。| 8118| GPS_SPEED <sup>12+</sup> | "GPSSpeed" | **读写能力：** 可读写<br> GPS接收器的移动速度。| 8119| GPS_TRACK_REF <sup>12+</sup> | "GPSTrackRef" | **读写能力：** 可读写<br> GPS接收机移动方向的参照。| 8120| GPS_TRACK <sup>12+</sup> | "GPSTrack" | **读写能力：** 可读写<br> GPS接收机的移动方向。| 8121| GPS_IMG_DIRECTION_REF <sup>12+</sup> | "GPSImgDirectionRef" | **读写能力：** 可读写<br> 图像方向的参照。| 8122| GPS_IMG_DIRECTION <sup>12+</sup> | "GPSImgDirection" | **读写能力：** 可读写<br> 拍摄时图像的方向。| 8123| GPS_MAP_DATUM <sup>12+</sup> | "GPSMapDatum" | **读写能力：** 可读写<br> GPS接收器使用的大地测量数据。| 8124| GPS_DEST_LATITUDE_REF <sup>12+</sup> | "GPSDestLatitudeRef" | **读写能力：** 可读写<br> 目的地点的纬度参照。| 8125| GPS_DEST_LATITUDE <sup>12+</sup> | "GPSDestLatitude" | **读写能力：** 可读写<br> 目的地点的纬度。| 8126| GPS_DEST_LONGITUDE_REF <sup>12+</sup> | "GPSDestLongitudeRef" | **读写能力：** 可读写<br> 目的地点的经度参照。| 8127| GPS_DEST_LONGITUDE <sup>12+</sup> | "GPSDestLongitude" | **读写能力：** 可读写<br> 目的地点的经度。| 8128| GPS_DEST_BEARING_REF <sup>12+</sup> | "GPSDestBearingRef" | **读写能力：** 可读写<br> 指向目的地点的方位参照。| 8129| GPS_DEST_BEARING <sup>12+</sup> | "GPSDestBearing" | **读写能力：** 可读写<br> 目的地方位。| 8130| GPS_DEST_DISTANCE_REF <sup>12+</sup> | "GPSDestDistanceRef" | **读写能力：** 可读写<br> 目标点距离的测量单位。| 8131| GPS_DEST_DISTANCE <sup>12+</sup> | "GPSDestDistance" | **读写能力：** 可读写<br> 到目的地点的距离。| 8132| GPS_PROCESSING_METHOD <sup>12+</sup> | "GPSProcessingMethod" | **读写能力：** 可读写<br> 记录定位方法名的字符字符串。| 8133| GPS_AREA_INFORMATION <sup>12+</sup> | "GPSAreaInformation" | **读写能力：** 可读写<br> 记录GPS区域名的字符字符串。| 8134| GPS_DATE_STAMP<sup>10+</sup> | "GPSDateStamp" | **读写能力：** 可读写<br> GPS日期戳。| 8135| GPS_DIFFERENTIAL <sup>12+</sup> | "GPSDifferential" | **读写能力：** 可读写<br> 此字段表示GPS数据是否应用了差分校正，对于精确的位置准确性至关重要。| 8136| GPS_H_POSITIONING_ERROR <sup>12+</sup> | "GPSHPositioningError" | **读写能力：** 可读写<br> 此标签指示水平定位误差，单位为米。| 8137| ISO_SPEED_RATINGS<sup>9+</sup> | "ISOSpeedRatings" | **读写能力：** 可读写<br> ISO感光度，例如400。| 8138| PHOTOGRAPHIC_SENSITIVITY <sup>12+</sup> | "PhotographicSensitivity" | **读写能力：** 可读写<br> 此标签指示拍摄图像时相机或输入设备的灵敏度。| 8139| OECF <sup>12+</sup> | "OECF" | **读写能力：** 可读写<br> 表示ISO 14524中规定的光电转换函数（OECF）。| 8140| SENSITIVITY_TYPE<sup>10+</sup> | "SensitivityType" | **读写能力：** 可读写<br> 灵敏度类型。| 8141| STANDARD_OUTPUT_SENSITIVITY<sup>10+</sup> | "StandardOutputSensitivity" | **读写能力：** 可读写<br> 标准输出灵敏度。| 8142| RECOMMENDED_EXPOSURE_INDEX<sup>10+</sup> | "RecommendedExposureIndex" | **读写能力：** 可读写<br> 推荐曝光指数。| 8143| ISO_SPEED<sup>10+</sup> | "ISOSpeedRatings" | **读写能力：** 可读写<br> ISO速度等级。| 8144| ISO_SPEED_LATITUDE_YYY <sup>12+</sup> | "ISOSpeedLatitudeyyy" | **读写能力：** 可读写<br> 该标签指示摄像机或输入设备的ISO速度纬度yyy值，该值在ISO 12232中定义。| 8145| ISO_SPEED_LATITUDE_ZZZ <sup>12+</sup> | "ISOSpeedLatitudezzz" | **读写能力：** 可读写<br> 该标签指示摄像机或输入设备的ISO速度纬度zzz值，该值在ISO 12232中定义。| 8146| EXIF_VERSION <sup>12+</sup> | "ExifVersion" | **读写能力：** 可读写<br> 支持的Exif标准版本。| 8147| DATE_TIME_ORIGINAL<sup>9+</sup> | "DateTimeOriginal" | **读写能力：** 可读写<br> 拍摄时间，例如2022:09:06 15:48:00。| 8148| DATE_TIME_DIGITIZED <sup>12+</sup> | "DateTimeDigitized" | **读写能力：** 可读写<br> 图像作为数字数据存储的日期和时间，格式为YYYY:MM:DD HH:MM:SS| 8149| OFFSET_TIME <sup>12+</sup> | "OffsetTime" | **读写能力：** 可读写<br> 在Exif中，OffsetTime字段表示与UTC（协调世界时）的时间偏移，格式为±HH:MM，用于确定照片拍摄的本地时间。| 8150| OFFSET_TIME_ORIGINAL <sup>12+</sup> | "OffsetTimeOriginal" | **读写能力：** 可读写<br> 此标签记录原始图像创建时的UTC偏移量，对于时间敏感的应用至关重要。| 8151| OFFSET_TIME_DIGITIZED <sup>12+</sup> | "OffsetTimeDigitized" | **读写能力：** 可读写<br> 此标签记录图像数字化时的UTC偏移量，有助于准确调整时间戳。| 8152| COMPONENTS_CONFIGURATION <sup>12+</sup> | "ComponentsConfiguration" | **读写能力：** 可读写<br> 压缩数据的特定信息。| 8153| COMPRESSED_BITS_PER_PIXEL <sup>12+</sup> | "CompressedBitsPerPixel" | **读写能力：** 可读写<br> 用于压缩图像的压缩模式，单位为每像素位数。| 8154| SHUTTER_SPEED <sup>12+</sup> | "ShutterSpeedValue" | **读写能力：** 可读写<br> 快门速度，以APEX（摄影曝光的加法系统）值表示。| 8155| APERTURE_VALUE<sup>10+</sup> | "ApertureValue" | **读写能力：** 可读写<br> 光圈值。格式如4/1。| 8156| BRIGHTNESS_VALUE <sup>12+</sup> | "BrightnessValue" | **读写能力：** 可读写<br> 图像的亮度值，以APEX单位表示。| 8157| EXPOSURE_BIAS_VALUE<sup>10+</sup> | "ExposureBiasValue" | **读写能力：** 可读写<br> 曝光偏差值。| 8158| MAX_APERTURE_VALUE <sup>12+</sup> | "MaxApertureValue" | **读写能力：** 可读写<br> 最小F数镜头。| 8159| SUBJECT_DISTANCE <sup>12+</sup> | "SubjectDistance" | **读写能力：** 可读写<br> 测量单位为米的主体距离。| 8160| METERING_MODE<sup>10+</sup> | "MeteringMode" | **读写能力：** 可读写<br> 测光模式。| 8161| LIGHT_SOURCE<sup>10+</sup> | "LightSource" | **读写能力：** 可读写<br> 光源。例如Fluorescent。| 8162| FLASH <sup>10+</sup> | "Flash" | **读写能力：** 可读写<br> 闪光灯,记录闪光灯状态。| 8163| FOCAL_LENGTH <sup>10+</sup> | "FocalLength" | **读写能力：** 可读写<br> 焦距。| 8164| SUBJECT_AREA <sup>12+</sup> | "SubjectArea" | **读写能力：** 可读写<br> 该标签指示整个场景中主要主体的位置和区域。| 8165| MAKER_NOTE <sup>12+</sup> | "MakerNote" | **读写能力：** 只读<br> Exif/DCF制造商使用的标签，用于记录任何所需信息。| 8166| SCENE_POINTER <sup>12+</sup> | "HwMnoteScenePointer" | **读写能力：** 只读<br> 场景指针。| 8167| SCENE_VERSION <sup>12+</sup> | "HwMnoteSceneVersion" | **读写能力：** 只读<br> 场景算法版本信息。| 8168| SCENE_FOOD_CONF<sup>11+</sup> | "HwMnoteSceneFoodConf" | **读写能力：** 只读<br> 拍照场景：食物。| 8169| SCENE_STAGE_CONF<sup>11+</sup> | "HwMnoteSceneStageConf" | **读写能力：** 只读<br> 拍照场景：舞台。| 8170| SCENE_BLUE_SKY_CONF<sup>11+</sup> | "HwMnoteSceneBlueSkyConf" | **读写能力：** 只读<br> 拍照场景：蓝天。| 8171| SCENE_GREEN_PLANT_CONF<sup>11+</sup> | "HwMnoteSceneGreenPlantConf" | **读写能力：** 只读<br> 拍照场景：绿植。| 8172| SCENE_BEACH_CONF<sup>11+</sup> | "HwMnoteSceneBeachConf" | **读写能力：** 只读<br> 拍照场景：沙滩。| 8173| SCENE_SNOW_CONF<sup>11+</sup> | "HwMnoteSceneSnowConf" | **读写能力：** 只读<br> 拍照场景：下雪。| 8174| SCENE_SUNSET_CONF<sup>11+</sup> | "HwMnoteSceneSunsetConf" | **读写能力：** 只读<br> 拍照场景：日落。| 8175| SCENE_FLOWERS_CONF<sup>11+</sup> | "HwMnoteSceneFlowersConf" | **读写能力：** 只读<br> 拍照场景：花。| 8176| SCENE_NIGHT_CONF<sup>11+</sup> | "HwMnoteSceneNightConf" | **读写能力：** 只读<br> 拍照场景：夜晚。| 8177| SCENE_TEXT_CONF<sup>11+</sup> | "HwMnoteSceneTextConf" | **读写能力：** 只读<br> 拍照场景：文本。| 8178| FACE_POINTER <sup>12+</sup> | "HwMnoteFacePointer" | **读写能力：** 只读<br> 脸部指针。| 8179| FACE_VERSION <sup>12+</sup> | "HwMnoteFaceVersion" | **读写能力：** 只读<br> 人脸算法版本信息。| 8180| FACE_COUNT<sup>11+</sup> | "HwMnoteFaceCount" | **读写能力：** 只读<br> 人脸数量。| 8181| FACE_CONF <sup>12+</sup> | "HwMnoteFaceConf" | **读写能力：** 只读<br> 人脸置信度。| 8182| FACE_SMILE_SCORE <sup>12+</sup> | "HwMnoteFaceSmileScore" | **读写能力：** 只读<br> FaceCount张人脸的笑脸分数。| 8183| FACE_RECT <sup>12+</sup> | "HwMnoteFaceRect" | **读写能力：** 只读<br> 脸部矩形。| 8184| FACE_LEYE_CENTER <sup>12+</sup> | "HwMnoteFaceLeyeCenter" | **读写能力：** 只读<br> 左眼中心。| 8185| FACE_REYE_CENTER <sup>12+</sup> | "HwMnoteFaceReyeCenter" | **读写能力：** 只读<br> 右眼中心。| 8186| FACE_MOUTH_CENTER <sup>12+</sup> | "HwMnoteFaceMouthCenter" | **读写能力：** 只读<br> 嘴中心。| 8187| CAPTURE_MODE <sup>10+</sup> | "HwMnoteCaptureMode" | **读写能力：** 可读写<br> 捕获模式。| 8188| BURST_NUMBER <sup>12+</sup> | "HwMnoteBurstNumber" | **读写能力：** 只读<br> 连拍次数。| 8189| FRONT_CAMERA <sup>12+</sup> | "HwMnoteFrontCamera" | **读写能力：** 只读<br> 是否是前置相机自拍。| 8190| ROLL_ANGLE <sup>11+</sup> | "HwMnoteRollAngle" | **读写能力：** 只读<br> 滚动角度。| 8191| PITCH_ANGLE<sup>11+</sup> | "HwMnotePitchAngle" | **读写能力：** 只读<br> 俯仰角度。| 8192| PHYSICAL_APERTURE <sup>10+</sup> | "HwMnotePhysicalAperture" | **读写能力：** 只读<br> 物理孔径，光圈大小。| 8193| FOCUS_MODE<sup>11+</sup> | "HwMnoteFocusMode" | **读写能力：** 只读<br> 对焦模式。| 8194| USER_COMMENT <sup>10+</sup> | "UserComment" | **读写能力：** 可读写<br> 用户注释。| 8195| SUBSEC_TIME <sup>12+</sup> | "SubsecTime" | **读写能力：** 可读写<br> 用于为DateTime标签记录秒的分数的标签。| 8196| SUBSEC_TIME_ORIGINAL <sup>12+</sup> | "SubsecTimeOriginal" | **读写能力：** 可读写<br> 用于为DateTimeOriginal标签记录秒的分数的标签。| 8197| SUBSEC_TIME_DIGITIZED <sup>12+</sup> | "SubsecTimeDigitized" | **读写能力：** 可读写<br> 用于为DateTimeDigitized标签记录秒的分数的标签。| 8198| FLASHPIX_VERSION <sup>12+</sup> | "FlashpixVersion" | **读写能力：** 可读写<br> 该标签表示FPXR文件支持的Flashpix格式版本，增强了设备兼容性。| 8199| COLOR_SPACE <sup>12+</sup> | "ColorSpace" | **读写能力：** 可读写<br> 色彩空间信息标签，通常记录为色彩空间指定符。| 8200| PIXEL_X_DIMENSION <sup>10+</sup> | "PixelXDimension" | **读写能力：** 可读写<br> 像素X尺寸。| 8201| PIXEL_Y_DIMENSION<sup>10+</sup> | "PixelYDimension" | **读写能力：** 可读写<br> 像素Y尺寸。| 8202| RELATED_SOUND_FILE <sup>12+</sup> | "RelatedSoundFile" | **读写能力：** 可读写<br> 与图像数据相关的音频文件的名称。| 8203| FLASH_ENERGY <sup>12+</sup> | "FlashEnergy" | **读写能力：** 可读写<br> 图像捕获时的闪光能量，以BCPS表示。| 8204| SPATIAL_FREQUENCY_RESPONSE <sup>12+</sup> | "SpatialFrequencyResponse" | **读写能力：** 可读写<br> 相机或输入设备的空间频率表。| 8205| FOCAL_PLANE_X_RESOLUTION <sup>12+</sup> | "FocalPlaneXResolution" | **读写能力：** 可读写<br> 图像宽度中每FocalPlaneResolutionUnit的像素。| 8206| FOCAL_PLANE_Y_RESOLUTION <sup>12+</sup> | "FocalPlaneYResolution" | **读写能力：** 可读写<br> 图像高度中每FocalPlaneResolutionUnit的像素。| 8207| FOCAL_PLANE_RESOLUTION_UNIT <sup>12+</sup> | "FocalPlaneResolutionUnit" | **读写能力：** 可读写<br> 测量FocalPlaneXResolution和FocalPlaneYResolution的单位。| 8208| SUBJECT_LOCATION <sup>12+</sup> | "SubjectLocation" | **读写能力：** 可读写<br> 主要对象相对于左边缘的位置。| 8209| EXPOSURE_INDEX <sup>12+</sup> | "ExposureIndex" | **读写能力：** 可读写<br> 捕获时选定的曝光指数。| 8210| SENSING_METHOD <sup>12+</sup> | "SensingMethod" | **读写能力：** 可读写<br> 相机上的图像传感器类型。| 8211| FILE_SOURCE <sup>12+</sup> | "FileSource" | **读写能力：** 可读写<br> 表明图像来源。| 8212| SCENE_TYPE<sup>9+</sup> | "SceneType" | **读写能力：** 可读写<br> 拍摄场景模式，例如人像、风光、运动、夜景等。| 8213| CFA_PATTERN <sup>12+</sup> | "CFAPattern" | **读写能力：** 可读写<br> 图像传感器的色彩滤光片（CFA）几何图案。| 8214| CUSTOM_RENDERED <sup>12+</sup> | "CustomRendered" | **读写能力：** 可读写<br> 指示图像数据上的特殊处理。| 8215| EXPOSURE_MODE <sup>12+</sup> | "ExposureMode" | **读写能力：** 可读写<br> 拍摄时设置的曝光模式。| 8216| WHITE_BALANCE <sup>10+</sup> | "WhiteBalance" | **读写能力：** 可读写<br> 白平衡。| 8217| DIGITAL_ZOOM_RATIO <sup>12+</sup> | "DigitalZoomRatio" | **读写能力：** 可读写<br> 捕获时的数字变焦比率。| 8218| FOCAL_LENGTH_IN_35_MM_FILM <sup>10+</sup> | "FocalLengthIn35mmFilm" | **读写能力：** 可读写<br> 焦距35毫米胶片。| 8219| SCENE_CAPTURE_TYPE <sup>12+</sup> | "SceneCaptureType" | **读写能力：** 可读写<br> 捕获的场景类型。| 8220| GAIN_CONTROL <sup>12+</sup> | "GainControl" | **读写能力：** 可读写<br> 整体图像增益调整的程度。| 8221| CONTRAST <sup>12+</sup> | "Contrast" | **读写能力：** 可读写<br> 相机应用的对比度处理方向。| 8222| SATURATION <sup>12+</sup> | "Saturation" | **读写能力：** 可读写<br> 相机应用的饱和度处理方向。| 8223| SHARPNESS <sup>12+</sup> | "Sharpness" | **读写能力：** 可读写<br> 相机应用的锐度处理方向。| 8224| DEVICE_SETTING_DESCRIPTION <sup>12+</sup> | "DeviceSettingDescription" | **读写能力：** 可读写<br> 特定相机模型的拍照条件信息。| 8225| SUBJECT_DISTANCE_RANGE <sup>12+</sup> | "SubjectDistanceRange" | **读写能力：** 可读写<br> 表示主体到相机的距离范围。| 8226| IMAGE_UNIQUE_ID <sup>12+</sup> | "ImageUniqueID" | **读写能力：** 可读写<br> 为每张图片唯一分配的标识符。| 8227| CAMERA_OWNER_NAME <sup>12+</sup> | "CameraOwnerName" | **读写能力：** 可读写<br> 相机所有者的姓名。| 8228| BODY_SERIAL_NUMBER <sup>12+</sup> | "BodySerialNumber" | **读写能力：** 可读写<br> 相机机身的序列号。| 8229| LENS_SPECIFICATION <sup>12+</sup> | "LensSpecification" | **读写能力：** 可读写<br> 使用的镜头规格。| 8230| LENS_MAKE <sup>12+</sup> | "LensMake" | **读写能力：** 可读写<br> 镜头的制造商。| 8231| LENS_MODEL <sup>12+</sup> | "LensModel" | **读写能力：** 可读写<br> 镜头的型号名称。| 8232| LENS_SERIAL_NUMBER <sup>12+</sup> | "LensSerialNumber" | **读写能力：** 可读写<br> 镜头的序列号。| 8233| COMPOSITE_IMAGE <sup>12+</sup> | "CompositeImage" | **读写能力：** 可读写<br> 表示图像是否为合成图像。| 8234| SOURCE_IMAGE_NUMBER_OF_COMPOSITE_IMAGE <sup>12+</sup> | "SourceImageNumberOfCompositeImage" | **读写能力：** 可读写<br> 用于合成图像的源图像数量。| 8235| SOURCE_EXPOSURE_TIMES_OF_COMPOSITE_IMAGE <sup>12+</sup> | "SourceExposureTimesOfCompositeImage" | **读写能力：** 可读写<br> 合成图像的源图像曝光时间。| 8236| GAMMA <sup>12+</sup> | "Gamma" | **读写能力：** 可读写<br> 表示系数伽马的值。| 8237| DNG_VERSION <sup>12+</sup> | "DNGVersion" | **读写能力：** 可读写<br> DNG版本标签编码了符合DNG规范的四级版本号。| 8238| DEFAULT_CROP_SIZE <sup>12+</sup> | "DefaultCropSize" | **读写能力：** 可读写<br> DefaultCropSize指定了原始坐标中的最终图像大小，考虑了额外的边缘像素。| 8239| GIF_LOOP_COUNT <sup>12+</sup> | "GIFLoopCount" | **读写能力：** 只读<br> GIF图片循环次数。0表示无限循环，其他值表示循环次数。| 8240| IS_XMAGE_SUPPORTED <sup>12+</sup> | "HwMnoteIsXmageSupported" | **读写能力：** 可读写<br>是否支持XMAGE。 | 8241| XMAGE_MODE <sup>12+</sup> | "HwMnoteXmageMode" | **读写能力：** 可读写<br>XMAGE水印模式。 | 8242| XMAGE_LEFT <sup>12+</sup> | "HwMnoteXmageLeft" | **读写能力：** 可读写<br>水印区域X1坐标。 | 8243| XMAGE_TOP <sup>12+</sup> | "HwMnoteXmageTop" | **读写能力：** 可读写<br>水印区域Y1坐标。 | 8244| XMAGE_RIGHT <sup>12+</sup> | "HwMnoteXmageRight" | **读写能力：** 可读写<br>水印区域X2坐标。 | 8245| XMAGE_BOTTOM <sup>12+</sup> | "HwMnoteXmageBottom" | **读写能力：** 可读写<br>水印区域Y2坐标。 | 8246| CLOUD_ENHANCEMENT_MODE <sup>12+</sup> | "HwMnoteCloudEnhancementMode" | **读写能力：** 可读写<br>云增强模式。 | 8247| WIND_SNAPSHOT_MODE <sup>12+</sup> | "HwMnoteWindSnapshotMode" | **读写能力：** 只读<br>运动快拍模式。 | 8248 8249## FragmentMapPropertyKey<sup>13+</sup> 8250 8251枚举，水印裁剪图图片信息。 8252 8253**系统能力：** SystemCapability.Multimedia.Image.Core 8254 8255| 名称 | 值 | 说明 | 8256| ------------- | --------------------- | ----------------------------------- | 8257| X_IN_ORIGINAL | "XInOriginal" | 水印裁剪图左上角在原始图中的X坐标。 | 8258| Y_IN_ORIGINAL | "YInOriginal" | 水印裁剪图左上角在原始图中的Y坐标。 | 8259| WIDTH | "FragmentImageWidth" | 水印裁剪图的宽。 | 8260| HEIGHT | "FragmentImageHeight" | 水印裁剪图的高。 | 8261 8262## ImageFormat<sup>9+</sup> 8263 8264枚举，图片格式。 8265 8266**系统能力：** SystemCapability.Multimedia.Image.Core 8267 8268| 名称 | 值 | 说明 | 8269| ------------ | ------ | -------------------- | 8270| YCBCR_422_SP | 1000 | YCBCR422半平面格式。 | 8271| JPEG | 2000 | JPEG编码格式。 | 8272 8273## ComponentType<sup>9+</sup> 8274 8275枚举，图像的组件类型。 8276 8277**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 8278 8279| 名称 | 值 | 说明 | 8280| ----- | ------ | ----------- | 8281| YUV_Y | 1 | 亮度信息。 | 8282| YUV_U | 2 | 色度信息。 | 8283| YUV_V | 3 | 色度信息。 | 8284| JPEG | 4 | JPEG 类型。 | 8285 8286## Component<sup>9+</sup> 8287 8288描述图像颜色分量。 8289 8290**系统能力：** SystemCapability.Multimedia.Image.Core 8291 8292| 名称 | 类型 | 只读 | 可选 | 说明 | 8293| ------------- | -------------------------------- | ---- | ---- | ------------ | 8294| componentType | [ComponentType](#componenttype9) | 是 | 否 | 组件类型。 | 8295| rowStride | number | 是 | 否 | 行距。读取相机预览流数据时，需要考虑按stride进行读取，具体用法见[ArkTS双路预览示例](../../media/camera/camera-dual-channel-preview.md)。 | 8296| pixelStride | number | 是 | 否 | 像素间距。 | 8297| byteBuffer | ArrayBuffer | 是 | 否 | 组件缓冲区。 | 8298 8299## DecodingDynamicRange<sup>12+</sup> 8300 8301描述解码时期望的图像动态范围。 8302 8303**系统能力：** SystemCapability.Multimedia.Image.Core 8304 8305| 名称 | 值 | 说明 | 8306| ------------- | ----------| ------------ | 8307| AUTO | 0 | 自适应，根据图片信息处理。即如果图片本身为HDR图片，则会按照HDR内容解码；反之按照SDR内容解码。通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource会解码为SDR内容。 | 8308| SDR | 1 | 按照标准动态范围处理图片。 | 8309| HDR | 2 | 按照高动态范围处理图片。通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource会解码为SDR内容。 | 8310 8311## PackingDynamicRange<sup>12+</sup> 8312 8313描述编码时期望的图像动态范围。 8314 8315**系统能力：** SystemCapability.Multimedia.Image.Core 8316 8317| 名称 | 值 | 说明 | 8318| ------------- | ----------| ------------ | 8319| AUTO | 0 | 自适应，根据[pixelmap](#pixelmap7)内容处理。即如果pixelmap本身为HDR，则会按照HDR内容进行编码；反之按照SDR内容编码。 | 8320| SDR | 1 | 按照标准动态范围处理图片。 | 8321 8322## HdrMetadataKey<sup>12+</sup> 8323 8324枚举，[pixelmap](#pixelmap7)使用的HDR相关元数据信息的关键字。 8325 8326**系统能力：** SystemCapability.Multimedia.Image.Core 8327 8328| 名称 | 值 | 说明 | 8329| ------------- | ----------| ------------ | 8330| HDR_METADATA_TYPE | 0 | [pixelmap](#pixelmap7)使用的元数据类型。 | 8331| HDR_STATIC_METADATA | 1 | 静态元数据。 | 8332| HDR_DYNAMIC_METADATA | 2 | 动态元数据。 | 8333| HDR_GAINMAP_METADATA | 3 | Gainmap使用的元数据。 | 8334 8335## HdrMetadataType<sup>12+</sup> 8336 8337枚举，[HdrMetadataKey](#hdrmetadatakey12)中HDR_METADATA_TYPE关键字对应的值。 8338 8339**系统能力：** SystemCapability.Multimedia.Image.Core 8340 8341| 名称 | 值 | 说明 | 8342| ------------- | ----------| ------------ | 8343| NONE | 0 | 无元数据内容。 | 8344| BASE | 1 | 表示用于基础图的元数据。 | 8345| GAINMAP | 2 | 表示用于Gainmap图的元数据。 | 8346| ALTERNATE| 3 | 表示用于合成后HDR图的元数据。 | 8347 8348## HdrStaticMetadata<sup>12+</sup> 8349 8350静态元数据值，[HdrMetadataKey](#hdrmetadatakey12)中HDR_STATIC_METADATA关键字对应的值。 8351 8352**系统能力：** SystemCapability.Multimedia.Image.Core 8353 8354| 名称 | 类型 | 只读 | 可选 | 说明 | 8355| ------------- | ----------| -- | -- | ------------ | 8356| displayPrimariesX | Array\<number> | 否 | 否 | 归一化后显示设备三基色的X坐标，数组的长度为3，以0.00002为单位，范围[0.0, 1.0]。 | 8357| displayPrimariesY | Array\<number> | 否 | 否 | 归一化后显示设备三基色的Y坐标，数组的长度为3，以0.00002为单位，范围[0.0, 1.0]。 | 8358| whitePointX | number | 否 | 否 | 归一化后白点值的X坐标，以0.00002为单位，范围[0.0, 1.0]。 | 8359| whitePointY | number | 否 | 否 | 归一化后白点值的Y坐标，以0.00002为单位，范围[0.0, 1.0]。 | 8360| maxLuminance | number | 否 | 否 | 图像主监视器最大亮度。以1为单位，最大值为65535。 | 8361| minLuminance | number | 否 | 否 | 图像主监视器最小亮度。以0.0001为单位，最大值6.55535。 | 8362| maxContentLightLevel | number | 否 | 否 | 显示内容的最大亮度。以1为单位，最大值为65535。 | 8363| maxFrameAverageLightLevel | number | 否 | 否 | 显示内容的最大平均亮度，以1为单位，最大值为65535。 | 8364 8365## GainmapChannel<sup>12+</sup> 8366 8367Gainmap图单个通道的数据内容，参考ISO 21496-1。 8368 8369**系统能力：** SystemCapability.Multimedia.Image.Core 8370 8371| 名称 | 类型 | 只读 | 可选 | 说明 | 8372| ------------- | ----------| -- | -- | ------------ | 8373| gainmapMax | number | 否 | 否 | 增强图像的最大值，参考ISO 21496-1。 | 8374| gainmapMin | number | 否 | 否 | 增强图像的最小值，参考ISO 21496-1。 | 8375| gamma | number | 否 | 否 | gamma值，参考ISO 21496-1。 | 8376| baseOffset | number | 否 | 否 | 基础图的偏移，参考ISO 21496-1。 | 8377| alternateOffset | number | 否 | 否 | 提取的可选择图像偏移量，参考ISO 21496-1。 | 8378 8379## HdrGainmapMetadata<sup>12+</sup> 8380 8381Gainmap使用的元数据值，[HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的值，参考ISO 21496-1。 8382 8383**系统能力：** SystemCapability.Multimedia.Image.Core 8384 8385| 名称 | 类型 | 只读 | 可选 | 说明 | 8386| ------------- | ----------| -- | -- | ------------ | 8387| writerVersion | number | 否 | 否 | 元数据编写器使用的版本。 | 8388| miniVersion | number | 否 | 否 | 元数据解析需要理解的最小版本。 | 8389| gainmapChannelCount | number | 否 | 否 | Gainmap的颜色通道数，值为3时RGB通道的元数据值不同，值为1时各通道元数据值相同，参考ISO 21496-1。 | 8390| useBaseColorFlag | boolean | 否 | 否 | 是否使用基础图的色彩空间，参考ISO 21496-1。 | 8391| baseHeadroom | number | 否 | 否 | 基础图提亮比，参考ISO 21496-1。 | 8392| alternateHeadroom | number | 否 | 否 | 提取的可选择图像提亮比，参考ISO 21496-1。 | 8393| channels | Array<[GainmapChannel](#gainmapchannel12)> | 否 | 否 | 各通道的数据，长度为3，参考ISO 21496-1。 | 8394 8395## HdrMetadataValue<sup>12+</sup> 8396 8397type HdrMetadataValue = HdrMetadataType | HdrStaticMetadata | ArrayBuffer | HdrGainmapMetadata 8398 8399PixelMap使用的HDR元数据值类型，和[HdrMetadataKey](#hdrmetadatakey12)关键字相对应。 8400 8401**系统能力：** SystemCapability.Multimedia.Image.Core 8402 8403| 类型 | 说明 | 8404| ------------------- | ----------------------------------------------- | 8405| [HdrMetadataType](#hdrmetadatatype12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的元数据值类型。 | 8406| [HdrStaticMetadata](#hdrstaticmetadata12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_STATIC_METADATA关键字对应的元数据值类型。 | 8407| ArrayBuffer | [HdrMetadataKey](#hdrmetadatakey12)中HDR_DYNAMIC_METADATA关键字对应的元数据值类型。 | 8408| [HdrGainmapMetadata](#hdrgainmapmetadata12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的元数据值类型。 | 8409 8410## AntiAliasingLevel<sup>12+</sup> 8411 8412缩放时的缩放算法。 8413 8414**原子化服务API**：从API version 14 开始，该接口支持在原子化服务中使用。 8415 8416**系统能力：** SystemCapability.Multimedia.Image.Core 8417 8418| 名称 | 值 | 说明 | 8419| ---------------------- | ------ | ----------------- | 8420| NONE | 0 | 最近邻插值算法。 | 8421| LOW | 1 | 双线性插值算法。 | 8422| MEDIUM | 2 | 双线性插值算法，同时开启Mipmap。缩小图片时建议使用。 | 8423| HIGH | 3 | 三次插值算法。 | 8424 8425## AllocatorType<sup>15+</sup> 8426 8427枚举，用于图像解码的内存类型。 8428 8429**系统能力：** SystemCapability.Multimedia.Image.Core 8430 8431| 名称 | 值 | 说明 | 8432| ------------ | ---- | ---------------------------------- | 8433| AUTO | 0 | 系统决定内存申请方式。 | 8434| DMA | 1 | 使用DMA内存申请方式。 | 8435| SHARE_MEMORY | 2 | 使用SHARE_MEMORY的内存申请方式。 | 8436 8437## 补充说明 8438### SVG标签说明 8439 8440从API version 10开始支持SVG标签，使用版本为(SVG) 1.1，SVG文件需添加xml声明，应以“<?xml”开头，并且SVG标签需设置width，height。当前支持的标签列表有： 8441- a 8442- circla 8443- clipPath 8444- defs 8445- ellipse 8446- feBlend 8447- feColorMatrix 8448- feComposite 8449- feDiffuseLighting 8450- feDisplacementMap 8451- feDistantLight 8452- feFlood 8453- feGaussianBlur 8454- feImage 8455- feMorphology 8456- feOffset 8457- fePointLight 8458- feSpecularLighting 8459- feSpotLight 8460- feTurbulence 8461- filter 8462- g 8463- image 8464- line 8465- linearGradient 8466- mask 8467- path 8468- pattern 8469- polygon 8470- polyline 8471- radialGradient 8472- rect 8473- stop 8474- svg 8475- text 8476- textPath 8477- tspan 8478- use
