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(context: Context) { 51 const resourceMgr = context.resourceManager; 52 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 53 let ops: image.SourceOptions = { 54 sourceDensity: 98, 55 } 56 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 57 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 58 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 59 if (pictureObj != null) { 60 console.info('Create picture succeeded'); 61 } else { 62 console.info('Create picture failed'); 63 } 64} 65``` 66 67## image.createPictureFromParcel<sup>13+</sup> 68 69createPictureFromParcel(sequence: rpc.MessageSequence): Picture 70 71从MessageSequence中获取Picture。 72 73**系统能力：** SystemCapability.Multimedia.Image.Core 74 75**参数：** 76 77| 参数名 | 类型 | 必填 | 说明 | 78| -------- | ------------------------------------------------------------------- | ---- | ------------------------------------ | 79| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有Picture信息的MessageSequence。 | 80 81**返回值：** 82 83| 类型 | 说明 | 84| ------------------ | ----------------- | 85| [Picture](#picture13) | 返回Picture对象。 | 86 87**错误码：** 88 89以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 90 91| 错误码ID | 错误信息 | 92| -------- | ------------------------------------------------------------ | 93| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. | 94| 62980097 | IPC error. | 95 96**示例：** 97 98```ts 99import { rpc } from '@kit.IPCKit'; 100import { BusinessError } from '@kit.BasicServicesKit'; 101import { image } from '@kit.ImageKit'; 102 103class MySequence implements rpc.Parcelable { 104 picture: image.Picture | null = null; 105 constructor(conPicture: image.Picture) { 106 this.picture = conPicture; 107 } 108 marshalling(messageSequence: rpc.MessageSequence) { 109 if(this.picture != null) { 110 this.picture.marshalling(messageSequence); 111 console.info('Marshalling success !'); 112 return true; 113 } else { 114 console.info('Marshalling failed !'); 115 return false; 116 } 117 } 118 unmarshalling(messageSequence : rpc.MessageSequence) { 119 this.picture = image.createPictureFromParcel(messageSequence); 120 this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => { 121 console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 122 }).catch((error: BusinessError) => { 123 console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}'); 124 }); 125 return true; 126 } 127} 128 129async function Marshalling_UnMarshalling(context: Context) { 130 const resourceMgr = context.resourceManager; 131 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 132 let ops: image.SourceOptions = { 133 sourceDensity: 98, 134 } 135 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 136 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 137 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 138 if (pictureObj != null) { 139 let parcelable: MySequence = new MySequence(pictureObj); 140 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 141 // marshalling. 142 data.writeParcelable(parcelable); 143 let ret: MySequence = new MySequence(pictureObj); 144 // unmarshalling. 145 data.readParcelable(ret); 146 } else { 147 console.info('PictureObj is null'); 148 } 149} 150``` 151 152## image.createPixelMap<sup>8+</sup> 153 154createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise\<PixelMap> 155 156通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过Promise返回结果。 157 158**系统能力：** SystemCapability.Multimedia.Image.Core 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 164| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 165| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 166 167**返回值：** 168 169| 类型 | 说明 | 170| -------------------------------- | ----------------------------------------------------------------------- | 171| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。<br>当创建的pixelMap大小超过原图大小时，返回原图pixelMap大小。| 172 173**示例：** 174 175```ts 176import { BusinessError } from '@kit.BasicServicesKit'; 177 178async function CreatePixelMap() { 179 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 180 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 181 image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 182 console.info('Succeeded in creating pixelmap.'); 183 }).catch((error: BusinessError) => { 184 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 185 }) 186} 187``` 188 189## image.createPixelMap<sup>8+</sup> 190 191createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback\<PixelMap>): void 192 193通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，通过callback返回结果。 194 195**系统能力：** SystemCapability.Multimedia.Image.Core 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| -------- | ------------------------------------------------ | ---- | -------------------------- | 201| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 202| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 203| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 204 205**示例：** 206 207```ts 208import { BusinessError } from '@kit.BasicServicesKit'; 209 210async function CreatePixelMap() { 211 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 212 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 213 image.createPixelMap(color, opts, (error: BusinessError, pixelMap: image.PixelMap) => { 214 if(error) { 215 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 216 return; 217 } else { 218 console.info('Succeeded in creating pixelmap.'); 219 } 220 }) 221} 222``` 223 224## image.createPixelMapFromParcel<sup>11+</sup> 225 226createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap 227 228从MessageSequence中获取PixelMap。 229 230**系统能力：** SystemCapability.Multimedia.Image.Core 231 232**参数：** 233 234| 参数名 | 类型 | 必填 | 说明 | 235| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 236| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 237 238**返回值：** 239 240| 类型 | 说明 | 241| -------------------------------- | --------------------- | 242| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 243 244**错误码：** 245 246以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 247 248| 错误码ID | 错误信息 | 249| ------- | --------------------------------------------| 250| 62980096 | Operation failed.| 251| 62980097 | IPC error.| 252| 62980115 | Invalid input parameter.| 253| 62980105 | Failed to get the data.| 254| 62980177 | Abnormal API environment.| 255| 62980178 | Failed to create the PixelMap.| 256| 62980179 | Abnormal buffer size.| 257| 62980180 | FD mapping failed.| 258| 62980246 | Failed to read the PixelMap.| 259 260**示例：** 261 262```ts 263import { image } from '@kit.ImageKit'; 264import { rpc } from '@kit.IPCKit'; 265import { BusinessError } from '@kit.BasicServicesKit'; 266 267class MySequence implements rpc.Parcelable { 268 pixel_map: image.PixelMap; 269 constructor(conPixelmap: image.PixelMap) { 270 this.pixel_map = conPixelmap; 271 } 272 marshalling(messageSequence: rpc.MessageSequence) { 273 this.pixel_map.marshalling(messageSequence); 274 return true; 275 } 276 unmarshalling(messageSequence: rpc.MessageSequence) { 277 try { 278 this.pixel_map = image.createPixelMapFromParcel(messageSequence); 279 } catch(e) { 280 let error = e as BusinessError; 281 console.error(`createPixelMapFromParcel error. code is ${error.code}, message is ${error.message}`); 282 return false; 283 } 284 return true; 285 } 286} 287async function CreatePixelMapFromParcel() { 288 const color: ArrayBuffer = new ArrayBuffer(96); 289 let bufferArr: Uint8Array = new Uint8Array(color); 290 for (let i = 0; i < bufferArr.length; i++) { 291 bufferArr[i] = 0x80; 292 } 293 let opts: image.InitializationOptions = { 294 editable: true, 295 pixelFormat: image.PixelMapFormat.BGRA_8888, 296 size: { height: 4, width: 6 }, 297 alphaType: image.AlphaType.UNPREMUL 298 } 299 let pixelMap: image.PixelMap | undefined = undefined; 300 image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 301 pixelMap = srcPixelMap; 302 }) 303 if (pixelMap != undefined) { 304 // 序列化。 305 let parcelable: MySequence = new MySequence(pixelMap); 306 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 307 data.writeParcelable(parcelable); 308 309 // 反序列化 rpc获取到data。 310 let ret: MySequence = new MySequence(pixelMap); 311 data.readParcelable(ret); 312 313 // 获取到pixelmap。 314 let unmarshPixelmap = ret.pixel_map; 315 } 316} 317``` 318 319## image.createPixelMapFromSurface<sup>11+</sup> 320 321createPixelMapFromSurface(surfaceId: string, region: Region): Promise\<PixelMap> 322 323根据Surface id和区域信息，创建一个PixelMap对象。该区域的大小由[Region](#region8).size指定。使用Promise形式返回。 324 325> **说明：** 326> 当开发设备为折叠屏，折叠状态切换时，可能因Surface自带旋转角度导致接口创建失败，需将宽高适配旋转角度。推荐使用[image.createPixelMapFromSurface](#imagecreatepixelmapfromsurface15) 327 328**系统能力：** SystemCapability.Multimedia.Image.Core 329 330**参数：** 331 332| 参数名 | 类型 | 必填 | 说明 | 333| ---------------------- | ------------- | ---- | ---------------------------------------- | 334| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 335| region | [Region](#region8) | 是 | 区域信息。[Region](#region8).size的宽高需和设置的预览流大小保持一致。 | 336 337**返回值：** 338| 类型 | 说明 | 339| -------------------------------- | --------------------- | 340| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 341 342**错误码：** 343 344以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 345 346| 错误码ID | 错误信息 | 347| ------- | --------------------------------------------| 348| 62980115 | If the image parameter invalid.| 349| 62980105 | Failed to get the data.| 350| 62980178 | Failed to create the PixelMap.| 351 352**示例：** 353 354```ts 355import { BusinessError } from '@kit.BasicServicesKit'; 356 357async function CreatePixelMapFromSurface(surfaceId: string) { 358 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 359 image.createPixelMapFromSurface(surfaceId, region).then(() => { 360 console.info('Succeeded in creating pixelmap from Surface'); 361 }).catch((error: BusinessError) => { 362 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 363 }); 364} 365``` 366 367## image.createPixelMapFromSurfaceSync<sup>12+</sup> 368 369createPixelMapFromSurfaceSync(surfaceId: string, region: Region): PixelMap 370 371以同步方式，根据Surface id和区域信息，创建一个PixelMap对象。该区域的大小由[Region](#region8).size指定。 372 373> **说明：** 374> 当开发设备为折叠屏，折叠状态切换时，可能因Surface自带旋转角度导致接口创建失败，需将宽高适配旋转角度。推荐使用[image.createPixelMapFromSurfaceSync](#imagecreatepixelmapfromsurfacesync15)。 375 376**系统能力：** SystemCapability.Multimedia.Image.Core 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| ---------------------- | ------------- | ---- | ---------------------------------------- | 382| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 383| region | [Region](#region8) | 是 | 区域信息。[Region](#region8).size的宽高需和设置的预览流大小保持一致。 | 384 385**返回值：** 386| 类型 | 说明 | 387| -------------------------------- | --------------------- | 388| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 389 390**错误码：** 391 392以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 393 394| 错误码ID | 错误信息 | 395| ------- | --------------------------------------------| 396| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 397| 62980105 | Failed to get the data.| 398| 62980178 | Failed to create the PixelMap.| 399 400**示例：** 401 402```ts 403import { BusinessError } from '@kit.BasicServicesKit'; 404 405async function Demo(surfaceId: string) { 406 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 407 let pixelMap : image.PixelMap = image.createPixelMapFromSurfaceSync(surfaceId, region); 408 return pixelMap; 409} 410``` 411 412## image.createPixelMapFromSurface<sup>15+</sup> 413 414createPixelMapFromSurface(surfaceId: string): Promise\<PixelMap> 415 416从Surface id创建一个PixelMap对象。使用Promise异步回调，返回PixelMap。 417 418**系统能力：** SystemCapability.Multimedia.Image.Core 419 420**参数：** 421 422| 参数名 | 类型 | 必填 | 说明 | 423| ---------------------- | ------------- | ---- | ---------------------------------------- | 424| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 425 426**返回值：** 427| 类型 | 说明 | 428| -------------------------------- | --------------------- | 429| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 430 431**错误码：** 432 433以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 434 435| 错误码ID | 错误信息 | 436| ------- | --------------------------------------------| 437| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 438| 62980105 | Failed to get the data| 439| 62980178 | Failed to create the PixelMap| 440 441**示例：** 442 443```ts 444import { BusinessError } from '@kit.BasicServicesKit'; 445 446async function Demo(surfaceId: string) { 447 image.createPixelMapFromSurface(surfaceId).then(() => { 448 console.info('Succeeded in creating pixelmap from Surface'); 449 }).catch((error: BusinessError) => { 450 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 451 }); 452} 453``` 454 455## image.createPixelMapFromSurfaceSync<sup>15+</sup> 456 457createPixelMapFromSurfaceSync(surfaceId: string): PixelMap 458 459从Surface id创建一个pixelMap对象，同步返回PixelMap结果。 460 461**系统能力：** SystemCapability.Multimedia.Image.Core 462 463**参数：** 464 465| 参数名 | 类型 | 必填 | 说明 | 466| ---------------------- | ------------- | ---- | ---------------------------------------- | 467| surfaceId | string | 是 | 对应Surface的ID，可通过预览组件获取，如[XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md)组件。 | 468 469**返回值：** 470| 类型 | 说明 | 471| -------------------------------- | --------------------- | 472| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 473 474**错误码：** 475 476以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 477 478| 错误码ID | 错误信息 | 479| ------- | --------------------------------------------| 480| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 481| 62980105 | Failed to get the data| 482| 62980178 | Failed to create the PixelMap| 483 484**示例：** 485 486```ts 487import { BusinessError } from '@kit.BasicServicesKit'; 488 489async function Demo(surfaceId: string) { 490 let pixelMap : image.PixelMap = image.createPixelMapFromSurfaceSync(surfaceId); 491 return pixelMap; 492} 493``` 494## image.createPixelMapSync<sup>12+</sup> 495 496createPixelMapSync(colors: ArrayBuffer, options: InitializationOptions): PixelMap 497 498通过属性创建PixelMap，默认采用BGRA_8888格式处理数据，同步返回结果。 499 500**系统能力：** SystemCapability.Multimedia.Image.Core 501 502**参数：** 503 504| 参数名 | 类型 | 必填 | 说明 | 505| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 506| colors | ArrayBuffer | 是 | 图像像素数据的缓冲区，用于初始化PixelMap的像素。初始化前，缓冲区中的像素格式需要由[InitializationOptions](#initializationoptions8).srcPixelFormat指定。<br>**说明：** 图像像素数据的缓冲区长度：length = width * height * 单位像素字节数。 | 507| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 508 509**返回值：** 510| 类型 | 说明 | 511| -------------------------------- | --------------------- | 512| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 513 514**错误码：** 515 516以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 517 518| 错误码ID | 错误信息 | 519| ------- | --------------------------------------------| 520| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 521 522**示例：** 523 524```ts 525import { BusinessError } from '@kit.BasicServicesKit'; 526 527async function CreatePixelMapSync() { 528 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 529 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 530 let pixelMap : image.PixelMap = image.createPixelMapSync(color, opts); 531 return pixelMap; 532} 533``` 534 535## image.createPixelMapSync<sup>12+</sup> 536 537createPixelMapSync(options: InitializationOptions): PixelMap 538 539通过属性创建PixelMap，同步返回PixelMap结果。 540 541**系统能力：** SystemCapability.Multimedia.Image.Core 542 543**参数：** 544 545| 参数名 | 类型 | 必填 | 说明 | 546| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 547| options | [InitializationOptions](#initializationoptions8) | 是 | 创建像素的属性，包括透明度，尺寸，缩略值，像素格式和是否可编辑。 | 548 549**返回值：** 550| 类型 | 说明 | 551| -------------------------------- | --------------------- | 552| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 553 554**错误码：** 555 556以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 557 558| 错误码ID | 错误信息 | 559| ------- | --------------------------------------------| 560| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 561 562**示例：** 563 564```ts 565import { BusinessError } from '@kit.BasicServicesKit'; 566 567async function CreatePixelMapSync() { 568 let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 569 let pixelMap : image.PixelMap = image.createPixelMapSync(opts); 570 return pixelMap; 571} 572``` 573 574## image.createPremultipliedPixelMap<sup>12+</sup> 575 576createPremultipliedPixelMap(src: PixelMap, dst: PixelMap, callback: AsyncCallback\<void>): void 577 578将PixelMap的透明通道非预乘模式转变为预乘模式，转换后的数据存入目标PixelMap，通过回调函数返回结果。 579 580**系统能力：** SystemCapability.Multimedia.Image.Core 581 582**参数：** 583 584| 参数名 | 类型 | 必填 | 说明 | 585| -------- | ------------------------------------------------ | ---- | -------------------------- | 586| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 587| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 588|callback | AsyncCallback\<void> | 是 | 回调函数，当创建PixelMap成功，err为undefined，否则为错误对象。 | 589 590**错误码：** 591 592以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 593 594| 错误码ID | 错误信息 | 595| ------- | --------------------------------------------| 596| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 597| 62980103 | The image data is not supported | 598| 62980246 | Failed to read the pixelMap | 599| 62980248 | Pixelmap not allow modify | 600 601**示例：** 602 603```ts 604import { BusinessError } from '@kit.BasicServicesKit'; 605 606async function CreatePremultipliedPixelMap() { 607 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 608 let bufferArr = new Uint8Array(color); 609 for (let i = 0; i < bufferArr.length; i += 4) { 610 bufferArr[i] = 255; 611 bufferArr[i+1] = 255; 612 bufferArr[i+2] = 122; 613 bufferArr[i+3] = 122; 614 } 615 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 616 let srcPixelmap = image.createPixelMapSync(color, optsForUnpre); 617 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 618 let dstPixelMap = image.createPixelMapSync(optsForPre); 619 image.createPremultipliedPixelMap(srcPixelmap, dstPixelMap, (error: BusinessError) => { 620 if(error) { 621 console.error(`Failed to convert pixelmap, error code is ${error}`); 622 return; 623 } else { 624 console.info('Succeeded in converting pixelmap.'); 625 } 626 }) 627} 628``` 629 630## image.createPremultipliedPixelMap<sup>12+</sup> 631 632createPremultipliedPixelMap(src: PixelMap, dst: PixelMap): Promise\<void> 633 634将PixelMap数据按照透明度非预乘格式转为预乘格式，转换后的数据存入另一个PixelMap，通过Promise返回结果。 635 636**系统能力：** SystemCapability.Multimedia.Image.Core 637 638**参数：** 639 640| 参数名 | 类型 | 必填 | 说明 | 641| -------- | ------------------------------------------------ | ---- | -------------------------- | 642| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 643| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 644 645**返回值：** 646 647| 类型 | 说明 | 648| -------------------------------- | ----------------------------------------------------------------------- | 649| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 650 651**错误码：** 652 653以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 654 655| 错误码ID | 错误信息 | 656| ------- | --------------------------------------------| 657| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 658| 62980103 | The image data is not supported | 659| 62980246 | Failed to read the pixelMap | 660| 62980248 | Pixelmap not allow modify | 661 662**示例：** 663 664```ts 665import { BusinessError } from '@kit.BasicServicesKit'; 666 667async function CreatePremultipliedPixelMap() { 668 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 669 let bufferArr = new Uint8Array(color); 670 for (let i = 0; i < bufferArr.length; i += 4) { 671 bufferArr[i] = 255; 672 bufferArr[i+1] = 255; 673 bufferArr[i+2] = 122; 674 bufferArr[i+3] = 122; 675 } 676 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 677 let srcPixelmap = image.createPixelMapSync(color, optsForUnpre); 678 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 679 let dstPixelMap = image.createPixelMapSync(optsForPre); 680 image.createPremultipliedPixelMap(srcPixelmap, dstPixelMap).then(() => { 681 console.info('Succeeded in converting pixelmap.'); 682 }).catch((error: BusinessError) => { 683 console.error(`Failed to convert pixelmap, error code is ${error}`); 684 }) 685} 686``` 687 688## image.createUnpremultipliedPixelMap<sup>12+</sup> 689 690createUnpremultipliedPixelMap(src: PixelMap, dst: PixelMap, callback: AsyncCallback\<void>): void 691 692将PixelMap的透明通道预乘模式转变为非预乘模式，转换后的数据存入目标PixelMap，通过回调函数返回结果。 693 694**系统能力：** SystemCapability.Multimedia.Image.Core 695 696**参数：** 697 698| 参数名 | 类型 | 必填 | 说明 | 699| -------- | ------------------------------------------------ | ---- | -------------------------- | 700| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 701| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。| 702|callback | AsyncCallback\<void> | 是 | 回调函数，当创建PixelMap成功，err为undefined，否则为错误对象。| 703 704**错误码：** 705 706以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 707 708| 错误码ID | 错误信息 | 709| ------- | --------------------------------------------| 710| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed| 711| 62980103 | The image data is not supported | 712| 62980246 | Failed to read the pixelMap | 713| 62980248 | Pixelmap not allow modify | 714 715**示例：** 716 717```ts 718import { BusinessError } from '@kit.BasicServicesKit'; 719 720async function CreateUnpremultipliedPixelMap() { 721 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 722 let bufferArr = new Uint8Array(color); 723 for (let i = 0; i < bufferArr.length; i += 4) { 724 bufferArr[i] = 255; 725 bufferArr[i+1] = 255; 726 bufferArr[i+2] = 122; 727 bufferArr[i+3] = 122; 728 } 729 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 730 let srcPixelmap = image.createPixelMapSync(color, optsForPre); 731 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 732 let dstPixelMap = image.createPixelMapSync(optsForUnpre); 733 image.createUnpremultipliedPixelMap(srcPixelmap, dstPixelMap, (error: BusinessError) => { 734 if(error) { 735 console.error(`Failed to convert pixelmap, error code is ${error}`); 736 return; 737 } else { 738 console.info('Succeeded in converting pixelmap.'); 739 } 740 }) 741} 742``` 743 744## image.createUnpremultipliedPixelMap<sup>12+</sup> 745 746createUnpremultipliedPixelMap(src: PixelMap, dst: PixelMap): Promise\<void> 747 748将PixelMap的透明通道预乘模式转变为非预乘模式，转换后的数据存入目标PixelMap，通过Promise返回结果。 749 750**系统能力：** SystemCapability.Multimedia.Image.Core 751 752**参数：** 753 754| 参数名 | 类型 | 必填 | 说明 | 755| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 756| src | [PixelMap](#pixelmap7) | 是 | 源PixelMap对象。 | 757| dst | [PixelMap](#pixelmap7) | 是 | 目标PixelMap对象。 | 758 759**返回值：** 760 761| 类型 | 说明 | 762| -------------------------------- | ----------------------------------------------------------------------- | 763| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 764 765**错误码：** 766 767以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 768 769| 错误码ID | 错误信息 | 770| ------- | --------------------------------------------| 771| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 772| 62980103 | The image data is not supported. | 773| 62980246 | Failed to read the pixelMap. | 774| 62980248 | Pixelmap not allow modify. | 775 776**示例：** 777 778```ts 779import { BusinessError } from '@kit.BasicServicesKit'; 780 781async function CreateUnpremultipliedPixelMap() { 782 const color: ArrayBuffer = new ArrayBuffer(16); // 16为需要创建的像素buffer大小，取值为：height * width *4。 783 let bufferArr = new Uint8Array(color); 784 for (let i = 0; i < bufferArr.length; i += 4) { 785 bufferArr[i] = 255; 786 bufferArr[i+1] = 255; 787 bufferArr[i+2] = 122; 788 bufferArr[i+3] = 122; 789 } 790 let optsForPre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.PREMUL} 791 let srcPixelmap = image.createPixelMapSync(color, optsForPre); 792 let optsForUnpre: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 2, width: 2 } , alphaType: image.AlphaType.UNPREMUL} 793 let dstPixelMap = image.createPixelMapSync(optsForUnpre); 794 image.createUnpremultipliedPixelMap(srcPixelmap, dstPixelMap).then(() => { 795 console.info('Succeeded in converting pixelmap.'); 796 }).catch((error: BusinessError) => { 797 console.error(`Failed to convert pixelmap, error code is ${error}`); 798 }) 799} 800``` 801 802 803## Picture<sup>13+</sup> 804 805一些包含特殊信息的图片可以解码为多图对象，多图对象一般包含主图、辅助图和元数据。其中主图包含图像的大部分信息，主要用于显示图像内容；辅助图用于存储与主图相关但不同的数据，展示图像更丰富的信息；元数据一般用来存储关于图像文件的信息。多图对象类用于读取或写入多图对象。在调用Picture的方法前，需要先通过[createPicture](#imagecreatepicture13)创建一个Picture实例。 806 807### 属性 808 809**系统能力：** SystemCapability.Multimedia.Image.Core 810 811### getMainPixelmap<sup>13+</sup> 812 813getMainPixelmap(): PixelMap 814 815获取主图的pixelmap。 816 817**系统能力：** SystemCapability.Multimedia.Image.Core 818 819**返回值：** 820 821| 类型 | 说明 | 822| ------------------- | ---------------------- | 823| [PixelMap](#pixelmap7) | 同步返回PixelMap对象。 | 824 825**示例：** 826 827```ts 828import { BusinessError } from '@kit.BasicServicesKit'; 829import { image } from '@kit.ImageKit'; 830 831async function GetMainPixelmap() { 832 let funcName = "getMainPixelmap"; 833 if (pictureObj != null) { 834 let mainPixelmap: image.PixelMap = pictureObj.getMainPixelmap(); 835 if (mainPixelmap != null) { 836 mainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 837 if (imageInfo != null) { 838 console.info('GetMainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 839 } 840 }).catch((error: BusinessError) => { 841 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 842 }); 843 } 844 } else { 845 console.info('PictureObj is null'); 846 } 847} 848``` 849 850### getHdrComposedPixelmap<sup>13+</sup> 851 852getHdrComposedPixelmap(): Promise\<PixelMap> 853 854合成hdr图并获取hdr图的pixelmap，使用Promise形式返回结果。 855 856**系统能力：** SystemCapability.Multimedia.Image.Core 857 858**返回值：** 859 860| 类型 | 说明 | 861| ----------------------------- | --------------------------- | 862| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 863 864**错误码：** 865 866以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 867 868| 错误码ID | 错误信息 | 869| -------- | ---------------------- | 870| 7600901 | Unknown error. | 871| 7600201 | Unsupported operation. | 872 873**示例：** 874 875```ts 876import { BusinessError } from '@kit.BasicServicesKit'; 877import { image } from '@kit.ImageKit'; 878 879async function GetHdrComposedPixelmap() { 880 let funcName = "getHdrComposedPixelmap"; 881 if (pictureObj != null) { //图片包含Hdr图。 882 let hdrComposedPixelmap: image.PixelMap = await pictureObj.getHdrComposedPixelmap(); 883 if (hdrComposedPixelmap != null) { 884 hdrComposedPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 885 if (imageInfo != null) { 886 console.info('GetHdrComposedPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 887 } 888 }).catch((error: BusinessError) => { 889 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 890 }); 891 } 892 } else { 893 console.info('PictureObj is null'); 894 } 895} 896``` 897 898### getGainmapPixelmap<sup>13+</sup> 899 900getGainmapPixelmap(): PixelMap | null 901 902获取增益图的pixelmap。 903 904**系统能力：** SystemCapability.Multimedia.Image.Core 905 906**返回值：** 907 908| 类型 | 说明 | 909| ------------------------- | -------------------------------------- | 910| [PixelMap](#pixelmap7) \| null | 返回Pixelmap对象，如果没有则返回null。 | 911 912**示例：** 913 914```ts 915import { BusinessError } from '@kit.BasicServicesKit'; 916import { image } from '@kit.ImageKit'; 917 918async function GetGainmapPixelmap() { 919 let funcName = "getGainmapPixelmap"; 920 if (pictureObj != null) { //图片包含增益图。 921 let gainPixelmap: image.PixelMap | null = pictureObj.getGainmapPixelmap(); 922 if (gainPixelmap != null) { 923 gainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => { 924 if (imageInfo != null) { 925 console.info('GetGainmapPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 926 } else { 927 console.info('GainPixelmap is null'); 928 } 929 }).catch((error: BusinessError) => { 930 console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}'); 931 }); 932 } else { 933 console.info('GainPixelmap is null'); 934 } 935 } else { 936 console.info('PictureObj is null'); 937 } 938} 939``` 940 941### setAuxiliaryPicture<sup>13+</sup> 942 943setAuxiliaryPicture(type: AuxiliaryPictureType, auxiliaryPicture: AuxiliaryPicture): void 944 945设置辅助图。 946 947**系统能力：** SystemCapability.Multimedia.Image.Core 948 949**参数：** 950 951| 参数名 | 类型 | 必填 | 说明 | 952| ---------------- | -------------------- | ---- | ------------ | 953| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 954| auxiliaryPicture | [AuxiliaryPicture](#auxiliarypicture13) | 是 | 辅助图对象。 | 955 956**错误码：** 957 958以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 959 960| 错误码ID | 错误信息 | 961| -------- | ------------------------------------------------------------ | 962| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 963 964**示例：** 965 966```ts 967import { image } from '@kit.ImageKit'; 968 969async function SetAuxiliaryPicture(context: Context) { 970 const resourceMgr = context.resourceManager; 971 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg");//需要支持hdr的图片。 972 let ops: image.SourceOptions = { 973 sourceDensity: 98, 974 } 975 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 976 let pixelMap: image.PixelMap = await imageSource.createPixelMap(); 977 let auxPicture: image.Picture = image.createPicture(pixelMap); 978 if (auxPicture != null) { 979 console.info('Create picture succeeded'); 980 } else { 981 console.info('Create picture failed'); 982 } 983 984 if (pictureObj != null) { 985 let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 986 let auxPictureObj: image.AuxiliaryPicture | null = await auxPicture.getAuxiliaryPicture(type); 987 if (auxPictureObj != null) { 988 pictureObj.setAuxiliaryPicture(type, auxPictureObj); 989 } 990 } 991} 992``` 993 994### getAuxiliaryPicture<sup>13+</sup> 995 996getAuxiliaryPicture(type: AuxiliaryPictureType): AuxiliaryPicture | null 997 998根据类型获取辅助图。 999 1000**系统能力：** SystemCapability.Multimedia.Image.Core 1001 1002**参数：** 1003 1004| 参数名 | 类型 | 必填 | 说明 | 1005| ------ | -------------------- | ---- | ------------ | 1006| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 1007 1008**返回值：** 1009 1010| 类型 | 说明 | 1011| ---------------------- | ---------------------------------------------- | 1012| [AuxiliaryPicture](#auxiliarypicture13) \| null | 返回AuxiliaryPicture对象，如果没有则返回null。 | 1013 1014**错误码：** 1015 1016以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1017 1018| 错误码ID | 错误信息 | 1019| -------- | ------------------------------------------------------------ | 1020| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1021 1022**示例：** 1023 1024```ts 1025import { image } from '@kit.ImageKit'; 1026 1027async function GetAuxiliaryPicture() { 1028 if (pictureObj != null) { 1029 let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 1030 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(type); 1031 } 1032} 1033``` 1034 1035### setMetadata<sup>13+</sup> 1036 1037setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void> 1038 1039设置主图的元数据。 1040 1041**系统能力：** SystemCapability.Multimedia.Image.Core 1042 1043**参数：** 1044 1045| 参数名 | 类型 | 必填 | 说明 | 1046| ------------ | ------------ | ---- | ------------ | 1047| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型。 | 1048| metadata | [Metadata](#metadata13) | 是 | 元数据对象。 | 1049 1050**返回值：** 1051 1052| 类型 | 说明 | 1053| -------------- | -------------------------------------- | 1054| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1055 1056**错误码：** 1057 1058以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1059 1060| 错误码ID | 错误信息 | 1061| -------- | ------------------------------------------------------------ | 1062| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1063| 7600202 | Unsupported metadata. Possible causes: Unsupported metadata type. | 1064 1065**示例：** 1066 1067```ts 1068import { BusinessError } from '@kit.BasicServicesKit'; 1069import { image } from '@kit.ImageKit'; 1070 1071async function SetPictureObjMetadata(context: Context) { 1072 const exifResourceMgr = exifContext.resourceManager; 1073 const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");//含有exif metadata的图片。 1074 let exifOps: image.SourceOptions = { 1075 sourceDensity: 98, 1076 } 1077 let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps); 1078 let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap(); 1079 let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap); 1080 if (exifPictureObj != null) { 1081 console.info('Create picture succeeded'); 1082 } else { 1083 console.info('Create picture failed'); 1084 } 1085 1086 if (pictureObj != null) { 1087 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 1088 let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType); 1089 pictureObj.setMetadata(metadataType, exifMetaData).then(() => { 1090 console.info('Set metadata success'); 1091 }).catch((error: BusinessError) => { 1092 console.error('Failed to set metadata. error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 1093 }); 1094 } else { 1095 console.info('PictureObj is null'); 1096 } 1097} 1098``` 1099 1100### getMetadata<sup>13+</sup> 1101 1102getMetadata(metadataType: MetadataType): Promise\<Metadata> 1103 1104获取主图的元数据。 1105 1106**系统能力：** SystemCapability.Multimedia.Image.Core 1107 1108**参数：** 1109 1110| 参数名 | 类型 | 必填 | 说明 | 1111| ------------ | ------------ | ---- | ------------ | 1112| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型。 | 1113 1114**返回值：** 1115 1116| 类型 | 说明 | 1117| ------------------ | ------------------------- | 1118| Promise\<[Metadata](#metadata13)> | Promise对象。返回元数据。 | 1119 1120**错误码：** 1121 1122以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1123 1124| 错误码ID | 错误信息 | 1125| -------- | ------------------------------------------------------------ | 1126| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1127| 7600202 | Unsupported metadata. Possible causes: Unsupported metadata type. | 1128 1129**示例：** 1130 1131```ts 1132import { image } from '@kit.ImageKit'; 1133 1134async function GetPictureObjMetadataProperties() { 1135 if (pictureObj != null) { 1136 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 1137 let pictureObjMetaData: image.Metadata = await pictureObj.getMetadata(metadataType); 1138 if (pictureObjMetaData != null) { 1139 console.info('get picture metadata success'); 1140 } else { 1141 console.info('get picture metadata is failed'); 1142 } 1143 } else { 1144 console.info(" pictureObj is null"); 1145 } 1146} 1147``` 1148 1149### marshalling<sup>13+</sup> 1150 1151marshalling(sequence: rpc.MessageSequence): void 1152 1153将picture序列化后写入MessageSequence。 1154 1155**系统能力：** SystemCapability.Multimedia.Image.Core 1156 1157**参数：** 1158 1159| 参数名 | 类型 | 必填 | 说明 | 1160| -------- | ------------------------------------------------------------------- | ---- | ------------------------- | 1161| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 1162 1163**错误码：** 1164 1165以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1166 1167| 错误码ID | 错误信息 | 1168| -------- | ------------------------------------------------------------ | 1169| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1170| 62980097 | IPC error. | 1171 1172**示例：** 1173 1174```ts 1175import { BusinessError } from '@kit.BasicServicesKit'; 1176import { image } from '@kit.ImageKit'; 1177import { rpc } from '@kit.IPCKit'; 1178 1179class MySequence implements rpc.Parcelable { 1180 picture: image.Picture | null = null; 1181 constructor(conPicture: image.Picture) { 1182 this.picture = conPicture; 1183 } 1184 marshalling(messageSequence: rpc.MessageSequence) { 1185 if(this.picture != null) { 1186 this.picture.marshalling(messageSequence); 1187 console.info('Marshalling success !'); 1188 return true; 1189 } else { 1190 console.info('Marshalling failed !'); 1191 return false; 1192 } 1193 } 1194 unmarshalling(messageSequence : rpc.MessageSequence) { 1195 this.picture = image.createPictureFromParcel(messageSequence); 1196 this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => { 1197 console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width); 1198 }).catch((error: BusinessError) => { 1199 console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}'); 1200 }); 1201 return true; 1202 } 1203} 1204 1205async function Marshalling_UnMarshalling() { 1206 if (pictureObj != null) { 1207 let parcelable: MySequence = new MySequence(pictureObj); 1208 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 1209 // marshalling. 1210 data.writeParcelable(parcelable); 1211 let ret: MySequence = new MySequence(pictureObj); 1212 // unmarshalling. 1213 data.readParcelable(ret); 1214 } else { 1215 console.info('PictureObj is null'); 1216 } 1217} 1218``` 1219 1220### release<sup>13+</sup> 1221 1222release(): void 1223 1224释放picture对象。 1225 1226**系统能力：** SystemCapability.Multimedia.Image.Core 1227 1228**示例：** 1229 1230```ts 1231import { image } from '@kit.ImageKit'; 1232 1233async function Release() { 1234 let funcName = "Release"; 1235 if (pictureObj != null) { 1236 pictureObj.release(); 1237 if (pictureObj.getMainPixelmap() == null) { 1238 console.info(funcName, 'Success !'); 1239 } else { 1240 console.info(funcName, 'Failed !'); 1241 } 1242 } else { 1243 console.info('PictureObj is null'); 1244 } 1245} 1246``` 1247 1248## PixelMap<sup>7+</sup> 1249 1250图像像素类，用于读取或写入图像数据以及获取图像信息。在调用PixelMap的方法前，需要先通过[createPixelMap](#imagecreatepixelmap8)创建一个PixelMap实例。目前pixelmap序列化大小最大128MB，超过会送显失败。大小计算方式为(宽\*高\*每像素占用字节数)。 1251 1252从API version 11开始，PixelMap支持通过worker跨线程调用。当PixelMap通过[Worker](../apis-arkts/js-apis-worker.md)跨线程后，原线程的PixelMap的所有接口均不能调用，否则将报错501 服务器不具备完成请求的功能。 1253 1254在调用PixelMap的方法前，需要先通过[image.createPixelMap](#imagecreatepixelmap8)构建一个PixelMap对象。 1255 1256开发原子化服务请通过[ImageSoure](#imagesource)构建PixelMap对象。 1257 1258### 属性 1259 1260**系统能力：** SystemCapability.Multimedia.Image.Core 1261 1262| 名称 | 类型 | 可读 | 可写 | 说明 | 1263| -----------------| ------- | ---- | ---- | -------------------------- | 1264| isEditable | boolean | 是 | 否 | true表示图像像素可被编辑，false表示不可被编辑。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 1265| isStrideAlignment<sup>11+</sup> | boolean | 是 | 否 | true表示图像内存为DMA内存，false表示非DMA内存。 | 1266 1267### readPixelsToBuffer<sup>7+</sup> 1268 1269readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 1270 1271按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用Promise形式返回。 1272 1273**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1274 1275**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1276 1277**系统能力：** SystemCapability.Multimedia.Image.Core 1278 1279**参数：** 1280 1281| 参数名 | 类型 | 必填 | 说明 | 1282| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 1283| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1284 1285**返回值：** 1286 1287| 类型 | 说明 | 1288| -------------- | ----------------------------------------------- | 1289| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1290 1291**示例：** 1292 1293```ts 1294import { BusinessError } from '@kit.BasicServicesKit'; 1295 1296async function ReadPixelsToBuffer() { 1297 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1298 if (pixelMap != undefined) { 1299 pixelMap.readPixelsToBuffer(readBuffer).then(() => { 1300 console.info('Succeeded in reading image pixel data.'); // 符合条件则进入。 1301 }).catch((error: BusinessError) => { 1302 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1303 }) 1304 } 1305} 1306``` 1307 1308### readPixelsToBuffer<sup>7+</sup> 1309 1310readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback\<void>): void 1311 1312按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用callback形式返回。 1313 1314**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1315 1316**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1317 1318**系统能力：** SystemCapability.Multimedia.Image.Core 1319 1320**参数：** 1321 1322| 参数名 | 类型 | 必填 | 说明 | 1323| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 1324| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1325| callback | AsyncCallback\<void> | 是 | 回调函数。当读取像素数据到ArrayBuffer成功，err为undefined，否则为错误对象。 | 1326 1327**示例：** 1328 1329```ts 1330import { BusinessError } from '@kit.BasicServicesKit'; 1331 1332async function ReadPixelsToBuffer() { 1333 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1334 if (pixelMap != undefined) { 1335 pixelMap.readPixelsToBuffer(readBuffer, (error: BusinessError, res: void) => { 1336 if(error) { 1337 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1338 return; 1339 } else { 1340 console.info('Succeeded in reading image pixel data.'); //符合条件则进入。 1341 } 1342 }) 1343 } 1344} 1345``` 1346 1347### readPixelsToBufferSync<sup>12+</sup> 1348 1349readPixelsToBufferSync(dst: ArrayBuffer): void 1350 1351按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，同步返回结果。 1352 1353**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1354 1355**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1356 1357**系统能力：** SystemCapability.Multimedia.Image.Core 1358 1359**参数：** 1360 1361| 参数名 | 类型 | 必填 | 说明 | 1362| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 1363| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1364 1365**错误码：** 1366 1367以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1368 1369| 错误码ID | 错误信息 | 1370| ------- | --------------------------------------------| 1371| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1372| 501 | Resource Unavailable | 1373 1374**示例：** 1375 1376```ts 1377import { BusinessError } from '@kit.BasicServicesKit'; 1378 1379async function ReadPixelsToBufferSync() { 1380 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1381 if (pixelMap != undefined) { 1382 pixelMap.readPixelsToBufferSync(readBuffer); 1383 } 1384} 1385``` 1386 1387### readPixels<sup>7+</sup> 1388 1389readPixels(area: PositionArea): Promise\<void> 1390 1391固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，使用Promise形式返回。 1392 1393可用公式计算PositionArea需要申请的内存大小。 1394 1395YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1396 1397RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1398 1399**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1400 1401**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1402 1403**系统能力：** SystemCapability.Multimedia.Image.Core 1404 1405**参数：** 1406 1407| 参数名 | 类型 | 必填 | 说明 | 1408| ------ | ------------------------------ | ---- | ------------------------ | 1409| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1410 1411**返回值：** 1412 1413| 类型 | 说明 | 1414| :------------- | :-------------------------------------------------- | 1415| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1416 1417**示例：** 1418 1419```ts 1420import { BusinessError } from '@kit.BasicServicesKit'; 1421 1422async function ReadPixelsRGBA() { 1423 const area: image.PositionArea = { 1424 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1425 offset: 0, 1426 stride: 8, 1427 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1428 }; 1429 if (pixelMap != undefined) { 1430 pixelMap.readPixels(area).then(() => { 1431 console.info('Succeeded in reading the image data in the area.'); //符合条件则进入。 1432 }).catch((error: BusinessError) => { 1433 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1434 }) 1435 } 1436} 1437 1438async function ReadPixelsYUV() { 1439 const area: image.PositionArea = { 1440 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1441 offset: 0, 1442 stride: 8, 1443 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1444 }; 1445 if (pixelMap != undefined) { 1446 pixelMap.readPixels(area).then(() => { 1447 console.info('Succeeded in reading the image data in the area.'); //符合条件则进入。 1448 }).catch((error: BusinessError) => { 1449 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 1450 }) 1451 } 1452} 1453``` 1454 1455### readPixels<sup>7+</sup> 1456 1457readPixels(area: PositionArea, callback: AsyncCallback\<void>): void 1458 1459固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，使用callback形式返回。 1460 1461可用公式计算PositionArea需要申请的内存大小。 1462 1463YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1464 1465RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1466 1467**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1468 1469**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1470 1471**系统能力：** SystemCapability.Multimedia.Image.Core 1472 1473**参数：** 1474 1475| 参数名 | 类型 | 必填 | 说明 | 1476| -------- | ------------------------------ | ---- | ------------------------------ | 1477| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1478| callback | AsyncCallback\<void> | 是 | 回调函数。当读取区域内的图片数据成功，err为undefined，否则为错误对象。 | 1479 1480**示例：** 1481 1482```ts 1483import { BusinessError } from '@kit.BasicServicesKit'; 1484 1485async function ReadPixelsRGBA() { 1486 const area: image.PositionArea = { 1487 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1488 offset: 0, 1489 stride: 8, 1490 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1491 }; 1492 if (pixelMap != undefined) { 1493 pixelMap.readPixels(area, (error: BusinessError) => { 1494 if (error) { 1495 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 1496 return; 1497 } else { 1498 console.info('Succeeded in reading pixelmap from the specified area.'); 1499 } 1500 }) 1501 } 1502} 1503 1504async function ReadPixelsYUV() { 1505 const area: image.PositionArea = { 1506 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1507 offset: 0, 1508 stride: 8, 1509 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1510 }; 1511 if (pixelMap != undefined) { 1512 pixelMap.readPixels(area, (error: BusinessError) => { 1513 if (error) { 1514 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 1515 return; 1516 } else { 1517 console.info('Succeeded in reading pixelmap from the specified area.'); 1518 } 1519 }) 1520 } 1521} 1522``` 1523 1524### readPixelsSync<sup>12+</sup> 1525 1526readPixelsSync(area: PositionArea): void 1527 1528固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](#positionarea7).pixels缓冲区中，该区域由[PositionArea](#positionarea7).region指定，同步返回结果。 1529 1530**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1531 1532**系统能力：** SystemCapability.Multimedia.Image.Core 1533 1534**参数：** 1535 1536| 参数名 | 类型 | 必填 | 说明 | 1537| ------ | ------------------------------ | ---- | ------------------------ | 1538| area | [PositionArea](#positionarea7) | 是 | 区域大小，根据区域读取。 | 1539 1540**错误码：** 1541 1542以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1543 1544| 错误码ID | 错误信息 | 1545| ------- | --------------------------------------------| 1546| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1547| 501 | Resource Unavailable | 1548 1549**示例：** 1550 1551```ts 1552import { BusinessError } from '@kit.BasicServicesKit'; 1553 1554async function ReadPixelsSync() { 1555 const area : image.PositionArea = { 1556 pixels: new ArrayBuffer(8), 1557 offset: 0, 1558 stride: 8, 1559 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1560 }; 1561 if (pixelMap != undefined) { 1562 pixelMap.readPixelsSync(area); 1563 } 1564} 1565``` 1566 1567### writePixels<sup>7+</sup> 1568 1569writePixels(area: PositionArea): Promise\<void> 1570 1571固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，使用Promise形式返回。 1572 1573可用公式计算PositionArea需要申请的内存大小。 1574 1575YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1576 1577RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1578 1579**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1580 1581**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1582 1583**系统能力：** SystemCapability.Multimedia.Image.Core 1584 1585**参数：** 1586 1587| 参数名 | 类型 | 必填 | 说明 | 1588| ------ | ------------------------------ | ---- | -------------------- | 1589| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1590 1591**返回值：** 1592 1593| 类型 | 说明 | 1594| :------------- | :-------------------------------------------------- | 1595| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1596 1597**示例：** 1598 1599```ts 1600import { BusinessError } from '@kit.BasicServicesKit'; 1601 1602async function WritePixelsRGBA() { 1603 const area: image.PositionArea = { 1604 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1605 offset: 0, 1606 stride: 8, 1607 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1608 }; 1609 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1610 for (let i = 0; i < bufferArr.length; i++) { 1611 bufferArr[i] = i + 1; 1612 } 1613 if (pixelMap != undefined) { 1614 pixelMap.writePixels(area).then(() => { 1615 console.info('Succeeded in writing pixelmap into the specified area.'); 1616 }).catch((error: BusinessError) => { 1617 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1618 }) 1619 } 1620} 1621 1622async function WritePixelsYUV() { 1623 const area: image.PositionArea = { 1624 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1625 offset: 0, 1626 stride: 8, 1627 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1628 }; 1629 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1630 for (let i = 0; i < bufferArr.length; i++) { 1631 bufferArr[i] = i + 1; 1632 } 1633 if (pixelMap != undefined) { 1634 pixelMap.writePixels(area).then(() => { 1635 console.info('Succeeded in writing pixelmap into the specified area.'); 1636 }).catch((error: BusinessError) => { 1637 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1638 }) 1639 } 1640} 1641``` 1642 1643### writePixels<sup>7+</sup> 1644 1645writePixels(area: PositionArea, callback: AsyncCallback\<void>): void 1646 1647固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，使用callback形式返回。 1648 1649可用公式计算PositionArea需要申请的内存大小。 1650 1651YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 1652 1653RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 1654 1655**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1656 1657**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1658 1659**系统能力：** SystemCapability.Multimedia.Image.Core 1660 1661**参数：** 1662 1663| 参数名 | 类型 | 必填 | 说明 | 1664| --------- | ------------------------------ | ---- | ------------------------------ | 1665| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1666| callback | AsyncCallback\<void> | 是 | 回调函数，当写入成功，err为undefined，否则为错误对象。 | 1667 1668**示例：** 1669 1670```ts 1671import { BusinessError } from '@kit.BasicServicesKit'; 1672 1673async function WritePixelsRGBA() { 1674 const area: image.PositionArea = { pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 1675 offset: 0, 1676 stride: 8, 1677 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1678 }; 1679 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1680 for (let i = 0; i < bufferArr.length; i++) { 1681 bufferArr[i] = i + 1; 1682 } 1683 if (pixelMap != undefined) { 1684 pixelMap.writePixels(area, (error : BusinessError) => { 1685 if (error) { 1686 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1687 return; 1688 } else { 1689 console.info('Succeeded in writing pixelmap into the specified area.'); 1690 } 1691 }) 1692 } 1693} 1694 1695async function WritePixelsYUV() { 1696 const area: image.PositionArea = { pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 1697 offset: 0, 1698 stride: 8, 1699 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 1700 }; 1701 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1702 for (let i = 0; i < bufferArr.length; i++) { 1703 bufferArr[i] = i + 1; 1704 } 1705 if (pixelMap != undefined) { 1706 pixelMap.writePixels(area, (error : BusinessError) => { 1707 if (error) { 1708 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 1709 return; 1710 } else { 1711 console.info('Succeeded in writing pixelmap into the specified area.'); 1712 } 1713 }) 1714 } 1715} 1716``` 1717 1718### writePixelsSync<sup>12+</sup> 1719 1720writePixelsSync(area: PositionArea): void 1721 1722固定按照BGRA_8888格式，读取[PositionArea](#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](#positionarea7).region指定，同步返回结果。 1723 1724**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1725 1726**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1727 1728**系统能力：** SystemCapability.Multimedia.Image.Core 1729 1730**参数：** 1731 1732| 参数名 | 类型 | 必填 | 说明 | 1733| ------ | ------------------------------ | ---- | -------------------- | 1734| area | [PositionArea](#positionarea7) | 是 | 区域，根据区域写入。 | 1735 1736**错误码：** 1737 1738以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1739 1740| 错误码ID | 错误信息 | 1741| ------- | --------------------------------------------| 1742| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1743| 501 | Resource Unavailable | 1744 1745**示例：** 1746 1747```ts 1748import { BusinessError } from '@kit.BasicServicesKit'; 1749 1750async function WritePixelsSync() { 1751 const area: image.PositionArea = { 1752 pixels: new ArrayBuffer(8), 1753 offset: 0, 1754 stride: 8, 1755 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 1756 }; 1757 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 1758 for (let i = 0; i < bufferArr.length; i++) { 1759 bufferArr[i] = i + 1; 1760 } 1761 if (pixelMap != undefined) { 1762 pixelMap.writePixelsSync(area); 1763 } 1764} 1765``` 1766 1767### writeBufferToPixels<sup>7+</sup> 1768 1769writeBufferToPixels(src: ArrayBuffer): Promise\<void> 1770 1771按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用Promise形式返回。 1772 1773**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1774 1775**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1776 1777**系统能力：** SystemCapability.Multimedia.Image.Core 1778 1779**参数：** 1780 1781| 参数名 | 类型 | 必填 | 说明 | 1782| ------ | ----------- | ---- | -------------- | 1783| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1784 1785**返回值：** 1786 1787| 类型 | 说明 | 1788| -------------- | ----------------------------------------------- | 1789| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1790 1791**示例：** 1792 1793```ts 1794import { BusinessError } from '@kit.BasicServicesKit'; 1795 1796async function WriteBufferToPixels() { 1797 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 1798 let bufferArr: Uint8Array = new Uint8Array(color); 1799 for (let i = 0; i < bufferArr.length; i++) { 1800 bufferArr[i] = i + 1; 1801 } 1802 if (pixelMap != undefined) { 1803 pixelMap.writeBufferToPixels(color).then(() => { 1804 console.info("Succeeded in writing data from a buffer to a PixelMap."); 1805 }).catch((error: BusinessError) => { 1806 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 1807 }) 1808 } 1809} 1810``` 1811 1812### writeBufferToPixels<sup>7+</sup> 1813 1814writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback\<void>): void 1815 1816按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用callback形式返回。 1817 1818**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1819 1820**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1821 1822**系统能力：** SystemCapability.Multimedia.Image.Core 1823 1824**参数：** 1825 1826| 参数名 | 类型 | 必填 | 说明 | 1827| -------- | -------------------- | ---- | ------------------------------ | 1828| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1829| callback | AsyncCallback\<void> | 是 | 回调函数。当缓冲区中的图像像素数据写入PixelMap成功，err为undefined，否则为错误对象。 | 1830 1831**示例：** 1832 1833```ts 1834import { BusinessError } from '@kit.BasicServicesKit'; 1835 1836async function WriteBufferToPixels() { 1837 const color: ArrayBuffer = new ArrayBuffer(96); //96为需要创建的像素buffer大小，取值为：height * width *4。 1838 let bufferArr: Uint8Array = new Uint8Array(color); 1839 for (let i = 0; i < bufferArr.length; i++) { 1840 bufferArr[i] = i + 1; 1841 } 1842 if (pixelMap != undefined) { 1843 pixelMap.writeBufferToPixels(color, (error: BusinessError) => { 1844 if (error) { 1845 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 1846 return; 1847 } else { 1848 console.info("Succeeded in writing data from a buffer to a PixelMap."); 1849 } 1850 }) 1851 } 1852} 1853``` 1854 1855### writeBufferToPixelsSync<sup>12+</sup> 1856 1857writeBufferToPixelsSync(src: ArrayBuffer): void 1858 1859按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，同步返回结果。 1860 1861**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1862 1863**系统能力：** SystemCapability.Multimedia.Image.Core 1864 1865**参数：** 1866 1867| 参数名 | 类型 | 必填 | 说明 | 1868| ------ | ----------- | ---- | -------------- | 1869| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 1870 1871**错误码：** 1872 1873以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1874 1875| 错误码ID | 错误信息 | 1876| ------- | --------------------------------------------| 1877| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1878| 501 | Resource Unavailable | 1879 1880**示例：** 1881 1882```ts 1883import { BusinessError } from '@kit.BasicServicesKit'; 1884 1885async function WriteBufferToPixelsSync() { 1886 const color : ArrayBuffer = new ArrayBuffer(96); //96为需要创建的像素buffer大小，取值为：height * width *4。 1887 let bufferArr : Uint8Array = new Uint8Array(color); 1888 for (let i = 0; i < bufferArr.length; i++) { 1889 bufferArr[i] = i + 1; 1890 } 1891 if (pixelMap != undefined) { 1892 pixelMap.writeBufferToPixelsSync(color); 1893 } 1894} 1895``` 1896 1897 1898### getImageInfo<sup>7+</sup> 1899 1900getImageInfo(): Promise\<ImageInfo> 1901 1902获取图像像素信息，使用Promise形式返回获取的图像像素信息。 1903 1904**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1905 1906**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1907 1908**系统能力：** SystemCapability.Multimedia.Image.Core 1909 1910**返回值：** 1911 1912| 类型 | 说明 | 1913| --------------------------------- | ----------------------------------------------------------- | 1914| Promise\<[ImageInfo](#imageinfo)> | Promise对象，返回图像像素信息。 | 1915 1916**示例：** 1917 1918```ts 1919import { BusinessError } from '@kit.BasicServicesKit'; 1920 1921async function GetImageInfo() { 1922 if (pixelMap != undefined) { 1923 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 1924 if (imageInfo != undefined) { 1925 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 1926 } 1927 }).catch((error: BusinessError) => { 1928 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 1929 }) 1930 } 1931} 1932``` 1933 1934### getImageInfo<sup>7+</sup> 1935 1936getImageInfo(callback: AsyncCallback\<ImageInfo>): void 1937 1938获取图像像素信息，使用callback形式返回获取的图像像素信息。 1939 1940**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1941 1942**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1943 1944**系统能力：** SystemCapability.Multimedia.Image.Core 1945 1946**参数：** 1947 1948| 参数名 | 类型 | 必填 | 说明 | 1949| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 1950| callback | AsyncCallback\<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图像像素信息成功，err为undefined，data为获取到的图像像素信息；否则为错误对象。 | 1951 1952**示例:** 1953 1954```ts 1955import { BusinessError } from '@kit.BasicServicesKit'; 1956 1957async function GetImageInfo() { 1958 if (pixelMap != undefined) { 1959 pixelMap.getImageInfo((error: BusinessError, imageInfo: image.ImageInfo) => { 1960 if (error) { 1961 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 1962 return; 1963 } else { 1964 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 1965 } 1966 }) 1967 } 1968} 1969``` 1970 1971### getImageInfoSync<sup>12+</sup> 1972 1973getImageInfoSync(): ImageInfo 1974 1975以同步方法获取图像像素信息。 1976 1977**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1978 1979**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1980 1981**系统能力：** SystemCapability.Multimedia.Image.ImageSource 1982 1983**返回值：** 1984 1985| 类型 | 说明 | 1986| --------------------------------- | ----------------------------------------------------------- | 1987| [ImageInfo](#imageinfo) | 图像像素信息。 | 1988 1989**错误码：** 1990 1991以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1992 1993| 错误码ID | 错误信息 | 1994| ------- | --------------------------------------------| 1995| 501 | Resource Unavailable | 1996 1997**示例：** 1998 1999```ts 2000import { BusinessError } from '@kit.BasicServicesKit'; 2001 2002async function GetImageInfoSync() { 2003 if (pixelMap != undefined) { 2004 let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync(); 2005 return imageInfo; 2006 } 2007 return undefined; 2008} 2009``` 2010 2011### getBytesNumberPerRow<sup>7+</sup> 2012 2013getBytesNumberPerRow(): number 2014 2015获取图像像素每行字节数。 2016 2017**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2018 2019**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2020 2021**系统能力：** SystemCapability.Multimedia.Image.Core 2022 2023**返回值：** 2024 2025| 类型 | 说明 | 2026| ------ | -------------------- | 2027| number | 图像像素的行字节数。 | 2028 2029**示例：** 2030 2031```ts 2032let rowCount: number = pixelMap.getBytesNumberPerRow(); 2033``` 2034 2035### getPixelBytesNumber<sup>7+</sup> 2036 2037getPixelBytesNumber(): number 2038 2039获取图像像素的总字节数。 2040 2041**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2042 2043**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2044 2045**系统能力：** SystemCapability.Multimedia.Image.Core 2046 2047**返回值：** 2048 2049| 类型 | 说明 | 2050| ------ | -------------------- | 2051| number | 图像像素的总字节数。 | 2052 2053**示例：** 2054 2055```ts 2056let pixelBytesNumber: number = pixelMap.getPixelBytesNumber(); 2057``` 2058 2059### getDensity<sup>9+</sup> 2060 2061getDensity():number 2062 2063获取当前图像像素的密度。 2064 2065**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2066 2067**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2068 2069**系统能力：** SystemCapability.Multimedia.Image.Core 2070 2071**返回值：** 2072 2073| 类型 | 说明 | 2074| ------ | --------------- | 2075| number | 图像像素的密度，单位为ppi。| 2076 2077**示例：** 2078 2079```ts 2080let getDensity: number = pixelMap.getDensity(); 2081``` 2082 2083### opacity<sup>9+</sup> 2084 2085opacity(rate: number, callback: AsyncCallback\<void>): void 2086 2087通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用callback形式返回。 2088 2089**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2090 2091**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2092 2093**系统能力：** SystemCapability.Multimedia.Image.Core 2094 2095**参数：** 2096 2097| 参数名 | 类型 | 必填 | 说明 | 2098| -------- | -------------------- | ---- | ------------------------------ | 2099| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 2100| callback | AsyncCallback\<void> | 是 | 回调函数。当设置透明比率成功，err为undefined，否则为错误对象。 | 2101 2102**示例：** 2103 2104```ts 2105import { BusinessError } from '@kit.BasicServicesKit'; 2106 2107async function Opacity() { 2108 let rate: number = 0.5; 2109 if (pixelMap != undefined) { 2110 pixelMap.opacity(rate, (err: BusinessError) => { 2111 if (err) { 2112 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 2113 return; 2114 } else { 2115 console.info("Succeeded in setting opacity."); 2116 } 2117 }) 2118 } 2119} 2120``` 2121 2122### opacity<sup>9+</sup> 2123 2124opacity(rate: number): Promise\<void> 2125 2126通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用Promise形式返回。 2127 2128**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2129 2130**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2131 2132**系统能力：** SystemCapability.Multimedia.Image.Core 2133 2134**参数：** 2135 2136| 参数名 | 类型 | 必填 | 说明 | 2137| ------ | ------ | ---- | --------------------------- | 2138| rate | number | 是 | 透明比率的值，取值范围是(0,1]。| 2139 2140**返回值：** 2141 2142| 类型 | 说明 | 2143| -------------- | ----------------------------------------------- | 2144| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2145 2146**示例：** 2147 2148```ts 2149import { BusinessError } from '@kit.BasicServicesKit'; 2150 2151async function Opacity() { 2152 let rate: number = 0.5; 2153 if (pixelMap != undefined) { 2154 pixelMap.opacity(rate).then(() => { 2155 console.info('Succeeded in setting opacity.'); 2156 }).catch((err: BusinessError) => { 2157 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 2158 }) 2159 } 2160} 2161``` 2162 2163### opacitySync<sup>12+</sup> 2164 2165opacitySync(rate: number): void 2166 2167设置PixelMap的透明比率，yuv图片不支持设置透明度，初始化PixelMap并同步返回结果。 2168 2169**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2170 2171**系统能力：** SystemCapability.Multimedia.Image.Core 2172 2173**参数：** 2174 2175| 参数名 | 类型 | 必填 | 说明 | 2176| -------- | -------------------- | ---- | ------------------------------ | 2177| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 2178 2179**错误码：** 2180 2181以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2182 2183| 错误码ID | 错误信息 | 2184| ------- | --------------------------------------------| 2185| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2186| 501 | Resource Unavailable | 2187 2188**示例：** 2189 2190```ts 2191import { BusinessError } from '@kit.BasicServicesKit'; 2192 2193async function OpacitySync() { 2194 let rate : number = 0.5; 2195 if (pixelMap != undefined) { 2196 pixelMap.opacitySync(rate); 2197 } 2198} 2199``` 2200 2201### createAlphaPixelmap<sup>9+</sup> 2202 2203createAlphaPixelmap(): Promise\<PixelMap> 2204 2205根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用Promise形式返回。 2206 2207**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2208 2209**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2210 2211**系统能力：** SystemCapability.Multimedia.Image.Core 2212 2213**返回值：** 2214 2215| 类型 | 说明 | 2216| -------------------------------- | --------------------------- | 2217| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 2218 2219**示例：** 2220 2221```ts 2222import { BusinessError } from '@kit.BasicServicesKit'; 2223 2224async function CreateAlphaPixelmap() { 2225 if (pixelMap != undefined) { 2226 pixelMap.createAlphaPixelmap().then((alphaPixelMap: image.PixelMap) => { 2227 console.info('Succeeded in creating alpha pixelmap.'); 2228 }).catch((error: BusinessError) => { 2229 console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`); 2230 }) 2231 } 2232} 2233``` 2234 2235### createAlphaPixelmap<sup>9+</sup> 2236 2237createAlphaPixelmap(callback: AsyncCallback\<PixelMap>): void 2238 2239根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用callback形式返回。 2240 2241**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2242 2243**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2244 2245**系统能力：** SystemCapability.Multimedia.Image.Core 2246 2247**参数：** 2248 2249| 参数名 | 类型 | 必填 | 说明 | 2250| -------- | ------------------------ | ---- | ------------------------ | 2251| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 2252 2253**示例：** 2254 2255```ts 2256import { BusinessError } from '@kit.BasicServicesKit'; 2257 2258async function CreateAlphaPixelmap() { 2259 if (pixelMap != undefined) { 2260 pixelMap.createAlphaPixelmap((err: BusinessError, alphaPixelMap: image.PixelMap) => { 2261 if (alphaPixelMap == undefined) { 2262 console.error(`Failed to obtain new pixel map. code is ${err.code}, message is ${err.message}`); 2263 return; 2264 } else { 2265 console.info('Succeeded in obtaining new pixel map.'); 2266 } 2267 }) 2268 } 2269} 2270``` 2271 2272### createAlphaPixelmapSync<sup>12+</sup> 2273 2274createAlphaPixelmapSync(): PixelMap 2275 2276根据Alpha通道的信息，生成一个仅包含Alpha通道信息的PixelMap，可用于阴影效果，yuv格式不支持此接口，同步返回PixelMap类型的结果。 2277 2278**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2279 2280**系统能力：** SystemCapability.Multimedia.Image.Core 2281 2282**返回值：** 2283 2284| 类型 | 说明 | 2285| -------------------------------- | --------------------- | 2286| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2287 2288**错误码：** 2289 2290以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2291 2292| 错误码ID | 错误信息 | 2293| ------- | --------------------------------------------| 2294| 401 | Parameter error. Possible causes: 1.Parameter verification failed | 2295| 501 | Resource Unavailable | 2296 2297**示例：** 2298 2299```ts 2300import { BusinessError } from '@kit.BasicServicesKit'; 2301 2302async function CreateAlphaPixelmapSync() { 2303 if (pixelMap != undefined) { 2304 let pixelmap : image.PixelMap = pixelMap.createAlphaPixelmapSync(); 2305 return pixelmap; 2306 } 2307 return undefined; 2308} 2309``` 2310 2311### scale<sup>9+</sup> 2312 2313scale(x: number, y: number, callback: AsyncCallback\<void>): void 2314 2315根据输入的宽高的缩放倍数对图片进行缩放，使用callback形式返回。 2316 2317> **说明：** 2318> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2319> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2320 2321**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2322 2323**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2324 2325**系统能力：** SystemCapability.Multimedia.Image.Core 2326 2327**参数：** 2328 2329| 参数名 | 类型 | 必填 | 说明 | 2330| -------- | -------------------- | ---- | ------------------------------- | 2331| x | number | 是 | 宽度的缩放倍数。| 2332| y | number | 是 | 高度的缩放倍数。| 2333| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行缩放成功，err为undefined，否则为错误对象。 | 2334 2335**示例：** 2336 2337```ts 2338import { BusinessError } from '@kit.BasicServicesKit'; 2339 2340async function Scale() { 2341 let scaleX: number = 2.0; 2342 let scaleY: number = 1.0; 2343 if (pixelMap != undefined) { 2344 pixelMap.scale(scaleX, scaleY, (err: BusinessError) => { 2345 if (err) { 2346 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2347 return; 2348 } else { 2349 console.info("Succeeded in scaling pixelmap."); 2350 } 2351 }) 2352 } 2353} 2354``` 2355 2356### scale<sup>9+</sup> 2357 2358scale(x: number, y: number): Promise\<void> 2359 2360根据输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 2361 2362> **说明：** 2363> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2364> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2365 2366**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2367 2368**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2369 2370**系统能力：** SystemCapability.Multimedia.Image.Core 2371 2372**参数：** 2373 2374| 参数名 | 类型 | 必填 | 说明 | 2375| ------ | ------ | ---- | ------------------------------- | 2376| x | number | 是 | 宽度的缩放倍数。| 2377| y | number | 是 | 高度的缩放倍数。| 2378 2379**返回值：** 2380 2381| 类型 | 说明 | 2382| -------------- | --------------------------- | 2383| Promise\<void> | Promise对象。无返回结果的Promise对象。| 2384 2385**示例：** 2386 2387```ts 2388import { BusinessError } from '@kit.BasicServicesKit'; 2389 2390async function Scale() { 2391 let scaleX: number = 2.0; 2392 let scaleY: number = 1.0; 2393 if (pixelMap != undefined) { 2394 pixelMap.scale(scaleX, scaleY).then(() => { 2395 console.info('Succeeded in scaling pixelmap.'); 2396 }).catch((err: BusinessError) => { 2397 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2398 2399 }) 2400 } 2401} 2402``` 2403 2404### scaleSync<sup>12+</sup> 2405 2406scaleSync(x: number, y: number): void 2407 2408根据输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 2409 2410> **说明：** 2411> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2412> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2413 2414**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2415 2416**系统能力：** SystemCapability.Multimedia.Image.Core 2417 2418**参数：** 2419 2420| 参数名 | 类型 | 必填 | 说明 | 2421| ------ | ------ | ---- | ------------------------------- | 2422| x | number | 是 | 宽度的缩放倍数。| 2423| y | number | 是 | 高度的缩放倍数。| 2424 2425**错误码：** 2426 2427以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2428 2429| 错误码ID | 错误信息 | 2430| ------- | --------------------------------------------| 2431| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2432| 501 | Resource Unavailable | 2433 2434**示例：** 2435 2436```ts 2437import { BusinessError } from '@kit.BasicServicesKit'; 2438 2439async function ScaleSync() { 2440 let scaleX: number = 2.0; 2441 let scaleY: number = 1.0; 2442 if (pixelMap != undefined) { 2443 pixelMap.scaleSync(scaleX, scaleY); 2444 } 2445} 2446``` 2447 2448### scale<sup>12+</sup> 2449 2450scale(x: number, y: number, level: AntiAliasingLevel): Promise\<void> 2451 2452根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 2453 2454> **说明：** 2455> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2456> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2457 2458**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2459 2460**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2461 2462**系统能力：** SystemCapability.Multimedia.Image.Core 2463 2464**参数：** 2465 2466| 参数名 | 类型 | 必填 | 说明 | 2467| ------ | ------ | ---- | ------------------------------- | 2468| x | number | 是 | 宽度的缩放倍数。| 2469| y | number | 是 | 高度的缩放倍数。| 2470| level | [AntiAliasingLevel](#antialiasinglevel12) | 是 | 采用的缩放算法。| 2471 2472**返回值：** 2473 2474| 类型 | 说明 | 2475| -------------- | --------------------------- | 2476| Promise\<void> | Promise对象。无返回结果的Promise对象。| 2477 2478**错误码：** 2479 2480以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2481 2482| 错误码ID | 错误信息 | 2483| ------- | --------------------------------------------| 2484| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2485| 501 | Resource Unavailable | 2486 2487**示例：** 2488 2489```ts 2490import { BusinessError } from '@kit.BasicServicesKit'; 2491 2492async function Scale() { 2493 let scaleX: number = 2.0; 2494 let scaleY: number = 1.0; 2495 if (pixelMap != undefined) { 2496 pixelMap.scale(scaleX, scaleY, image.AntiAliasingLevel.LOW).then(() => { 2497 console.info('Succeeded in scaling pixelmap.'); 2498 }).catch((err: BusinessError) => { 2499 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 2500 2501 }) 2502 } 2503} 2504``` 2505 2506### scaleSync<sup>12+</sup> 2507 2508scaleSync(x: number, y: number, level: AntiAliasingLevel): void 2509 2510根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 2511 2512> **说明：** 2513> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 2514> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 2515 2516**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2517 2518**系统能力：** SystemCapability.Multimedia.Image.Core 2519 2520**参数：** 2521 2522| 参数名 | 类型 | 必填 | 说明 | 2523| ------ | ------ | ---- | ------------------------------- | 2524| x | number | 是 | 宽度的缩放倍数。| 2525| y | number | 是 | 高度的缩放倍数。| 2526| level | [AntiAliasingLevel](#antialiasinglevel12) | 是 | 采用的缩放算法。| 2527 2528**错误码：** 2529 2530以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2531 2532| 错误码ID | 错误信息 | 2533| ------- | --------------------------------------------| 2534| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2535| 501 | Resource Unavailable | 2536 2537**示例：** 2538 2539```ts 2540import { BusinessError } from '@kit.BasicServicesKit'; 2541 2542async function ScaleSync() { 2543 let scaleX: number = 2.0; 2544 let scaleY: number = 1.0; 2545 if (pixelMap != undefined) { 2546 pixelMap.scaleSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 2547 } 2548} 2549``` 2550 2551### createScaledPixelMap<sup>18+</sup> 2552 2553createScaledPixelMap(x: number, y: number, level?: AntiAliasingLevel): Promise\<PixelMap> 2554 2555根据指定的缩放算法和输入的宽高的缩放倍数，创建一个新的缩放后的图片，使用Promise形式返回。 2556 2557**系统能力：** SystemCapability.Multimedia.Image.Core 2558 2559**参数：** 2560 2561| 参数名 | 类型 | 必填 | 说明 | 2562| ------ | ------ | ---- | ------------------------------- | 2563| x | number | 是 | 宽度的缩放倍数。| 2564| y | number | 是 | 高度的缩放倍数。| 2565| level | [AntiAliasingLevel](#antialiasinglevel12) | 否 | 采用的缩放算法。| 2566 2567**返回值：** 2568 2569| 类型 | 说明 | 2570| -------------- | --------------------------- | 2571| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 2572 2573**错误码：** 2574 2575以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2576 2577| 错误码ID | 错误信息 | 2578| ------- | --------------------------------------------| 2579| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2580| 501 | Resource Unavailable | 2581 2582**示例：** 2583 2584```ts 2585import { BusinessError } from '@kit.BasicServicesKit'; 2586 2587async function CreateScaledPixelMap() { 2588 let scaleX: number = 2.0; 2589 let scaleY: number = 1.0; 2590 if (pixelMap != undefined) { 2591 pixelMap.createScaledPixelMap(scaleX, scaleY, image.AntiAliasingLevel.LOW).then((scaledPixelMap: image.PixelMap) => { 2592 console.info('Succeeded in creating scaledPixelMap.'); 2593 }).catch((error: BusinessError) => { 2594 console.error(`Failed to create scaledPixelMap. Error code is ${error.code}, error message is ${error.message}`); 2595 }) 2596 } 2597} 2598``` 2599 2600### createScaledPixelMapSync<sup>18+</sup> 2601 2602createScaledPixelMapSync(x: number, y: number, level?: AntiAliasingLevel): PixelMap 2603 2604根据指定的缩放算法和输入的宽高的缩放倍数，创建一个新的缩放后的图片，同步返回结果。 2605 2606**系统能力：** SystemCapability.Multimedia.Image.Core 2607 2608**参数：** 2609 2610| 参数名 | 类型 | 必填 | 说明 | 2611| ------ | ------ | ---- | ------------------------------- | 2612| x | number | 是 | 宽度的缩放倍数。| 2613| y | number | 是 | 高度的缩放倍数。| 2614| level | [AntiAliasingLevel](#antialiasinglevel12) | 否 | 采用的缩放算法。| 2615 2616**返回值：** 2617 2618| 类型 | 说明 | 2619| -------------------------------- | --------------------- | 2620| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2621 2622**错误码：** 2623 2624以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2625 2626| 错误码ID | 错误信息 | 2627| ------- | --------------------------------------------| 2628| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2629| 501 | Resource Unavailable | 2630 2631**示例：** 2632 2633```ts 2634import { BusinessError } from '@kit.BasicServicesKit'; 2635 2636async function CreateScaledPixelMapSync() { 2637 let scaleX: number = 2.0; 2638 let scaleY: number = 1.0; 2639 if (pixelMap != undefined) { 2640 let scaledPixelMap = pixelMap.createScaledPixelMapSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 2641 } 2642} 2643``` 2644 2645### clone<sup>18+</sup> 2646 2647clone(): Promise\<PixelMap> 2648 2649拷贝一份当前Pixelmap对象，使用Promise形式返回。 2650 2651**系统能力：**: SystemCapability.Multimedia.Image.Core 2652 2653**返回值：** 2654 2655| 类型 | 说明 | 2656| -------------------------------- | --------------------------- | 2657| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。| 2658 2659**错误码：** 2660 2661以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2662 2663| 错误码ID | 错误信息 | 2664| ------- | --------------------------------------------| 2665| 501 | Resource unavailable. | 2666| 62980102 | Image malloc abnormal. | 2667| 62980103 | Image types are not supported. | 2668| 62980104 | Image initialization abnormal. | 2669| 62980106 | The image data is to large. | 2670 2671**示例：** 2672 2673```ts 2674import { BusinessError } from '@kit.BasicServicesKit'; 2675 2676async function Demo() { 2677 if (pixelMap != undefined) { 2678 pixelMap.clone().then((clonePixelMap: image.PixelMap) => { 2679 console.info('Succeeded clone pixelmap.'); 2680 }).catch((error: BusinessError) => { 2681 console.error(`Failed to clone pixelmap. code is ${error.code}, message is ${error.message}`); 2682 }) 2683 } 2684} 2685``` 2686 2687### cloneSync<sup>18+</sup> 2688 2689cloneSync(): PixelMap 2690 2691拷贝一份当前Pixelmap对象, 同步返回结果。 2692 2693**系统能力：**: SystemCapability.Multimedia.Image.Core 2694 2695**返回值：** 2696 2697| 类型 | 说明 | 2698| -------------------------------- | --------------------------- | 2699| [PixelMap](#pixelmap7) | 成功同步返回PixelMap对象，失败抛出异常。 | 2700 2701**错误码：** 2702 2703以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2704 2705| 错误码ID | 错误信息 | 2706| ------- | --------------------------------------------| 2707| 501 | Resource unavailable. | 2708| 62980102 | Image malloc abnormal. | 2709| 62980103 | Image types are not supported. | 2710| 62980104 | Image initialization abnormal. | 2711| 62980106 | The image data is to large. | 2712 2713**示例：** 2714 2715```ts 2716import { BusinessError } from '@kit.BasicServicesKit'; 2717 2718async function Demo(pixelMap: image.PixelMap) { 2719 if (pixelMap != undefined) { 2720 try { 2721 let clonedPixelMap = pixelMap.cloneSync(); 2722 } catch(e) { 2723 let error = e as BusinessError; 2724 console.error(`clone pixelmap error. code is ${error.code}, message is ${error.message}`); 2725 } 2726 } 2727} 2728``` 2729 2730### translate<sup>9+</sup> 2731 2732translate(x: number, y: number, callback: AsyncCallback\<void>): void 2733 2734根据输入的坐标对图片进行位置变换，使用callback形式返回。 2735 2736translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2737 2738**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2739 2740**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2741 2742**系统能力：** SystemCapability.Multimedia.Image.Core 2743 2744**参数：** 2745 2746| 参数名 | 类型 | 必填 | 说明 | 2747| -------- | -------------------- | ---- | ----------------------------- | 2748| x | number | 是 | 区域横坐标。单位：像素。 | 2749| y | number | 是 | 区域纵坐标。单位：像素。 | 2750| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行位置变换成功，err为undefined，否则为错误对象。| 2751 2752**示例：** 2753 2754```ts 2755import { BusinessError } from '@kit.BasicServicesKit'; 2756 2757async function Translate() { 2758 let translateX: number = 50.0; 2759 let translateY: number = 10.0; 2760 if (pixelMap != undefined) { 2761 pixelMap.translate(translateX, translateY, (err: BusinessError) => { 2762 if (err) { 2763 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 2764 return; 2765 } else { 2766 console.info("Succeeded in translating pixelmap."); 2767 } 2768 }) 2769 } 2770} 2771``` 2772 2773### translate<sup>9+</sup> 2774 2775translate(x: number, y: number): Promise\<void> 2776 2777根据输入的坐标对图片进行位置变换，使用Promise形式返回。 2778 2779translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2780 2781**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2782 2783**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2784 2785**系统能力：** SystemCapability.Multimedia.Image.Core 2786 2787**参数：** 2788 2789| 参数名 | 类型 | 必填 | 说明 | 2790| ------ | ------ | ---- | ----------- | 2791| x | number | 是 | 区域横坐标。单位：像素。 | 2792| y | number | 是 | 区域纵坐标。单位：像素。 | 2793 2794**返回值：** 2795 2796| 类型 | 说明 | 2797| -------------- | --------------------------- | 2798| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2799 2800**示例：** 2801 2802```ts 2803import { BusinessError } from '@kit.BasicServicesKit'; 2804 2805async function Translate() { 2806 let translateX: number = 50.0; 2807 let translateY: number = 10.0; 2808 if (pixelMap != undefined) { 2809 pixelMap.translate(translateX, translateY).then(() => { 2810 console.info('Succeeded in translating pixelmap.'); 2811 }).catch((err: BusinessError) => { 2812 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 2813 }) 2814 } 2815} 2816``` 2817 2818### translateSync<sup>12+</sup> 2819 2820translateSync(x: number, y: number): void 2821 2822根据输入的坐标对图片进行位置变换，同步返回结果。 2823 2824translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 2825 2826**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2827 2828**系统能力：** SystemCapability.Multimedia.Image.Core 2829 2830**参数：** 2831 2832| 参数名 | 类型 | 必填 | 说明 | 2833| -------- | -------------------- | ---- | ------------------------------- | 2834| x | number | 是 | 区域横坐标。单位：像素。 | 2835| y | number | 是 | 区域纵坐标。单位：像素。 | 2836 2837**错误码：** 2838 2839以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2840 2841| 错误码ID | 错误信息 | 2842| ------- | --------------------------------------------| 2843| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2844| 501 | Resource Unavailable | 2845 2846**示例：** 2847 2848```ts 2849import { BusinessError } from '@kit.BasicServicesKit'; 2850 2851async function TranslateSync() { 2852 let translateX : number = 50.0; 2853 let translateY : number = 10.0; 2854 if (pixelMap != undefined) { 2855 pixelMap.translateSync(translateX, translateY); 2856 } 2857} 2858``` 2859 2860### rotate<sup>9+</sup> 2861 2862rotate(angle: number, callback: AsyncCallback\<void>): void 2863 2864根据输入的角度对图片进行旋转，使用callback形式返回。 2865 2866> **说明：** 2867> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 2868> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 2869 2870**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2871 2872**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2873 2874**系统能力：** SystemCapability.Multimedia.Image.Core 2875 2876**参数：** 2877 2878| 参数名 | 类型 | 必填 | 说明 | 2879| -------- | -------------------- | ---- | ----------------------------- | 2880| angle | number | 是 | 图片旋转的角度。 | 2881| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行旋转成功，err为undefined，否则为错误对象。| 2882 2883**示例：** 2884 2885```ts 2886import { BusinessError } from '@kit.BasicServicesKit'; 2887 2888async function Rotate() { 2889 let angle: number = 90.0; 2890 if (pixelMap != undefined) { 2891 pixelMap.rotate(angle, (err: BusinessError) => { 2892 if (err) { 2893 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 2894 return; 2895 } else { 2896 console.info("Succeeded in rotating pixelmap."); 2897 } 2898 }) 2899 } 2900} 2901``` 2902 2903### rotate<sup>9+</sup> 2904 2905rotate(angle: number): Promise\<void> 2906 2907根据输入的角度对图片进行旋转，使用Promise形式返回。 2908 2909> **说明：** 2910> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 2911> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 2912 2913**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2914 2915**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2916 2917**系统能力：** SystemCapability.Multimedia.Image.Core 2918 2919**参数：** 2920 2921| 参数名 | 类型 | 必填 | 说明 | 2922| ------ | ------ | ---- | ----------------------------- | 2923| angle | number | 是 | 图片旋转的角度。 | 2924 2925**返回值：** 2926 2927| 类型 | 说明 | 2928| -------------- | --------------------------- | 2929| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2930 2931**示例：** 2932 2933```ts 2934import { BusinessError } from '@kit.BasicServicesKit'; 2935 2936async function Rotate() { 2937 let angle: number = 90.0; 2938 if (pixelMap != undefined) { 2939 pixelMap.rotate(angle).then(() => { 2940 console.info('Succeeded in rotating pixelmap.'); 2941 }).catch((err: BusinessError) => { 2942 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 2943 }) 2944 } 2945} 2946``` 2947 2948### rotateSync<sup>12+</sup> 2949 2950rotateSync(angle: number): void 2951 2952根据输入的角度对图片进行旋转，同步返回结果。 2953 2954> **说明：** 2955> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 2956> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 2957 2958**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2959 2960**系统能力：** SystemCapability.Multimedia.Image.Core 2961 2962**参数：** 2963 2964| 参数名 | 类型 | 必填 | 说明 | 2965| -------- | -------------------- | ---- | ----------------------------- | 2966| angle | number | 是 | 图片旋转的角度。 | 2967 2968**错误码：** 2969 2970以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2971 2972| 错误码ID | 错误信息 | 2973| ------- | --------------------------------------------| 2974| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2975| 501 | Resource Unavailable | 2976 2977**示例：** 2978 2979```ts 2980import { BusinessError } from '@kit.BasicServicesKit'; 2981 2982async function RotateSync() { 2983 let angle : number = 90.0; 2984 if (pixelMap != undefined) { 2985 pixelMap.rotateSync(angle); 2986 } 2987} 2988``` 2989 2990### flip<sup>9+</sup> 2991 2992flip(horizontal: boolean, vertical: boolean, callback: AsyncCallback\<void>): void 2993 2994根据输入的条件对图片进行翻转，使用callback形式返回。 2995 2996**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2997 2998**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2999 3000**系统能力：** SystemCapability.Multimedia.Image.Core 3001 3002**参数：** 3003 3004| 参数名 | 类型 | 必填 | 说明 | 3005| ---------- | -------------------- | ---- | ----------------------------- | 3006| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 3007| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 3008| callback | AsyncCallback\<void> | 是 | 回调函数，当对图片翻转成功，err为undefined，否则为错误对象。| 3009 3010**示例：** 3011 3012```ts 3013import { BusinessError } from '@kit.BasicServicesKit'; 3014 3015async function Flip() { 3016 let horizontal: boolean = true; 3017 let vertical: boolean = false; 3018 if (pixelMap != undefined) { 3019 pixelMap.flip(horizontal, vertical, (err: BusinessError) => { 3020 if (err) { 3021 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 3022 return; 3023 } else { 3024 console.info("Succeeded in flipping pixelmap."); 3025 } 3026 }) 3027 } 3028} 3029``` 3030 3031### flip<sup>9+</sup> 3032 3033flip(horizontal: boolean, vertical: boolean): Promise\<void> 3034 3035根据输入的条件对图片进行翻转，使用Promise形式返回。 3036 3037**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3038 3039**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3040 3041**系统能力：** SystemCapability.Multimedia.Image.Core 3042 3043**参数：** 3044 3045| 参数名 | 类型 | 必填 | 说明 | 3046| ---------- | ------- | ---- | --------- | 3047| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 3048| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 3049 3050**返回值：** 3051 3052| 类型 | 说明 | 3053| -------------- | --------------------------- | 3054| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3055 3056**示例：** 3057 3058```ts 3059import { BusinessError } from '@kit.BasicServicesKit'; 3060 3061async function Flip() { 3062 let horizontal: boolean = true; 3063 let vertical: boolean = false; 3064 if (pixelMap != undefined) { 3065 pixelMap.flip(horizontal, vertical).then(() => { 3066 console.info('Succeeded in flipping pixelmap.'); 3067 }).catch((err: BusinessError) => { 3068 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 3069 }) 3070 } 3071} 3072``` 3073 3074### flipSync<sup>12+</sup> 3075 3076flipSync(horizontal: boolean, vertical: boolean): void 3077 3078根据输入的条件对图片进行翻转并同步返回结果。 3079 3080**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3081 3082**系统能力：** SystemCapability.Multimedia.Image.Core 3083 3084**参数：** 3085 3086| 参数名 | 类型 | 必填 | 说明 | 3087| ---------- | -------------------- | ---- | ----------------------------- | 3088| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 3089| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 3090 3091**错误码：** 3092 3093以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3094 3095| 错误码ID | 错误信息 | 3096| ------- | --------------------------------------------| 3097| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3098| 501 | Resource Unavailable | 3099 3100**示例：** 3101 3102```ts 3103import { BusinessError } from '@kit.BasicServicesKit'; 3104 3105async function FlipSync() { 3106 let horizontal : boolean = true; 3107 let vertical : boolean = false; 3108 if (pixelMap != undefined) { 3109 pixelMap.flipSync(horizontal, vertical); 3110 } 3111} 3112``` 3113 3114### crop<sup>9+</sup> 3115 3116crop(region: Region, callback: AsyncCallback\<void>): void 3117 3118根据输入的尺寸对图片进行裁剪，使用callback形式返回。 3119 3120**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3121 3122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3123 3124**系统能力：** SystemCapability.Multimedia.Image.Core 3125 3126**参数：** 3127 3128| 参数名 | 类型 | 必填 | 说明 | 3129| -------- | -------------------- | ---- | ----------------------------- | 3130| region | [Region](#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 3131| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行裁剪成功，err为undefined，否则为错误对象。| 3132 3133**示例：** 3134 3135```ts 3136import { BusinessError } from '@kit.BasicServicesKit'; 3137 3138async function Crop() { 3139 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3140 if (pixelMap != undefined) { 3141 pixelMap.crop(region, (err: BusinessError) => { 3142 if (err) { 3143 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 3144 return; 3145 } else { 3146 console.info("Succeeded in cropping pixelmap."); 3147 } 3148 }) 3149 } 3150} 3151``` 3152 3153### crop<sup>9+</sup> 3154 3155crop(region: Region): Promise\<void> 3156 3157根据输入的尺寸对图片进行裁剪，使用Promise形式返回。 3158 3159**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3160 3161**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3162 3163**系统能力：** SystemCapability.Multimedia.Image.Core 3164 3165**参数：** 3166 3167| 参数名 | 类型 | 必填 | 说明 | 3168| ------ | ------------------ | ---- | ----------- | 3169| region | [Region](#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 3170 3171**返回值：** 3172 3173| 类型 | 说明 | 3174| -------------- | --------------------------- | 3175| Promise\<void> | Promise对象。无返回结果的Promise对象。| 3176 3177**示例：** 3178 3179```ts 3180import { BusinessError } from '@kit.BasicServicesKit'; 3181 3182async function Crop() { 3183 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3184 if (pixelMap != undefined) { 3185 pixelMap.crop(region).then(() => { 3186 console.info('Succeeded in cropping pixelmap.'); 3187 }).catch((err: BusinessError) => { 3188 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 3189 3190 }); 3191 } 3192} 3193``` 3194 3195### cropSync<sup>12+</sup> 3196 3197cropSync(region: Region): void 3198 3199根据输入的尺寸裁剪图片。 3200 3201**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3202 3203**系统能力：** SystemCapability.Multimedia.Image.Core 3204 3205**参数：** 3206 3207| 参数名 | 类型 | 必填 | 说明 | 3208| -------- | -------------------- | ---- | ----------------------------- | 3209| region | [Region](#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 3210 3211**错误码：** 3212 3213以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3214 3215| 错误码ID | 错误信息 | 3216| ------- | --------------------------------------------| 3217| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3218| 501 | Resource Unavailable | 3219 3220**示例：** 3221 3222```ts 3223import { BusinessError } from '@kit.BasicServicesKit'; 3224 3225async function CropSync() { 3226 let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 3227 if (pixelMap != undefined) { 3228 pixelMap.cropSync(region); 3229 } 3230} 3231``` 3232 3233### getColorSpace<sup>10+</sup> 3234 3235getColorSpace(): colorSpaceManager.ColorSpaceManager 3236 3237获取图像广色域信息。 3238 3239**系统能力：** SystemCapability.Multimedia.Image.Core 3240 3241**返回值：** 3242 3243| 类型 | 说明 | 3244| ----------------------------------- | ---------------- | 3245| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 图像广色域信息。 | 3246 3247**错误码：** 3248 3249以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3250 3251| 错误码ID | 错误信息 | 3252| ------- | --------------------------------------------| 3253| 62980101| If the image data abnormal. | 3254| 62980103| If the image data unsupport. | 3255| 62980115| If the image parameter invalid. | 3256 3257**示例：** 3258 3259```ts 3260async function GetColorSpace() { 3261 if (pixelMap != undefined) { 3262 let csm = pixelMap.getColorSpace(); 3263 } 3264} 3265``` 3266 3267### setColorSpace<sup>10+</sup> 3268 3269setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void 3270 3271设置图像广色域信息。 3272 3273**系统能力：** SystemCapability.Multimedia.Image.Core 3274 3275**参数：** 3276 3277| 参数名 | 类型 | 必填 | 说明 | 3278| ---------- | ----------------------------------- | ---- | --------------- | 3279| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 图像广色域信息。| 3280 3281**错误码：** 3282 3283以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3284 3285| 错误码ID | 错误信息 | 3286| ------- | --------------------------------------------| 3287| 62980111| The image source data is incomplete. | 3288| 62980115| If the image parameter invalid. | 3289 3290**示例：** 3291 3292```ts 3293import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3294async function SetColorSpace() { 3295 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3296 let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3297 if (pixelMap != undefined) { 3298 pixelMap.setColorSpace(csm); 3299 } 3300} 3301``` 3302 3303### applyColorSpace<sup>11+</sup> 3304 3305applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager, callback: AsyncCallback\<void>): void 3306 3307根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用callback形式返回。 3308 3309**系统能力：** SystemCapability.Multimedia.Image.Core 3310 3311**参数：** 3312 3313| 参数名 | 类型 | 必填 | 说明 | 3314| -------- | -------------------- | ---- | ----------------------------- | 3315| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 3316| callback | AsyncCallback\<void> | 是 | 回调函数。当对图像像素颜色进行色彩空间转换成功，err为undefined，否则为错误对象。| 3317 3318**错误码：** 3319 3320以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3321 3322| 错误码ID | 错误信息 | 3323| ------- | ------------------------------------------| 3324| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3325| 62980104| Failed to initialize the internal object. | 3326| 62980108| Failed to convert the color space. | 3327| 62980115| Invalid image parameter. | 3328 3329**示例：** 3330 3331```ts 3332import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3333import { BusinessError } from '@kit.BasicServicesKit'; 3334 3335async function ApplyColorSpace() { 3336 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3337 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3338 if (pixelMap != undefined) { 3339 pixelMap.applyColorSpace(targetColorSpace, (err: BusinessError) => { 3340 if (err) { 3341 console.error(`Failed to apply color space for pixelmap object, error code is ${error}`); 3342 return; 3343 } else { 3344 console.info('Succeeded in applying color space for pixelmap object.'); 3345 } 3346 }) 3347 } 3348} 3349``` 3350 3351### applyColorSpace<sup>11+</sup> 3352 3353applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void> 3354 3355根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用Promise形式返回。 3356 3357**系统能力：** SystemCapability.Multimedia.Image.Core 3358 3359**参数：** 3360 3361| 参数名 | 类型 | 必填 | 说明 | 3362| ------ | ------------------ | ---- | ----------- | 3363| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 3364 3365**返回值：** 3366 3367| 类型 | 说明 | 3368| -------------- | --------------------------- | 3369| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3370 3371**错误码：** 3372 3373以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3374 3375| 错误码ID | 错误信息 | 3376| ------- | ------------------------------------------| 3377| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 3378| 62980104| Failed to initialize the internal object. | 3379| 62980108| Failed to convert the color space. | 3380| 62980115| Invalid image parameter. | 3381 3382**示例：** 3383 3384```ts 3385import { colorSpaceManager } from '@kit.ArkGraphics2D'; 3386import { BusinessError } from '@kit.BasicServicesKit'; 3387 3388async function ApplyColorSpace() { 3389 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 3390 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 3391 if (pixelMap != undefined) { 3392 pixelMap.applyColorSpace(targetColorSpace).then(() => { 3393 console.info('Succeeded in applying color space for pixelmap object.'); 3394 }).catch((error: BusinessError) => { 3395 console.error(`Failed to apply color space for pixelmap object, error code is ${error}`); 3396 }) 3397 } 3398} 3399``` 3400 3401### toSdr<sup>12+<sup> 3402 3403toSdr(): Promise\<void> 3404 3405将HDR的图像内容转换为SDR的图像内容，异步使用Promise形式返回。 3406 3407**系统能力：** SystemCapability.Multimedia.Image.Core 3408 3409**返回值：** 3410 3411| 类型 | 说明 | 3412| -------------- | --------------------------- | 3413| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3414 3415**错误码：** 3416 3417以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3418 3419| 错误码ID | 错误信息 | 3420| ------- | --------------------------------------------| 3421| 62980137 | Invalid image operation. | 3422 3423**示例：** 3424 3425```ts 3426import image from '@ohos.multimedia.image'; 3427import resourceManager from '@ohos.resourceManager'; 3428import { BusinessError } from '@kit.BasicServicesKit'; 3429 3430// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 3431let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 3432//此处'hdr.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3433let img = context.resourceManager.getMediaContentSync($r('app.media.hdr')); 3434let imageSource = image.createImageSource(img.buffer.slice(0)); 3435let decodingOptions: image.DecodingOptions = { 3436 desiredDynamicRange: image.DecodingDynamicRange.AUTO 3437}; 3438let pixelmap = imageSource.createPixelMapSync(decodingOptions); 3439if (pixelmap != undefined) { 3440 console.info('Succeeded in creating pixelMap object.'); 3441 pixelmap.toSdr().then(() => { 3442 let imageInfo = pixelmap.getImageInfoSync(); 3443 console.info("after toSdr ,imageInfo isHdr:" + imageInfo.isHdr); 3444 }).catch((err: BusinessError) => { 3445 console.error(`Failed to set sdr. code is ${err.code}, message is ${err.message}`); 3446 }); 3447} else { 3448 console.info('Failed to create pixelMap.'); 3449} 3450``` 3451 3452### getMetadata<sup>12+</sup> 3453 3454getMetadata(key: HdrMetadataKey): HdrMetadataValue 3455 3456从PixelMap中获取元数据。 3457 3458**系统能力：** SystemCapability.Multimedia.Image.Core 3459 3460**参数：** 3461 3462| 参数名 | 类型 | 必填 | 说明 | 3463| ------------- | -------------------------------- | ---- | ---------------- | 3464| key | [HdrMetadataKey](#hdrmetadatakey12) | 是 | HDR元数据的关键字，可用于查询对应值。 | 3465 3466**返回值：** 3467 3468| 类型 | 说明 | 3469| --------------------------------- | --------------------------------- | 3470| [HdrMetadataValue](#hdrmetadatavalue12) | 返回元数据的值。 | 3471 3472**错误码：** 3473 3474以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3475 3476| 错误码ID | 错误信息 | 3477| ------- | --------------------------------------------| 3478| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 3479| 501 | Resource unavailable. | 3480| 62980173 | The DMA memory does not exist. | 3481| 62980302 | Memory copy failed. | 3482 3483**示例：** 3484 3485```ts 3486import { BusinessError } from '@kit.BasicServicesKit'; 3487import image from '@ohos.multimedia.image'; 3488 3489// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 3490let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 3491// 'app.media.test'需要替换为本地hdr图片。 3492let img = context.resourceManager.getMediaContentSync($r('app.media.test')); 3493let imageSource = image.createImageSource(img.buffer.slice(0)); 3494let decodingOptions: image.DecodingOptions = { 3495 desiredDynamicRange: image.DecodingDynamicRange.AUTO 3496}; 3497let pixelmap = imageSource.createPixelMapSync(decodingOptions); 3498if (pixelmap != undefined) { 3499 console.info('Succeeded in creating pixelMap object.'); 3500 try { 3501 let staticMetadata = pixelmap.getMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA); 3502 console.info("getmetadata:" + JSON.stringify(staticMetadata)); 3503 } catch (e) { 3504 console.info('pixelmap create failed' + e); 3505 } 3506} else { 3507 console.info('Failed to create pixelMap.'); 3508} 3509``` 3510 3511### setMetadata<sup>12+</sup> 3512 3513setMetadata(key: HdrMetadataKey, value: HdrMetadataValue): Promise\<void> 3514 3515设置PixelMap元数据。 3516 3517**系统能力：** SystemCapability.Multimedia.Image.Core 3518 3519**参数：** 3520 3521| 参数名 | 类型 | 必填 | 说明 | 3522| ------------- | -------------------------------- | ---- | ---------------- | 3523| key | [HdrMetadataKey](#hdrmetadatakey12) | 是 | HDR元数据的关键字，用于设置对应值。 | 3524| value | [HdrMetadataValue](#hdrmetadatavalue12) | 是 | 元数据的值。 | 3525 3526**返回值：** 3527 3528| 类型 | 说明 | 3529| -------------- | --------------------- | 3530| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3531 3532**错误码：** 3533 3534以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3535 3536| 错误码ID | 错误信息 | 3537| ------- | --------------------------------------------| 3538| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 3539| 501 | Resource unavailable. | 3540| 62980173 | The DMA memory does not exist. | 3541| 62980302 | Memory copy failed. | 3542 3543**示例：** 3544 3545```ts 3546import image from '@ohos.multimedia.image'; 3547import { BusinessError } from '@kit.BasicServicesKit'; 3548 3549let staticMetadata: image.HdrStaticMetadata = { 3550 displayPrimariesX: [1.1, 1.1, 1.1], 3551 displayPrimariesY: [1.2, 1.2, 1.2], 3552 whitePointX: 1.1, 3553 whitePointY: 1.2, 3554 maxLuminance: 2.1, 3555 minLuminance: 1.0, 3556 maxContentLightLevel: 2.1, 3557 maxFrameAverageLightLevel: 2.1, 3558}; 3559const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 3560let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } }; 3561image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 3562 pixelMap.setMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA, staticMetadata).then(() => { 3563 console.info('Succeeded in setting pixelMap metadata.'); 3564 }).catch((error: BusinessError) => { 3565 console.error(`Failed to set the metadata.code ${error.code},message is ${error.message}`); 3566 }) 3567}).catch((error: BusinessError) => { 3568 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 3569}) 3570 3571``` 3572 3573### setTransferDetached<sup>12+<sup> 3574 3575setTransferDetached(detached: boolean): void 3576 3577pixelmap在跨线程传输时，断开原线程的引用。适用于需立即释放pixelmap的场景。 3578 3579**系统能力：** SystemCapability.Multimedia.Image.Core 3580 3581**参数：** 3582 3583| 参数名 | 类型 | 必填 | 说明 | 3584| ------- | ------------------ | ---- | ----------------------------- | 3585| detached | boolean | 是 | true表示断开原线程引用，false表示不断开原线程引用。 | 3586 3587**错误码：** 3588 3589以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3590 3591| 错误码ID | 错误信息 | 3592| ------- | --------------------------------------------| 3593| 501 | Resource Unavailable | 3594 3595**示例：** 3596 3597```ts 3598import { BusinessError } from '@kit.BasicServicesKit'; 3599import image from '@ohos.multimedia.image'; 3600import taskpool from '@ohos.taskpool'; 3601 3602@Concurrent 3603// 子线程方法。 3604async function loadPixelMap(rawFileDescriptor: number): Promise<PixelMap> { 3605 // 创建imageSource。 3606 const imageSource = image.createImageSource(rawFileDescriptor); 3607 // 创建pixelMap。 3608 const pixelMap = imageSource.createPixelMapSync(); 3609 // 释放imageSource。 3610 imageSource.release(); 3611 // 使pixelMap在跨线程传输完成后，断开原线程的引用。 3612 pixelMap.setTransferDetached(true); 3613 // 返回pixelMap给主线程。 3614 return pixelMap; 3615} 3616 3617struct Demo { 3618 @State pixelMap: PixelMap | undefined = undefined; 3619 // 主线程方法。 3620 private loadImageFromThread(): void { 3621 const resourceMgr = this.getUIContext().getHostContext()?.resourceManager; 3622 // 此处‘example.jpg’仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 3623 resourceMgr.getRawFd('example.jpg').then(rawFileDescriptor => { 3624 taskpool.execute(loadPixelMap, rawFileDescriptor).then(pixelMap => { 3625 if (pixelMap) { 3626 this.pixelMap = pixelMap as PixelMap; 3627 console.log('Succeeded in creating pixelMap.'); 3628 // 主线程释放pixelMap。由于子线程返回pixelMap时已调用setTransferDetached，所以此处能够立即释放pixelMap。 3629 this.pixelMap.release(); 3630 } else { 3631 console.error('Failed to create pixelMap.'); 3632 } 3633 }); 3634 }); 3635 } 3636} 3637``` 3638 3639### marshalling<sup>10+</sup> 3640 3641marshalling(sequence: rpc.MessageSequence): void 3642 3643将PixelMap序列化后写入MessageSequence。 3644 3645**系统能力：** SystemCapability.Multimedia.Image.Core 3646 3647**参数：** 3648 3649| 参数名 | 类型 | 必填 | 说明 | 3650| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 3651| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 3652 3653**错误码：** 3654 3655以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3656 3657| 错误码ID | 错误信息 | 3658| ------- | --------------------------------------------| 3659| 62980115 | Invalid image parameter. | 3660| 62980097 | IPC error. | 3661 3662**示例：** 3663 3664```ts 3665import { image } from '@kit.ImageKit'; 3666import { rpc } from '@kit.IPCKit'; 3667 3668class MySequence implements rpc.Parcelable { 3669 pixel_map: image.PixelMap; 3670 constructor(conPixelMap : image.PixelMap) { 3671 this.pixel_map = conPixelMap; 3672 } 3673 marshalling(messageSequence : rpc.MessageSequence) { 3674 this.pixel_map.marshalling(messageSequence); 3675 console.info('marshalling'); 3676 return true; 3677 } 3678 unmarshalling(messageSequence : rpc.MessageSequence) { 3679 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: image.PixelMap) => { 3680 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: image.PixelMap) => { 3681 this.pixel_map = pixelMap; 3682 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 3683 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 3684 }) 3685 }) 3686 }); 3687 return true; 3688 } 3689} 3690async function Marshalling() { 3691 const color: ArrayBuffer = new ArrayBuffer(96); 3692 let bufferArr: Uint8Array = new Uint8Array(color); 3693 for (let i = 0; i < bufferArr.length; i++) { 3694 bufferArr[i] = 0x80; 3695 } 3696 let opts: image.InitializationOptions = { 3697 editable: true, 3698 pixelFormat: image.PixelMapFormat.BGRA_8888, 3699 size: { height: 4, width: 6 }, 3700 alphaType: image.AlphaType.UNPREMUL 3701 } 3702 let pixelMap: image.PixelMap | undefined = undefined; 3703 image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 3704 pixelMap = srcPixelMap; 3705 }) 3706 if (pixelMap != undefined) { 3707 // 序列化。 3708 let parcelable: MySequence = new MySequence(pixelMap); 3709 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 3710 data.writeParcelable(parcelable); 3711 3712 // 反序列化 rpc获取到data。 3713 let ret: MySequence = new MySequence(pixelMap); 3714 data.readParcelable(ret); 3715 } 3716} 3717``` 3718 3719### unmarshalling<sup>10+</sup> 3720 3721unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap> 3722 3723从MessageSequence中获取PixelMap， 3724如需使用同步方式创建PixelMap可使用：[createPixelMapFromParcel](#imagecreatepixelmapfromparcel11)。 3725 3726**系统能力：** SystemCapability.Multimedia.Image.Core 3727 3728**参数：** 3729 3730| 参数名 | 类型 | 必填 | 说明 | 3731| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 3732| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 3733 3734**返回值：** 3735 3736| 类型 | 说明 | 3737| -------------------------------- | --------------------- | 3738| Promise\<[PixelMap](#pixelmap7)> |Promise对象，返回PixelMap。 | 3739 3740**错误码：** 3741 3742以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3743 3744| 错误码ID | 错误信息 | 3745| ------- | --------------------------------------------| 3746| 62980115 | Invalid image parameter. | 3747| 62980097 | IPC error. | 3748| 62980096 | The operation failed. | 3749 3750**示例：** 3751 3752```ts 3753import { image } from '@kit.ImageKit'; 3754import { rpc } from '@kit.IPCKit'; 3755 3756class MySequence implements rpc.Parcelable { 3757 pixel_map: image.PixelMap; 3758 constructor(conPixelMap: image.PixelMap) { 3759 this.pixel_map = conPixelMap; 3760 } 3761 marshalling(messageSequence: rpc.MessageSequence) { 3762 this.pixel_map.marshalling(messageSequence); 3763 console.info('marshalling'); 3764 return true; 3765 } 3766 unmarshalling(messageSequence: rpc.MessageSequence) { 3767 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : image.PixelMap) => { 3768 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : image.PixelMap) => { 3769 this.pixel_map = pixelMap; 3770 pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => { 3771 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 3772 }) 3773 }) 3774 }); 3775 return true; 3776 } 3777} 3778async function Unmarshalling() { 3779 const color: ArrayBuffer = new ArrayBuffer(96); 3780 let bufferArr: Uint8Array = new Uint8Array(color); 3781 for (let i = 0; i < bufferArr.length; i++) { 3782 bufferArr[i] = 0x80; 3783 } 3784 let opts: image.InitializationOptions = { 3785 editable: true, 3786 pixelFormat: image.PixelMapFormat.BGRA_8888, 3787 size: { height: 4, width: 6 }, 3788 alphaType: image.AlphaType.UNPREMUL 3789 } 3790 let pixelMap: image.PixelMap | undefined = undefined; 3791 image.createPixelMap(color, opts).then((srcPixelMap : image.PixelMap) => { 3792 pixelMap = srcPixelMap; 3793 }) 3794 if (pixelMap != undefined) { 3795 // 序列化。 3796 let parcelable: MySequence = new MySequence(pixelMap); 3797 let data : rpc.MessageSequence = rpc.MessageSequence.create(); 3798 data.writeParcelable(parcelable); 3799 3800 // 反序列化 rpc获取到data。 3801 let ret : MySequence = new MySequence(pixelMap); 3802 data.readParcelable(ret); 3803 } 3804} 3805``` 3806 3807### release<sup>7+</sup> 3808 3809release():Promise\<void> 3810 3811释放PixelMap对象，使用Promise形式返回释放结果。 3812 3813ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 3814 3815**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3816 3817**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3818 3819**系统能力：** SystemCapability.Multimedia.Image.Core 3820 3821**返回值：** 3822 3823| 类型 | 说明 | 3824| -------------- | ------------------------------- | 3825| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3826 3827**示例：** 3828 3829```ts 3830import { BusinessError } from '@kit.BasicServicesKit'; 3831 3832async function Release() { 3833 if (pixelMap != undefined) { 3834 pixelMap.release().then(() => { 3835 console.info('Succeeded in releasing pixelmap object.'); 3836 }).catch((error: BusinessError) => { 3837 console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`); 3838 }) 3839 } 3840} 3841``` 3842 3843### release<sup>7+</sup> 3844 3845release(callback: AsyncCallback\<void>): void 3846 3847释放PixelMap对象，使用callback形式返回释放结果。 3848 3849ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 3850 3851**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 3852 3853**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3854 3855**系统能力：** SystemCapability.Multimedia.Image.Core 3856 3857**参数：** 3858 3859| 参数名 | 类型 | 必填 | 说明 | 3860| -------- | -------------------- | ---- | ------------------ | 3861| callback | AsyncCallback\<void> | 是 | 回调函数。当对PixelMap对象释放成功，err为undefined，否则为错误对象。 | 3862 3863**示例：** 3864 3865```ts 3866import { BusinessError } from '@kit.BasicServicesKit'; 3867 3868async function Release() { 3869 if (pixelMap != undefined) { 3870 pixelMap.release((err: BusinessError) => { 3871 if (err) { 3872 console.error(`Failed to release pixelmap object. code is ${err.code}, message is ${err.message}`); 3873 return; 3874 } else { 3875 console.info('Succeeded in releasing pixelmap object.'); 3876 } 3877 }) 3878 } 3879} 3880``` 3881 3882### convertPixelFormat<sup>12+</sup> 3883 3884convertPixelFormat(targetPixelFormat: PixelMapFormat): Promise\<void> 3885 3886YUV和RGB类型互转，目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转。 3887 3888从API18开始，可用于ASTC_4x4类型转为RGBA_8888类型，目前仅支持ASTC_4x4转为RGBA_8888。 3889 3890> **注意：** 3891> 仅在ASTC_4x4格式的图像需要进行像素访问时，建议调用此接口将ASTC_4x4类型转为RGBA_8888类型。由于使用ASTC_4x4反解为RGBA_8888时延较高，其余情况下不推荐使用。 3892 3893**系统能力：** SystemCapability.Multimedia.Image.Core 3894 3895**参数：** 3896 3897| 参数名 | 类型 | 必填 | 说明 | 3898| -------- | -------------------- | ---- | ------------------ | 3899| targetPixelFormat | [PixelMapFormat](#pixelmapformat7) | 是 | 目标像素格式，用于YUV和RGB类型互转，或者ASTC_4x4类型转为RGBA_8888类型。目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转，ASTC_4x4转为RGBA_8888。 | 3900 3901**返回值：** 3902 3903| 类型 | 说明 | 3904| -------------- | ------------------------------- | 3905| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3906 3907**错误码：** 3908 3909以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3910 3911| 错误码ID | 错误信息 | 3912| ------- | --------------------------------------------| 3913| 62980111 | The image source data is incomplete. | 3914| 62980115 | Invalid input parameter. | 3915| 62980178 | Failed to create the pixelmap. | 3916| 62980274 | The conversion failed | 3917| 62980276 | The type to be converted is an unsupported target pixel format| 3918 3919**示例：** 3920 3921```ts 3922import { BusinessError } from '@kit.BasicServicesKit'; 3923 3924if (pixelMap != undefined) { 3925 // 设置目标像素格式为NV12。 3926 let targetPixelFormat = image.PixelMapFormat.NV12; 3927 pixelMap.convertPixelFormat(targetPixelFormat).then(() => { 3928 // pixelMap转换成NV12格式成功。 3929 console.info('PixelMapFormat convert Succeeded'); 3930 }).catch((error: BusinessError) => { 3931 // pixelMap转换成NV12格式失败。 3932 console.error(`PixelMapFormat convert Failed. code is ${error.code}, message is ${error.message}`); 3933 }) 3934} 3935``` 3936 3937### setMemoryNameSync<sup>13+</sup> 3938 3939setMemoryNameSync(name: string): void 3940 3941设置PixelMap内存标识符。 3942 3943**系统能力：** SystemCapability.Multimedia.Image.Core 3944 3945**参数：** 3946 3947| 参数名 | 类型 | 必填 | 说明 | 3948| ------------- | -------------------------------- | ---- | ---------------- | 3949| name | string | 是 | pixelmap内存标识符，只允许DMA和ASHMEM内存形式的piexelmap设置，支持1-31位长度。 | 3950 3951**错误码：** 3952 3953以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 3954 3955| 错误码ID | 错误信息 | 3956| ------- | --------------------------------------------| 3957| 401 | Parameter error. Possible causes: 1.The length of the input parameter is too long. 2.Parameter verification failed. | 3958| 501 | Resource unavailable. | 3959| 62980286 | Memory format not supported. | 3960 3961**示例：** 3962 3963```ts 3964import { BusinessError } from '@ohos.base'; 3965 3966async function SetMemoryNameSync() { 3967 if (pixelMap != undefined) { 3968 try { 3969 pixelMap.setMemoryNameSync("PixelMapName Test"); 3970 } catch(e) { 3971 let error = e as BusinessError; 3972 console.error(`setMemoryNameSync error. code is ${error.code}, message is ${error.message}`); 3973 } 3974 } 3975} 3976``` 3977 3978## image.createImageSource 3979 3980createImageSource(uri: string): ImageSource 3981 3982通过传入的uri创建ImageSource实例。 3983 3984 3985**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3986 3987**系统能力：** SystemCapability.Multimedia.Image.ImageSource 3988 3989**参数：** 3990 3991| 参数名 | 类型 | 必填 | 说明 | 3992| ------ | ------ | ---- | ---------------------------------- | 3993| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng .heic<sup>12+</sup>（不同硬件设备支持情况不同） [.svg<sup>10+</sup>](#svg标签说明) .ico<sup>11+</sup>。 | 3994 3995**返回值：** 3996 3997| 类型 | 说明 | 3998| --------------------------- | -------------------------------------------- | 3999| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4000 4001**示例：** 4002 4003```ts 4004// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4005let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4006//此处'test.jpg'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 4007const path: string = context.filesDir + "/test.jpg"; 4008const imageSourceApi: image.ImageSource = image.createImageSource(path); 4009``` 4010 4011## image.createImageSource<sup>9+</sup> 4012 4013createImageSource(uri: string, options: SourceOptions): ImageSource 4014 4015通过传入的uri创建ImageSource实例。 4016 4017**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4018 4019**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4020 4021**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4022 4023**参数：** 4024 4025| 参数名 | 类型 | 必填 | 说明 | 4026| ------- | ------------------------------- | ---- | ----------------------------------- | 4027| uri | string | 是 | 图片路径，当前仅支持应用沙箱路径。</br>当前支持格式有：.jpg .png .gif .bmp .webp .dng .heic<sup>12+</sup>（不同硬件设备支持情况不同）[.svg<sup>10+</sup>](#svg标签说明) .ico<sup>11+</sup>。 | 4028| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。| 4029 4030**返回值：** 4031 4032| 类型 | 说明 | 4033| --------------------------- | -------------------------------------------- | 4034| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4035 4036**示例：** 4037 4038```ts 4039let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 4040// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4041let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4042//此处'test.png'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 4043const path: string = context.filesDir + "/test.png"; 4044let imageSourceApi: image.ImageSource = image.createImageSource(path, sourceOptions); 4045``` 4046 4047## image.createImageSource<sup>7+</sup> 4048 4049createImageSource(fd: number): ImageSource 4050 4051通过传入文件描述符来创建ImageSource实例。 4052 4053**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4054 4055**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4056 4057**参数：** 4058 4059| 参数名 | 类型 | 必填 | 说明 | 4060| ------ | ------ | ---- | ------------- | 4061| fd | number | 是 | 文件描述符fd。| 4062 4063**返回值：** 4064 4065| 类型 | 说明 | 4066| --------------------------- | -------------------------------------------- | 4067| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4068 4069**示例：** 4070 4071```ts 4072import { fileIo as fs } from '@kit.CoreFileKit'; 4073 4074// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4075let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4076//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 4077let filePath: string = context.filesDir + "/test.jpg"; 4078let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 4079const imageSourceApi: image.ImageSource = image.createImageSource(file.fd); 4080``` 4081 4082## image.createImageSource<sup>9+</sup> 4083 4084createImageSource(fd: number, options: SourceOptions): ImageSource 4085 4086通过传入文件描述符来创建ImageSource实例。 4087 4088**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4089 4090**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4091 4092**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4093 4094**参数：** 4095 4096| 参数名 | 类型 | 必填 | 说明 | 4097| ------- | ------------------------------- | ---- | ----------------------------------- | 4098| fd | number | 是 | 文件描述符fd。 | 4099| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。| 4100 4101**返回值：** 4102 4103| 类型 | 说明 | 4104| --------------------------- | -------------------------------------------- | 4105| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4106 4107**示例：** 4108 4109```ts 4110import { fileIo as fs } from '@kit.CoreFileKit'; 4111 4112let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 4113// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4114let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4115//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4116const filePath: string = context.filesDir + "/test.jpg"; 4117let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 4118const imageSourceApi: image.ImageSource = image.createImageSource(file.fd, sourceOptions); 4119``` 4120 4121## image.createImageSource<sup>9+</sup> 4122 4123createImageSource(buf: ArrayBuffer): ImageSource 4124 4125通过缓冲区创建ImageSource实例。buf数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用[image.createPixelMapSync](#createpixelmapsync12)这一类接口。 4126 4127**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4128 4129**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4130 4131**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4132 4133**参数：** 4134 4135| 参数名 | 类型 | 必填 | 说明 | 4136| ------ | ----------- | ---- | ---------------- | 4137| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 4138 4139**返回值：** 4140 4141| 类型 | 说明 | 4142| --------------------------- | -------------------------------------------- | 4143| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4144 4145 4146**示例：** 4147 4148```ts 4149const buf: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 4150const imageSourceApi: image.ImageSource = image.createImageSource(buf); 4151``` 4152 4153## image.createImageSource<sup>9+</sup> 4154 4155createImageSource(buf: ArrayBuffer, options: SourceOptions): ImageSource 4156 4157通过缓冲区创建ImageSource实例。buf数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用[image.createPixelMapSync](#createpixelmapsync12)这一类接口。 4158 4159**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4160 4161**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4162 4163**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4164 4165**参数：** 4166 4167| 参数名 | 类型 | 必填 | 说明 | 4168| ------ | -------------------------------- | ---- | ------------------------------------ | 4169| buf | ArrayBuffer | 是 | 图像缓冲区数组。 | 4170| options | [SourceOptions](#sourceoptions9) | 是 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4171 4172**返回值：** 4173 4174| 类型 | 说明 | 4175| --------------------------- | -------------------------------------------- | 4176| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4177 4178**示例：** 4179 4180```ts 4181const data: ArrayBuffer = new ArrayBuffer(112); 4182let sourceOptions: image.SourceOptions = { sourceDensity: 120 }; 4183const imageSourceApi: image.ImageSource = image.createImageSource(data, sourceOptions); 4184``` 4185 4186## image.createImageSource<sup>11+</sup> 4187 4188createImageSource(rawfile: resourceManager.RawFileDescriptor, options?: SourceOptions): ImageSource 4189 4190通过图像资源文件的RawFileDescriptor创建ImageSource实例。 4191 4192**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4193 4194**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4195 4196**参数：** 4197 4198| 参数名 | 类型 | 必填 | 说明 | 4199| ------ | -------------------------------- | ---- | ------------------------------------ | 4200| rawfile | [resourceManager.RawFileDescriptor](../apis-localization-kit/js-apis-resource-manager.md#rawfiledescriptor9) | 是 | 图像资源文件的RawFileDescriptor。 | 4201| options | [SourceOptions](#sourceoptions9) | 否 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4202 4203**返回值：** 4204 4205| 类型 | 说明 | 4206| --------------------------- | -------------------------------------------- | 4207| [ImageSource](#imagesource) | 返回ImageSource类实例，失败时返回undefined。 | 4208 4209**示例：** 4210 4211```ts 4212import { resourceManager } from '@kit.LocalizationKit'; 4213 4214// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4215let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4216// 获取resourceManager资源管理器。 4217const resourceMgr: resourceManager.ResourceManager = context.resourceManager; 4218//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4219resourceMgr.getRawFd('test.jpg').then((rawFileDescriptor: resourceManager.RawFileDescriptor) => { 4220 const imageSourceApi: image.ImageSource = image.createImageSource(rawFileDescriptor); 4221}).catch((error: BusinessError) => { 4222 console.error(`Failed to get RawFileDescriptor.code is ${error.code}, message is ${error.message}`); 4223}) 4224``` 4225 4226## image.CreateIncrementalSource<sup>9+</sup> 4227 4228CreateIncrementalSource(buf: ArrayBuffer): ImageSource 4229 4230通过缓冲区以增量的方式创建ImageSource实例，IncrementalSource不支持读写Exif信息。 4231 4232以增量方式创建的ImageSource实例，仅支持使用以下功能，同步、异步callback、异步Promise均支持。 4233- 获取图片信息：指定序号-[getImageInfo](#getimageinfo)、直接获取-[getImageInfo](#getimageinfo-1) 4234- 获取图片中给定索引处图像的指定属性键的值：[getImageProperty](#getimageproperty11) 4235- 批量获取图片中的指定属性键的值：[getImageProperties](#getimageproperties12) 4236- 更新增量数据：[updateData](#updatedata9) 4237- 创建PixelMap对象：通过图片解码参数创建-[createPixelMap](#createpixelmap7)、通过默认参数创建-[createPixelMap](#createpixelmap7-1) 、通过图片解码参数-[createPixelMap](#createpixelmap7-2) 4238- 释放ImageSource实例：[release](#release) 4239 4240**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4241 4242**参数：** 4243 4244| 参数名 | 类型 | 必填 | 说明 | 4245| ------- | ------------| ---- | ----------| 4246| buf | ArrayBuffer | 是 | 增量数据。| 4247 4248**返回值：** 4249 4250| 类型 | 说明 | 4251| --------------------------- | --------------------------------- | 4252| [ImageSource](#imagesource) | 返回ImageSource，失败时返回undefined。 | 4253 4254**示例：** 4255 4256```ts 4257// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4258let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4259let imageArray = context.resourceManager.getMediaContentSync($r('app.media.startIcon')); // 获取图像资源。 4260// 此处'app.media.startIcon'仅作示例，请开发者自行替换，否则imageArray创建失败会导致后续无法正常执行。 4261let splitBuff1 = imageArray.slice(0, imageArray.byteLength / 2); // 分片。 4262let splitBuff2 = imageArray.slice(imageArray.byteLength / 2); 4263const imageSourceIncrementalSApi: image.ImageSource = image.CreateIncrementalSource(new ArrayBuffer(imageArray.byteLength)); 4264imageSourceIncrementalSApi.updateData(splitBuff1, false, 0, splitBuff1.byteLength).then(() => { 4265 imageSourceIncrementalSApi.updateData(splitBuff2, true, 0, splitBuff2.byteLength).then(() => { 4266 let pixelMap = imageSourceIncrementalSApi.createPixelMapSync(); 4267 let imageInfo = pixelMap.getImageInfoSync(); 4268 console.info('Succeeded in creating pixelMap'); 4269 }).catch((error : BusinessError) => { 4270 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4271 }) 4272}).catch((error : BusinessError) => { 4273 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4274}) 4275``` 4276 4277## image.CreateIncrementalSource<sup>9+</sup> 4278 4279CreateIncrementalSource(buf: ArrayBuffer, options?: SourceOptions): ImageSource 4280 4281通过缓冲区以增量的方式创建ImageSource实例，IncrementalSource不支持读写Exif信息。 4282 4283此接口支持的功能与[CreateIncrementalSource(buf: ArrayBuffer): ImageSource](#imagecreateincrementalsource9)所生成的实例支持的功能相同。 4284 4285**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4286 4287**参数：** 4288 4289| 参数名 | 类型 | 必填 | 说明 | 4290| ------- | ------------------------------- | ---- | ------------------------------------ | 4291| buf | ArrayBuffer | 是 | 增量数据。 | 4292| options | [SourceOptions](#sourceoptions9) | 否 | 图片属性，包括图片像素密度、像素格式和图片尺寸。 | 4293 4294**返回值：** 4295 4296| 类型 | 说明 | 4297| --------------------------- | --------------------------------- | 4298| [ImageSource](#imagesource) | 返回ImageSource，失败时返回undefined。 | 4299 4300**示例：** 4301 4302```ts 4303// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4304let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4305let imageArray = context.resourceManager.getMediaContentSync($r('app.media.startIcon')) // 获取图像资源。 4306// 此处'app.media.startIcon'仅作示例，请开发者自行替换，否则imageArray创建失败会导致后续无法正常执行。 4307let splitBuff1 = imageArray.slice(0, imageArray.byteLength / 2); // 分片。 4308let splitBuff2 = imageArray.slice(imageArray.byteLength / 2); 4309let sourceOptions: image.SourceOptions = { sourceDensity: 120}; 4310 4311const imageSourceIncrementalSApi: image.ImageSource = image.CreateIncrementalSource(new ArrayBuffer(imageArray.byteLength), sourceOptions); 4312imageSourceIncrementalSApi.updateData(splitBuff1, false, 0, splitBuff1.byteLength).then(() => { 4313 imageSourceIncrementalSApi.updateData(splitBuff2, true, 0, splitBuff2.byteLength).then(() => { 4314 let pixelMap = imageSourceIncrementalSApi.createPixelMapSync(); 4315 let imageInfo = pixelMap.getImageInfoSync(); 4316 console.info('Succeeded in creating pixelMap'); 4317 }).catch((error : BusinessError) => { 4318 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4319 }) 4320}).catch((error : BusinessError) => { 4321 console.error(`Failed to updateData error code is ${error.code}, message is ${error.message}`); 4322}) 4323``` 4324 4325## ImageSource 4326 4327ImageSource类，用于获取图片相关信息。在调用ImageSource的方法前，需要先通过[createImageSource](#imagecreateimagesource)构建一个ImageSource实例。 4328 4329### 属性 4330 4331**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4332 4333| 名称 | 类型 | 可读 | 可写 | 说明 | 4334| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 4335| supportedFormats | Array\<string> | 是 | 否 | 支持的图片格式，包括：png，jpeg，bmp，gif，webp，dng，heic<sup>12+</sup>（不同硬件设备支持情况不同）。 | 4336 4337### getImageInfo 4338 4339getImageInfo(index: number, callback: AsyncCallback\<ImageInfo>): void 4340 4341获取指定序号的图片信息，使用callback形式返回图片信息。 4342 4343**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4344 4345**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4346 4347**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4348 4349**参数：** 4350 4351| 参数名 | 类型 | 必填 | 说明 | 4352| -------- | -------------------------------------- | ---- | ---------------------------------------- | 4353| index | number | 是 | 创建ImageSource时的序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。 | 4354| callback | AsyncCallback<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图片信息成功，err为undefined，data为获取到的图片信息；否则为错误对象。 | 4355 4356**示例：** 4357 4358```ts 4359import { BusinessError } from '@kit.BasicServicesKit'; 4360 4361imageSourceApi.getImageInfo(0, (error: BusinessError, imageInfo: image.ImageInfo) => { 4362 if (error) { 4363 console.error(`Failed to obtain the image information.code is ${error.code}, message is ${error.message}`); 4364 } else { 4365 console.info('Succeeded in obtaining the image information.'); 4366 } 4367}) 4368``` 4369 4370### getImageInfo 4371 4372getImageInfo(callback: AsyncCallback\<ImageInfo>): void 4373 4374获取图片信息，使用callback形式返回图片信息。 4375 4376**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4377 4378**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4379 4380**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4381 4382**参数：** 4383 4384| 参数名 | 类型 | 必填 | 说明 | 4385| -------- | -------------------------------------- | ---- | ---------------------------------------- | 4386| callback | AsyncCallback<[ImageInfo](#imageinfo)> | 是 | 回调函数。当获取图片信息成功，err为undefined，data为获取到的图片信息；否则为错误对象。 | 4387 4388**示例：** 4389 4390```ts 4391import { BusinessError } from '@kit.BasicServicesKit'; 4392 4393imageSourceApi.getImageInfo((err: BusinessError, imageInfo: image.ImageInfo) => { 4394 if (err) { 4395 console.error(`Failed to obtain the image information.code is ${err.code}, message is ${err.message}`); 4396 } else { 4397 console.info('Succeeded in obtaining the image information.'); 4398 } 4399}) 4400``` 4401 4402### getImageInfo 4403 4404getImageInfo(index?: number): Promise\<ImageInfo> 4405 4406获取图片信息，使用Promise形式返回图片信息。 4407 4408**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 4409 4410**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4411 4412**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4413 4414**参数：** 4415 4416| 参数名| 类型 | 必填 | 说明 | 4417| ----- | ------ | ---- | ------------------------------------- | 4418| index | number | 否 | 创建ImageSource时的序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。 | 4419 4420**返回值：** 4421 4422| 类型 | 说明 | 4423| -------------------------------- | ---------------------- | 4424| Promise<[ImageInfo](#imageinfo)> | Promise对象，返回获取到的图片信息。 | 4425 4426**示例：** 4427 4428```ts 4429import { BusinessError } from '@kit.BasicServicesKit'; 4430 4431imageSourceApi.getImageInfo(0) 4432 .then((imageInfo: image.ImageInfo) => { 4433 console.info('Succeeded in obtaining the image information.'); 4434 }).catch((error: BusinessError) => { 4435 console.error(`Failed to obtain the image information.code is ${error.code}, message is ${error.message}`); 4436 }) 4437``` 4438 4439### getImageInfoSync<sup>12+</sup> 4440 4441getImageInfoSync(index?: number): ImageInfo 4442 4443获取指定序号的图片信息，使用同步形式返回图片信息。 4444 4445**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4446 4447**参数：** 4448 4449| 参数名| 类型 | 必填 | 说明 | 4450| ----- | ------ | ---- | ------------------------------------- | 4451| index | number | 否 | 创建ImageSource时的序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。 | 4452 4453**返回值：** 4454 4455| 类型 | 说明 | 4456| -------------------------------- | ---------------------- | 4457| [ImageInfo](#imageinfo) | 同步返回获取到的图片信息。 | 4458 4459**示例：** 4460 4461```ts 4462import { image } from '@kit.ImageKit'; 4463 4464// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 4465let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 4466//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 4467let filePath: string = context.filesDir + "/test.jpg"; 4468let imageSource = image.createImageSource(filePath); 4469let imageInfo = imageSource.getImageInfoSync(0); 4470if (imageInfo == undefined) { 4471 console.error('Failed to obtain the image information.'); 4472} else { 4473 console.info('Succeeded in obtaining the image information.'); 4474 console.info('imageInfo.size.height:' + imageInfo.size.height); 4475 console.info('imageInfo.size.width:' + imageInfo.size.width); 4476} 4477``` 4478 4479### getImageProperty<sup>11+</sup> 4480 4481getImageProperty(key:PropertyKey, options?: ImagePropertyOptions): Promise\<string> 4482 4483获取图片中给定索引处图像的指定属性键的值，用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4484 4485**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4486 4487**参数：** 4488 4489| 参数名 | 类型 | 必填 | 说明 | 4490| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4491| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4492| options | [ImagePropertyOptions](#imagepropertyoptions11) | 否 | 图片属性，包括图片序号与默认属性值。 | 4493 4494**返回值：** 4495 4496| 类型 | 说明 | 4497| ---------------- | ----------------------------------------------------------------- | 4498| Promise\<string> | Promise对象，返回图片属性值，如获取失败则返回属性默认值。 | 4499 4500**错误码：** 4501 4502以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4503 4504| 错误码ID | 错误信息 | 4505| ------- | --------------------------------------------| 4506| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4507| 62980096 | The operation failed. | 4508| 62980103 | The image data is not supported. | 4509| 62980110 | The image source data is incorrect. | 4510| 62980111 | The image source data is incomplete. | 4511| 62980112 | The image format does not match. | 4512| 62980113 | Unknown image format. | 4513| 62980115 | Invalid image parameter. | 4514| 62980116| Failed to decode the image. | 4515| 62980118 | Failed to create the image plugin. | 4516| 62980122 | Failed to decode the image header. | 4517| 62980123| Images in EXIF format are not supported. | 4518| 62980135| The EXIF value is invalid. | 4519 4520**示例：** 4521 4522```ts 4523import { BusinessError } from '@kit.BasicServicesKit'; 4524 4525let options: image.ImagePropertyOptions = { index: 0, defaultValue: '9999' } 4526imageSourceApi.getImageProperty(image.PropertyKey.BITS_PER_SAMPLE, options) 4527.then((data: string) => { 4528 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4529}).catch((error: BusinessError) => { 4530 console.error('Failed to get the value of the specified attribute key of the image.'); 4531}) 4532``` 4533 4534### getImageProperty<sup>(deprecated)</sup> 4535 4536getImageProperty(key:string, options?: GetImagePropertyOptions): Promise\<string> 4537 4538获取图片中给定索引处图像的指定属性键的值，用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4539 4540> **说明：** 4541> 4542> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4543 4544**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4545 4546**参数：** 4547 4548| 参数名 | 类型 | 必填 | 说明 | 4549| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4550| key | string | 是 | 图片属性名。 | 4551| options | [GetImagePropertyOptions](#getimagepropertyoptionsdeprecated) | 否 | 图片属性，包括图片序号与默认属性值。 | 4552 4553**返回值：** 4554 4555| 类型 | 说明 | 4556| ---------------- | ----------------------------------------------------------------- | 4557| Promise\<string> | Promise对象，返回图片属性值，如获取失败则返回属性默认值。 | 4558 4559**示例：** 4560 4561```ts 4562import { BusinessError } from '@kit.BasicServicesKit'; 4563 4564imageSourceApi.getImageProperty("BitsPerSample") 4565 .then((data: string) => { 4566 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4567 }).catch((error: BusinessError) => { 4568 console.error('Failed to get the value of the specified attribute key of the image.'); 4569 }) 4570``` 4571 4572### getImageProperty<sup>(deprecated)</sup> 4573 4574getImageProperty(key:string, callback: AsyncCallback\<string>): void 4575 4576获取图片中给定索引处图像的指定属性键的值，用callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4577 4578> **说明：** 4579> 4580> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4581 4582**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4583 4584**参数：** 4585 4586| 参数名 | 类型 | 必填 | 说明 | 4587| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4588| key | string | 是 | 图片属性名。 | 4589| callback | AsyncCallback\<string> | 是 | 回调函数，当获取图片属性值成功，err为undefined，data为获取到的图片属性值；否则为错误对象。 | 4590 4591**示例：** 4592 4593```ts 4594import { BusinessError } from '@kit.BasicServicesKit'; 4595 4596imageSourceApi.getImageProperty("BitsPerSample", (error: BusinessError, data: string) => { 4597 if (error) { 4598 console.error('Failed to get the value of the specified attribute key of the image.'); 4599 } else { 4600 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4601 } 4602}) 4603``` 4604 4605### getImageProperty<sup>(deprecated)</sup> 4606 4607getImageProperty(key:string, options: GetImagePropertyOptions, callback: AsyncCallback\<string>): void 4608 4609获取图片指定属性键的值，callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4610 4611> **说明：** 4612> 4613> 从API version 11开始不再维护，建议使用[getImageProperty](#getimageproperty11)代替。 4614 4615**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4616 4617**参数：** 4618 4619| 参数名 | 类型 | 必填 | 说明 | 4620| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------- | 4621| key | string | 是 | 图片属性名。 | 4622| options | [GetImagePropertyOptions](#getimagepropertyoptionsdeprecated) | 是 | 图片属性，包括图片序号与默认属性值。 | 4623| callback | AsyncCallback\<string> | 是 | 回调函数，当获取图片属性值成功，err为undefined，data为获取到的图片属性值；否则为错误对象。| 4624 4625**示例：** 4626 4627```ts 4628import { BusinessError } from '@kit.BasicServicesKit'; 4629 4630let property: image.GetImagePropertyOptions = { index: 0, defaultValue: '9999' } 4631imageSourceApi.getImageProperty("BitsPerSample", property, (error: BusinessError, data: string) => { 4632 if (error) { 4633 console.error('Failed to get the value of the specified attribute key of the image.'); 4634 } else { 4635 console.info('Succeeded in getting the value of the specified attribute key of the image.'); 4636 } 4637}) 4638``` 4639 4640### getImageProperties<sup>12+</sup> 4641 4642getImageProperties(key: Array<PropertyKey>): Promise<Record<PropertyKey, string|null>> 4643 4644批量获取图片中的指定属性键的值，用Promise形式返回结果。仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4645 4646**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4647 4648**参数：** 4649 4650| 参数名 | 类型 | 必填 | 说明 | 4651| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 4652| key | Array\<[PropertyKey](#propertykey7)> | 是 | 图片属性名的数组。 | 4653 4654**返回值：** 4655 4656| 类型 | 说明 | 4657| ---------------- | ----------------------------------------------------------------- | 4658| Promise\<Record<[PropertyKey](#propertykey7), string \| null>> | Promise对象，返回图片属性值，如获取失败则返回null。 | 4659 4660**错误码：** 4661 4662以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4663 4664| 错误码ID | 错误信息 | 4665| ------- | --------------------------------------------| 4666| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4667| 62980096| The operation failed. | 4668| 62980110| The image source data is incorrect. | 4669| 62980113| Unknown image format. | 4670| 62980116| Failed to decode the image. | 4671 4672**示例：** 4673 4674```ts 4675import { image } from '@kit.ImageKit'; 4676import { BusinessError } from '@kit.BasicServicesKit'; 4677 4678let key = [image.PropertyKey.IMAGE_WIDTH, image.PropertyKey.IMAGE_LENGTH]; 4679imageSourceApi.getImageProperties(key).then((data) => { 4680 console.info(JSON.stringify(data)); 4681}).catch((err: BusinessError) => { 4682 console.error(JSON.stringify(err)); 4683}); 4684``` 4685 4686### modifyImageProperty<sup>11+</sup> 4687 4688modifyImageProperty(key: PropertyKey, value: string): Promise\<void> 4689 4690通过指定的键修改图片属性的值，使用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4691 4692> **说明：** 4693> 4694> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4695 4696**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4697 4698**参数：** 4699 4700| 参数名 | 类型 | 必填 | 说明 | 4701| ------- | ------ | ---- | ------------ | 4702| key | [PropertyKey](#propertykey7) | 是 | 图片属性名。 | 4703| value | string | 是 | 属性值。 | 4704 4705**返回值：** 4706 4707| 类型 | 说明 | 4708| -------------- | --------------------------- | 4709| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4710 4711**错误码：** 4712 4713以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4714 4715| 错误码ID | 错误信息 | 4716| ------- | --------------------------------------------| 4717| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 4718| 62980123| The image does not support EXIF decoding. | 4719| 62980133| The EXIF data is out of range. | 4720| 62980135| The EXIF value is invalid. | 4721| 62980146| The EXIF data failed to be written to the file. | 4722 4723**示例：** 4724 4725```ts 4726import { BusinessError } from '@kit.BasicServicesKit'; 4727 4728imageSourceApi.modifyImageProperty(image.PropertyKey.IMAGE_WIDTH, "120").then(() => { 4729 imageSourceApi.getImageProperty(image.PropertyKey.IMAGE_WIDTH).then((width: string) => { 4730 console.info(`ImageWidth is :${width}`); 4731 }).catch((error: BusinessError) => { 4732 console.error('Failed to get the Image Width.'); 4733 }) 4734}).catch((error: BusinessError) => { 4735 console.error('Failed to modify the Image Width'); 4736}) 4737``` 4738 4739### modifyImageProperty<sup>(deprecated)</sup> 4740 4741modifyImageProperty(key: string, value: string): Promise\<void> 4742 4743通过指定的键修改图片属性的值，使用Promise形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4744 4745> **说明：** 4746> 4747> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4748> 4749> 从API version 11开始不再维护，建议使用[modifyImageProperty](#modifyimageproperty11)代替。 4750 4751**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4752 4753**参数：** 4754 4755| 参数名 | 类型 | 必填 | 说明 | 4756| ------- | ------ | ---- | ------------ | 4757| key | string | 是 | 图片属性名。 | 4758| value | string | 是 | 属性值。 | 4759 4760**返回值：** 4761 4762| 类型 | 说明 | 4763| -------------- | --------------------------- | 4764| Promise\<void> | Promise对象。无返回结果的Promise对象。| 4765 4766**示例：** 4767 4768```ts 4769import { BusinessError } from '@kit.BasicServicesKit'; 4770 4771imageSourceApi.modifyImageProperty("ImageWidth", "120").then(() => { 4772 imageSourceApi.getImageProperty("ImageWidth").then((width: string) => { 4773 console.info(`ImageWidth is :${width}`); 4774 }).catch((error: BusinessError) => { 4775 console.error('Failed to get the Image Width.'); 4776 }) 4777}).catch((error: BusinessError) => { 4778 console.error('Failed to modify the Image Width'); 4779}) 4780``` 4781 4782### modifyImageProperty<sup>(deprecated)</sup> 4783 4784modifyImageProperty(key: string, value: string, callback: AsyncCallback\<void>): void 4785 4786通过指定的键修改图片属性的值，callback形式返回结果，仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4787 4788> **说明：** 4789> 4790> 调用modifyImageProperty修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperty会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4791> 4792>从API version 11开始不再维护，建议使用[modifyImageProperty](#modifyimageproperty11)代替。 4793 4794**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4795 4796**参数：** 4797 4798| 参数名 | 类型 | 必填 | 说明 | 4799| -------- | ------------------- | ---- | ------------------------------ | 4800| key | string | 是 | 图片属性名。 | 4801| value | string | 是 | 属性值。 | 4802| callback | AsyncCallback\<void> | 是 | 回调函数，当修改图片属性值成功，err为undefined，否则为错误对象。 | 4803 4804**示例：** 4805 4806```ts 4807import { BusinessError } from '@kit.BasicServicesKit'; 4808 4809imageSourceApi.modifyImageProperty("ImageWidth", "120", (err: BusinessError) => { 4810 if (err) { 4811 console.error(`Failed to modify the Image Width.code is ${err.code}, message is ${err.message}`); 4812 } else { 4813 console.info('Succeeded in modifying the Image Width.'); 4814 } 4815}) 4816``` 4817 4818### modifyImageProperties<sup>12+</sup> 4819 4820modifyImageProperties(records: Record<PropertyKey, string|null>): Promise\<void> 4821 4822批量通过指定的键修改图片属性的值，使用Promise形式返回结果。仅支持JPEG、PNG和HEIF<sup>12+</sup>（不同硬件设备支持情况不同）文件，且需要包含exif信息。其中可以通过supportedFormats属性查询是否支持HEIF格式的exif读写。 4823 4824> **说明：** 4825> 4826> 调用modifyImageProperties修改属性会改变属性字节长度，使用buffer创建的ImageSource调用modifyImageProperties会导致buffer内容覆盖，目前buffer创建的ImageSource不支持调用此接口，请改用fd或path创建的ImageSource。 4827> 4828 4829**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4830 4831**参数：** 4832 4833| 参数名 | 类型 | 必填 | 说明 | 4834| ------- | ------ | ---- | ------------ | 4835| records | Record<[PropertyKey](#propertykey7), string \| null> | 是 | 包含图片属性名和属性值的数组。 | 4836 4837**返回值：** 4838 4839| 类型 | 说明 | 4840| -------------- | --------------------------- | 4841| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4842 4843**错误码：** 4844 4845以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4846 4847| 错误码ID | 错误信息 | 4848| ------- | --------------------------------------------| 4849| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 4850| 62980123| The image does not support EXIF decoding. | 4851| 62980133| The EXIF data is out of range. | 4852| 62980135| The EXIF value is invalid. | 4853| 62980146| The EXIF data failed to be written to the file. | 4854 4855**示例：** 4856 4857```ts 4858import { image } from '@kit.ImageKit'; 4859import { BusinessError } from '@kit.BasicServicesKit'; 4860 4861let keyValues: Record<PropertyKey, string|null> = { 4862 [image.PropertyKey.IMAGE_WIDTH] : "1024", 4863 [image.PropertyKey.IMAGE_LENGTH] : "1024" 4864}; 4865let checkKey = [image.PropertyKey.IMAGE_WIDTH, image.PropertyKey.IMAGE_LENGTH]; 4866imageSourceApi.modifyImageProperties(keyValues).then(() => { 4867 imageSourceApi.getImageProperties(checkKey).then((data) => { 4868 console.info(JSON.stringify(data)); 4869 }).catch((err: BusinessError) => { 4870 console.error(JSON.stringify(err)); 4871 }); 4872}).catch((err: BusinessError) => { 4873 console.error(JSON.stringify(err)); 4874}); 4875``` 4876 4877### updateData<sup>9+</sup> 4878 4879updateData(buf: ArrayBuffer, isFinished: boolean, offset: number, length: number): Promise\<void> 4880 4881更新增量数据，使用Promise形式返回结果。 4882 4883**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4884 4885**参数：** 4886 4887| 参数名 | 类型 | 必填 | 说明 | 4888| ---------- | ----------- | ---- | ------------ | 4889| buf | ArrayBuffer | 是 | 存放增量数据的buffer。 | 4890| isFinished | boolean | 是 | true表示数据更新完成，当前buffer内存放最后一段数据；false表示数据还未更新完成，需要继续更新。| 4891| offset | number | 是 | 即当前buffer中的数据首地址，相对于整个图片文件首地址的偏移量。单位：字节。 | 4892| length | number | 是 | 当前buffer的长度。单位：字节。 | 4893 4894**返回值：** 4895 4896| 类型 | 说明 | 4897| -------------- | -------------------------- | 4898| Promise\<void> | Promise对象。无返回结果的Promise对象。| 4899 4900**示例：** 4901 4902```ts 4903import { BusinessError } from '@kit.BasicServicesKit'; 4904 4905const array: ArrayBuffer = new ArrayBuffer(100); 4906imageSourceApi.updateData(array, false, 0, 10).then(() => { 4907 console.info('Succeeded in updating data.'); 4908}).catch((err: BusinessError) => { 4909 console.error(`Failed to update data.code is ${err.code},message is ${err.message}`); 4910}) 4911``` 4912 4913 4914### updateData<sup>9+</sup> 4915 4916updateData(buf: ArrayBuffer, isFinished: boolean, offset: number, length: number, callback: AsyncCallback\<void>): void 4917 4918更新增量数据，callback形式返回结果。 4919 4920**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4921 4922**参数：** 4923 4924| 参数名 | 类型 | 必填 | 说明 | 4925| ---------- | ------------------- | ---- | -------------------- | 4926| buf | ArrayBuffer | 是 | 存放增量数据的buffer。 | 4927| isFinished | boolean | 是 | true表示数据更新完成，当前buffer内存放最后一段数据；false表示数据还未更新完成，需要继续更新。| 4928| offset | number | 是 | 即当前buffer中的数据首地址，相对于整个图片文件首地址的偏移量。单位：字节。 | 4929| length | number | 是 | 当前buffer的长度。单位：字节。 | 4930| callback | AsyncCallback\<void> | 是 | 回调函数，当更新增量数据成功，err为undefined，否则为错误对象。 | 4931 4932**示例：** 4933 4934```ts 4935import { BusinessError } from '@kit.BasicServicesKit'; 4936 4937const array: ArrayBuffer = new ArrayBuffer(100); 4938imageSourceApi.updateData(array, false, 0, 10, (err: BusinessError) => { 4939 if (err) { 4940 console.error(`Failed to update data.code is ${err.code},message is ${err.message}`); 4941 } else { 4942 console.info('Succeeded in updating data.'); 4943 } 4944}) 4945``` 4946 4947### createPicture<sup>13+</sup> 4948 4949createPicture(options?: DecodingOptionsForPicture): Promise\<Picture> 4950 4951通过图片解码参数创建Picture对象,使用Promise形式返回。 4952 4953**系统能力：** SystemCapability.Multimedia.Image.ImageSource 4954 4955**参数：** 4956 4957| 参数名 | 类型 | 必填 | 说明 | 4958| ------- | ------------------------------------------------------ | ---- | ---------- | 4959| options | [DecodingOptionsForPicture](#decodingoptionsforpicture13) | 否 | 解码参数。 | 4960 4961**返回值：** 4962 4963| 类型 | 说明 | 4964| ---------------------------- | -------------------------- | 4965| Promise\<[Picture](#picture13)> | Promise对象，返回Picture。 | 4966 4967**错误码：** 4968 4969以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 4970 4971| 错误码ID | 错误信息 | 4972| -------- | ------------------------------------------------------------ | 4973| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified.2.Incorrect parameter types; 3.Parameter verification failed. | 4974| 7700301 | Decode failed. | 4975 4976**示例：** 4977 4978```ts 4979import { image } from '@kit.ImageKit'; 4980 4981async function CreatePicture() { 4982 let options: image.DecodingOptionsForPicture = { 4983 desiredAuxiliaryPictures: [image.AuxiliaryPictureType.GAINMAP] //GAINMAP为需要解码的辅助图类型。 4984 }; 4985 let pictureObj: image.Picture = await imageSourceApi.createPicture(options); 4986 if (pictureObj != null) { 4987 console.info('Create picture succeeded'); 4988 } else { 4989 console.info('Create picture failed'); 4990 } 4991} 4992``` 4993 4994### createPixelMap<sup>7+</sup> 4995 4996createPixelMap(options?: DecodingOptions): Promise\<PixelMap> 4997 4998通过图片解码参数创建PixelMap对象。 4999 5000**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 5001 5002**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5003 5004**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5005 5006**参数：** 5007 5008| 参数名 | 类型 | 必填 | 说明 | 5009| ------- | ------------------------------------ | ---- | ---------- | 5010| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5011 5012**返回值：** 5013 5014| 类型 | 说明 | 5015| -------------------------------- | --------------------- | 5016| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 5017 5018**示例：** 5019 5020```ts 5021import { BusinessError } from '@kit.BasicServicesKit'; 5022 5023imageSourceApi.createPixelMap().then((pixelMap: image.PixelMap) => { 5024 console.info('Succeeded in creating pixelMap object through image decoding parameters.'); 5025}).catch((error: BusinessError) => { 5026 console.error('Failed to create pixelMap object through image decoding parameters.'); 5027}) 5028``` 5029 5030### createPixelMap<sup>7+</sup> 5031 5032createPixelMap(callback: AsyncCallback\<PixelMap>): void 5033 5034通过默认参数创建PixelMap对象，使用callback形式返回结果。 5035 5036**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 5037 5038**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5039 5040**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5041 5042**参数：** 5043 5044| 参数名 | 类型 | 必填 | 说明 | 5045| -------- | ------------------------------------- | ---- | -------------------------- | 5046| callback | AsyncCallback<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap对象成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 5047 5048**示例：** 5049 5050```ts 5051import { BusinessError } from '@kit.BasicServicesKit'; 5052 5053imageSourceApi.createPixelMap((err: BusinessError, pixelMap: image.PixelMap) => { 5054 if (err) { 5055 console.error(`Failed to create pixelMap.code is ${err.code},message is ${err.message}`); 5056 } else { 5057 console.info('Succeeded in creating pixelMap object.'); 5058 } 5059}) 5060``` 5061 5062### createPixelMap<sup>7+</sup> 5063 5064createPixelMap(options: DecodingOptions, callback: AsyncCallback\<PixelMap>): void 5065 5066通过图片解码参数创建PixelMap对象。 5067 5068**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 5069 5070**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5071 5072**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5073 5074**参数：** 5075 5076| 参数名 | 类型 | 必填 | 说明 | 5077| -------- | ------------------------------------- | ---- | -------------------------- | 5078| options | [DecodingOptions](#decodingoptions7) | 是 | 解码参数。 | 5079| callback | AsyncCallback<[PixelMap](#pixelmap7)> | 是 | 回调函数，当创建PixelMap对象成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 5080 5081**示例：** 5082 5083```ts 5084import { BusinessError } from '@kit.BasicServicesKit'; 5085 5086let decodingOptions: image.DecodingOptions = { 5087 sampleSize: 1, 5088 editable: true, 5089 desiredSize: { width: 1, height: 2 }, 5090 rotate: 10, 5091 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5092 desiredRegion: { size: { width: 1, height: 2 }, x: 0, y: 0 }, 5093 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5094 index: 0 5095}; 5096imageSourceApi.createPixelMap(decodingOptions, (err: BusinessError, pixelMap: image.PixelMap) => { 5097 if (err) { 5098 console.error(`Failed to create pixelMap.code is ${err.code},message is ${err.message}`); 5099 } else { 5100 console.info('Succeeded in creating pixelMap object.'); 5101 } 5102}) 5103``` 5104 5105### createPixelMapSync<sup>12+</sup> 5106 5107createPixelMapSync(options?: DecodingOptions): PixelMap 5108 5109通过图片解码参数同步创建PixelMap对象。 5110 5111**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5112 5113**参数：** 5114 5115| 参数名 | 类型 | 必填 | 说明 | 5116| -------- | ------------------------------------- | ---- | -------------------------- | 5117| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5118 5119**返回值：** 5120 5121| 类型 | 说明 | 5122| -------------------------------- | --------------------- | 5123| [PixelMap](#pixelmap7) | 用于同步返回创建结果。 | 5124 5125**示例：** 5126 5127```ts 5128import { image } from '@kit.ImageKit'; 5129 5130// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 5131let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5132//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5133let filePath: string = context.filesDir + "/test.jpg"; 5134let imageSource = image.createImageSource(filePath); 5135let decodingOptions: image.DecodingOptions = { 5136 sampleSize: 1, 5137 editable: true, 5138 desiredSize: { width: 1, height: 2 }, 5139 rotate: 10, 5140 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5141 desiredRegion: { size: { width: 1, height: 2 }, x: 0, y: 0 }, 5142 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5143 index: 0 5144}; 5145let pixelmap = imageSource.createPixelMapSync(decodingOptions); 5146if (pixelmap != undefined) { 5147 console.info('Succeeded in creating pixelMap object.'); 5148} else { 5149 console.info('Failed to create pixelMap.'); 5150} 5151``` 5152 5153### createPixelMapList<sup>10+</sup> 5154 5155createPixelMapList(options?: DecodingOptions): Promise<Array\<PixelMap>> 5156 5157通过图片解码参数创建PixelMap数组。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5158 5159> **注意：** 5160> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5161 5162**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5163 5164**参数：** 5165 5166| 参数名 | 类型 | 必填 | 说明 | 5167| -------- | ------------------------------------- | ---- | -------------------------- | 5168| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5169 5170**返回值：** 5171 5172| 类型 | 说明 | 5173| -------------------------------- | --------------------- | 5174| Promise<Array<[PixelMap](#pixelmap7)>> | 异步返回PixeMap数组。 | 5175 5176**错误码：** 5177 5178以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5179 5180| 错误码ID | 错误信息 | 5181| ------- | --------------------------------------------| 5182| 62980096| The operation failed. | 5183| 62980099 | The shared memory data is abnormal. | 5184| 62980101 | The image data is abnormal. | 5185| 62980103| The image data is not supported. | 5186| 62980106 | The image is too large. | 5187| 62980109 | Failed to crop the image. | 5188| 62980110| The image source data is incorrect. | 5189| 62980111| The image source data is incomplete. | 5190| 62980112 | The image format does not match. | 5191| 62980113 | Unknown image format. | 5192| 62980115 | Invalid image parameter. | 5193| 62980116 | Failed to decode the image. | 5194| 62980118| Failed to create the image plugin. | 5195| 62980122 | Failed to decode the image header. | 5196| 62980137 | Invalid media operation. | 5197| 62980173 | The DMA memory does not exist. | 5198| 62980174 | The DMA memory data is abnormal. | 5199 5200**示例：** 5201 5202```ts 5203import { BusinessError } from '@kit.BasicServicesKit'; 5204 5205let decodeOpts: image.DecodingOptions = { 5206 sampleSize: 1, 5207 editable: true, 5208 desiredSize: { width: 198, height: 202 }, 5209 rotate: 0, 5210 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5211 index: 0, 5212}; 5213imageSourceApi.createPixelMapList(decodeOpts).then((pixelMapList: Array<image.PixelMap>) => { 5214 console.info('Succeeded in creating pixelMapList object.'); 5215}).catch((err: BusinessError) => { 5216 console.error(`Failed to create pixelMapList object, error code is ${error}`); 5217}) 5218``` 5219 5220### createPixelMapList<sup>10+</sup> 5221 5222createPixelMapList(callback: AsyncCallback<Array\<PixelMap>>): void 5223 5224通过默认参数创建PixelMap数组，使用callback形式返回结果。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5225 5226> **注意：** 5227> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5228 5229**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5230 5231**参数：** 5232 5233| 参数名 | 类型 | 必填 | 说明 | 5234| -------- | ------------------------------------- | ---- | -------------------------- | 5235| callback | AsyncCallback<Array<[PixelMap](#pixelmap7)>> | 是 | 回调函数，当创建PixelMap对象数组成功，err为undefined，data为获取到的PixelMap对象数组；否则为错误对象。 | 5236 5237**错误码：** 5238 5239以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5240 5241| 错误码ID | 错误信息 | 5242| ------- | --------------------------------------------| 5243| 62980096 | The operation failed. | 5244| 62980099 | The shared memory data is abnormal. | 5245| 62980101 | The image data is abnormal. | 5246| 62980103 | The image data is not supported. | 5247| 62980106 | The image is too large. | 5248| 62980109 | Failed to crop the image. | 5249| 62980110 | The image source data is incorrect. | 5250| 62980111 | The image source data is incomplete. | 5251| 62980112 | The image format does not match. | 5252| 62980113 | Unknown image format. | 5253| 62980115 | Invalid image parameter. | 5254| 62980116 | Failed to decode the image. | 5255| 62980118 | Failed to create the image plugin. | 5256| 62980122 | Failed to decode the image header. | 5257| 62980137 | Invalid media operation. | 5258| 62980173 | The DMA memory does not exist. | 5259| 62980174 | The DMA memory data is abnormal. | 5260 5261**示例：** 5262 5263```ts 5264import { BusinessError } from '@kit.BasicServicesKit'; 5265 5266imageSourceApi.createPixelMapList((err: BusinessError, pixelMapList: Array<image.PixelMap>) => { 5267 if (err) { 5268 console.error(`Failed to create pixelMapList object, error code is ${error}`); 5269 } else { 5270 console.info('Succeeded in creating pixelMapList object.'); 5271 } 5272}) 5273``` 5274 5275### createPixelMapList<sup>10+</sup> 5276 5277createPixelMapList(options: DecodingOptions, callback: AsyncCallback<Array\<PixelMap>>): void 5278 5279通过图片解码参数创建PixelMap数组，使用callback形式返回结果。针对动图如Gif、Webp，此接口返回每帧图片数据；针对静态图，此接口返回唯一的一帧图片数据。 5280 5281> **注意：** 5282> 此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。 5283 5284**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5285 5286**参数：** 5287 5288| 参数名 | 类型 | 必填 | 说明 | 5289| -------- | -------------------- | ---- | ---------------------------------- | 5290| options | [DecodingOptions](#decodingoptions7) | 是 | 解码参数。 | 5291| callback | AsyncCallback<Array<[PixelMap](#pixelmap7)>> | 是 | 回调函数，当创建PixelMap对象数组成功，err为undefined，data为获取到的PixelMap对象数组；否则为错误对象。 | 5292 5293**错误码：** 5294 5295以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5296 5297| 错误码ID | 错误信息 | 5298| ------- | --------------------------------------------| 5299| 62980096 | The operation failed. | 5300| 62980099 | The shared memory data is abnormal. | 5301| 62980101 | The image data is abnormal. | 5302| 62980103 | The image data is not supported. | 5303| 62980106 | The image is too large. | 5304| 62980109 | Failed to crop the image. | 5305| 62980110 | The image source data is incorrect. | 5306| 62980111 | The image source data is incomplete. | 5307| 62980112 | The image format does not match. | 5308| 62980113 | Unknown image format. | 5309| 62980115 | Invalid image parameter. | 5310| 62980116 | Failed to decode the image. | 5311| 62980118 | Failed to create the image plugin. | 5312| 62980122 | Failed to decode the image header. | 5313| 62980137 | Invalid media operation. | 5314| 62980173 | The DMA memory does not exist. | 5315| 62980174 | The DMA memory data is abnormal. | 5316 5317**示例：** 5318 5319```ts 5320import { BusinessError } from '@kit.BasicServicesKit'; 5321 5322let decodeOpts: image.DecodingOptions = { 5323 sampleSize: 1, 5324 editable: true, 5325 desiredSize: { width: 198, height: 202 }, 5326 rotate: 0, 5327 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5328 index: 0, 5329}; 5330imageSourceApi.createPixelMapList(decodeOpts, (err: BusinessError, pixelMapList: Array<image.PixelMap>) => { 5331 if (err) { 5332 console.error(`Failed to create pixelMapList object, error code is ${error}`); 5333 } else { 5334 console.info('Succeeded in creating pixelMapList object.'); 5335 } 5336}) 5337``` 5338 5339### createPixelMapUsingAllocator<sup>15+</sup> 5340 5341createPixelMapUsingAllocator(options?: DecodingOptions, allocatorType?: AllocatorType): Promise\<PixelMap\> 5342 5343使用指定的分配器根据图像解码参数异步创建PixelMap对象。使用Promise返回对象。 5344 5345**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5346 5347**参数：** 5348 5349| 参数名 | 类型 | 必填 | 说明 | 5350| ------------- | ------------------------------------ | ---- | ------------------------ | 5351| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5352| allocatorType | [AllocatorType](#allocatortype15) | 否 | 用于图像解码的内存类型。默认值为AllocatorType.AUTO。 | 5353 5354**返回值：** 5355 5356| 类型 | 说明 | 5357| -------------------------------- | --------------------------- | 5358| Promise\<[PixelMap](#pixelmap7)> | Promise对象，返回PixelMap。 | 5359 5360**错误码：** 5361 5362以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5363 5364| 错误码ID | 错误信息 | 5365| -------- | ------------------------------------------------------------ | 5366| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types;3.Parameter verification failed. | 5367| 7700101 | Bad source. | 5368| 7700102 | Unsupported mimetype. | 5369| 7700103 | Image too large. | 5370| 7700201 | Unsupported allocator type, e.g., use share memory to decode a HDR image as only DMA supported hdr metadata. | 5371| 7700203 | Unsupported options, e.g., cannot convert image into desired pixel format. | 5372| 7700301 | Decode failed. | 5373| 7700302 | Memory allocation failed. | 5374 5375**示例：** 5376 5377```ts 5378import image from '@ohos.multimedia.image'; 5379 5380// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 5381let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5382// 此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5383let filePath: string = context.filesDir + "/test.jpg"; 5384let imageSource = image.createImageSource(filePath); 5385let decodingOptions: image.DecodingOptions = { 5386 editable: true, 5387 desiredSize: { width: 3072, height: 4096 }, 5388 rotate: 10, 5389 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5390 desiredRegion: { size: { width: 3072, height: 4096 }, x: 0, y: 0 }, 5391 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5392 index: 0 5393}; 5394let pixelmap = imageSource.createPixelMapUsingAllocator(decodingOptions, image.AllocatorType.AUTO); 5395if (pixelmap != undefined) { 5396 console.info('Succeeded in creating pixelMap object.'); 5397} else { 5398 console.info('Failed to create pixelMap.'); 5399} 5400``` 5401 5402### createPixelMapUsingAllocatorSync<sup>15+</sup> 5403 5404createPixelMapUsingAllocatorSync(options?: DecodingOptions, allocatorType?: AllocatorType): PixelMap 5405 5406根据指定的分配器同步创建一个基于图像解码参数的PixelMap对象。 5407 5408**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5409 5410**参数：** 5411 5412| 参数名 | 类型 | 必填 | 说明 | 5413| ------------- | ------------------------------------ | ---- | ------------------------ | 5414| options | [DecodingOptions](#decodingoptions7) | 否 | 解码参数。 | 5415| allocatorType | [AllocatorType](#allocatortype15) | 否 | 用于图像解码的内存类型。默认值为AllocatorType.AUTO。 | 5416 5417**返回值：** 5418 5419| 类型 | 说明 | 5420| ---------------------- | ---------------------- | 5421| [PixelMap](#pixelmap7) | 用于同步返回创建结果。 | 5422 5423**错误码：** 5424 5425以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5426 5427| 错误码ID | 错误信息 | 5428| -------- | ------------------------------------------------------------ | 5429| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types;3.Parameter verification failed. | 5430| 7700101 | Bad source. | 5431| 7700102 | Unsupported mimetype. | 5432| 7700103 | Image too large. | 5433| 7700201 | Unsupported allocator type, e.g., use share memory to decode a HDR image as only DMA supported hdr metadata. | 5434| 7700203 | Unsupported options, e.g., cannot convert image into desired pixel format. | 5435| 7700301 | Decode failed. | 5436| 7700302 | Memory allocation failed. | 5437 5438**示例：** 5439 5440```ts 5441import image from '@ohos.multimedia.image'; 5442 5443// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 5444let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5445// 此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 5446let filePath: string = context.filesDir + "/test.jpg"; 5447let imageSource = image.createImageSource(filePath); 5448let decodingOptions: image.DecodingOptions = { 5449 editable: true, 5450 desiredSize: { width: 3072, height: 4096 }, 5451 rotate: 10, 5452 desiredPixelFormat: image.PixelMapFormat.RGBA_8888, 5453 desiredRegion: { size: { width: 3072, height: 4096 }, x: 0, y: 0 }, 5454 cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST, 5455 index: 0 5456}; 5457let pixelmap = imageSource.createPixelMapUsingAllocatorSync(decodingOptions, image.AllocatorType.AUTO); 5458if (pixelmap != undefined) { 5459 console.info('Succeeded in creating pixelMap object.'); 5460} else { 5461 console.info('Failed to create pixelMap.'); 5462} 5463``` 5464 5465### getDelayTimeList<sup>10+</sup> 5466 5467getDelayTimeList(callback: AsyncCallback<Array\<number>>): void 5468 5469获取图像延迟时间数组，使用callback形式返回结果。此接口仅用于gif图片和webp图片。 5470 5471**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5472 5473**参数：** 5474 5475| 参数名 | 类型 | 必填 | 说明 | 5476| -------- | -------------------- | ---- | ---------------------------------- | 5477| callback | AsyncCallback<Array\<number>> | 是 | 回调函数，当获取图像延迟时间数组成功，err为undefined，data为获取到的图像延时时间数组；否则为错误对象。 | 5478 5479**错误码：** 5480 5481以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5482 5483| 错误码ID | 错误信息 | 5484| ------- | --------------------------------------------| 5485| 62980096| The operation failed. | 5486| 62980110| The image source data is incorrect. | 5487| 62980111| The image source data is incomplete. | 5488| 62980112 | The image format does not match. | 5489| 62980113| Unknown image format. | 5490| 62980115 | Invalid image parameter. | 5491| 62980116| Failed to decode the image. | 5492| 62980118| Failed to create the image plugin. | 5493| 62980122| Failed to decode the image header. | 5494| 62980137 | Invalid media operation. | 5495| 62980149 | Invalid MIME type for the image source. | 5496 5497**示例：** 5498 5499```ts 5500import { BusinessError } from '@kit.BasicServicesKit'; 5501 5502imageSourceApi.getDelayTimeList((err: BusinessError, delayTimes: Array<number>) => { 5503 if (err) { 5504 console.error(`Failed to get delayTimes object.code is ${err.code},message is ${err.message}`); 5505 } else { 5506 console.info('Succeeded in getting delayTimes object.'); 5507 } 5508}) 5509``` 5510 5511### getDelayTimeList<sup>10+</sup> 5512 5513getDelayTimeList(): Promise<Array\<number>> 5514 5515获取图像延迟时间数组，使用Promise形式返回结果。此接口仅用于gif图片和webp图片。 5516 5517**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5518 5519**返回值：** 5520 5521| 类型 | 说明 | 5522| -------------- | --------------------------- | 5523| Promise<Array\<number>> | Promise对象，返回延迟时间数组。 | 5524 5525**错误码：** 5526 5527以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5528 5529| 错误码ID | 错误信息 | 5530| ------- | --------------------------------------------| 5531| 62980096 | The operation failed. | 5532| 62980110 | The image source data is incorrect. | 5533| 62980111 | The image source data is incomplete. | 5534| 62980112 | The image format does not match. | 5535| 62980113 | Unknown image format. | 5536| 62980115 | Invalid image parameter. | 5537| 62980116 | Failed to decode the image. | 5538| 62980118 | Failed to create the image plugin. | 5539| 62980122 | Failed to decode the image header. | 5540| 62980137 | Invalid media operation. | 5541| 62980149 | Invalid MIME type for the image source. | 5542 5543**示例：** 5544 5545```ts 5546import { BusinessError } from '@kit.BasicServicesKit'; 5547 5548imageSourceApi.getDelayTimeList().then((delayTimes: Array<number>) => { 5549 console.info('Succeeded in getting delayTimes object.'); 5550}).catch((err: BusinessError) => { 5551 console.error(`Failed to get delayTimes object.code is ${err.code},message is ${err.message}`); 5552}) 5553``` 5554 5555### getFrameCount<sup>10+</sup> 5556 5557getFrameCount(callback: AsyncCallback\<number>): void 5558 5559获取图像帧数，使用callback形式返回结果。 5560 5561**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5562 5563**参数：** 5564 5565| 参数名 | 类型 | 必填 | 说明 | 5566| -------- | -------------------- | ---- | ---------------------------------- | 5567| callback | AsyncCallback\<number> | 是 | 回调函数，当获取图像帧数成功，err为undefined，data为获取到的图像帧数；否则为错误对象。 | 5568 5569**错误码：** 5570 5571以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5572 5573| 错误码ID | 错误信息 | 5574| ------- | --------------------------------------------| 5575| 62980096| The operation failed. | 5576| 62980110| The image source data is incorrect. | 5577| 62980111| The image source data is incomplete. | 5578| 62980112| The image format does not match. | 5579| 62980113| Unknown image format. | 5580| 62980115| Invalid image parameter. | 5581| 62980116| Failed to decode the image. | 5582| 62980118| Failed to create the image plugin. | 5583| 62980122| Failed to decode the image header. | 5584| 62980137| Invalid media operation. | 5585 5586**示例：** 5587 5588```ts 5589import { BusinessError } from '@kit.BasicServicesKit'; 5590 5591imageSourceApi.getFrameCount((err: BusinessError, frameCount: number) => { 5592 if (err) { 5593 console.error(`Failed to get frame count.code is ${err.code},message is ${err.message}`); 5594 } else { 5595 console.info('Succeeded in getting frame count.'); 5596 } 5597}) 5598``` 5599 5600### getFrameCount<sup>10+</sup> 5601 5602getFrameCount(): Promise\<number> 5603 5604获取图像帧数，使用Promise形式返回结果。 5605 5606**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5607 5608**返回值：** 5609 5610| 类型 | 说明 | 5611| -------------- | --------------------------- | 5612| Promise\<number> | Promise对象，返回图像帧数。 | 5613 5614**错误码：** 5615 5616以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5617 5618| 错误码ID | 错误信息 | 5619| ------- | --------------------------------------------| 5620| 62980096 | The operation failed. | 5621| 62980110 | The image source data is incorrect. | 5622| 62980111 | The image source data is incomplete. | 5623| 62980112 | The image format does not match. | 5624| 62980113 | Unknown image format. | 5625| 62980115 | Invalid image parameter. | 5626| 62980116 | Failed to decode the image. | 5627| 62980118 | Failed to create the image plugin. | 5628| 62980122 | Failed to decode the image header. | 5629| 62980137 | Invalid media operation. | 5630 5631**示例：** 5632 5633```ts 5634import { BusinessError } from '@kit.BasicServicesKit'; 5635 5636imageSourceApi.getFrameCount().then((frameCount: number) => { 5637 console.info('Succeeded in getting frame count.'); 5638}).catch((err: BusinessError) => { 5639 console.error(`Failed to get frame count.code is ${err.code},message is ${err.message}`); 5640}) 5641``` 5642 5643### getDisposalTypeList<sup>12+</sup> 5644 5645getDisposalTypeList(): Promise\<Array\<number>> 5646 5647获取图像帧过渡模式数组，使用Promise形式返回结果。此接口仅用于gif图片。 5648 5649**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5650 5651**返回值：** 5652 5653| 类型 | 说明 | 5654| -------------- | --------------------------- | 5655| Promise\<Array\<number>> | Promise对象，返回帧过渡模式数组。 | 5656 5657**错误码：** 5658 5659以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5660 5661| 错误码ID | 错误信息 | 5662| ------- | --------------------------------------------| 5663| 62980096 | The operation failed. | 5664| 62980101 | The image data is abnormal. | 5665| 62980137 | Invalid media operation. | 5666| 62980149 | Invalid MIME type for the image source. | 5667 5668**示例：** 5669 5670```ts 5671import { BusinessError } from '@kit.BasicServicesKit'; 5672imageSourceApi.getDisposalTypeList().then((disposalTypes: Array<number>) => { 5673 console.info('Succeeded in getting disposalTypes object.'); 5674}).catch((err: BusinessError) => { 5675 console.error(`Failed to get disposalTypes object.code ${err.code},message is ${err.message}`); 5676}) 5677``` 5678 5679### release 5680 5681release(callback: AsyncCallback\<void>): void 5682 5683释放ImageSource实例，使用callback形式返回结果。 5684 5685ArkTS有内存回收机制，ImageSource对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5686 5687**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5688 5689**参数：** 5690 5691| 参数名 | 类型 | 必填 | 说明 | 5692| -------- | -------------------- | ---- | ---------------------------------- | 5693| callback | AsyncCallback\<void> | 是 | 回调函数，当资源释放成功，err为undefined，否则为错误对象。 | 5694 5695**示例：** 5696 5697```ts 5698import { BusinessError } from '@kit.BasicServicesKit'; 5699 5700imageSourceApi.release((err: BusinessError) => { 5701 if (err) { 5702 console.error(`Failed to release the image source instance.code ${err.code},message is ${err.message}`); 5703 } else { 5704 console.info('Succeeded in releasing the image source instance.'); 5705 } 5706}) 5707``` 5708 5709### release 5710 5711release(): Promise\<void> 5712 5713释放ImageSource实例，使用Promise形式返回结果。 5714 5715ArkTS有内存回收机制，ImageSource对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 5716 5717**系统能力：** SystemCapability.Multimedia.Image.ImageSource 5718 5719**返回值：** 5720 5721| 类型 | 说明 | 5722| -------------- | --------------------------- | 5723| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 5724 5725**示例：** 5726 5727```ts 5728import { BusinessError } from '@kit.BasicServicesKit'; 5729 5730imageSourceApi.release().then(() => { 5731 console.info('Succeeded in releasing the image source instance.'); 5732}).catch((error: BusinessError) => { 5733 console.error(`Failed to release the image source instance.code ${error.code},message is ${error.message}`); 5734}) 5735``` 5736 5737## image.createImagePacker 5738 5739createImagePacker(): ImagePacker 5740 5741创建ImagePacker实例。 5742 5743**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5744 5745**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5746 5747**返回值：** 5748 5749| 类型 | 说明 | 5750| --------------------------- | --------------------- | 5751| [ImagePacker](#imagepacker) | 返回ImagePacker实例。 | 5752 5753**示例：** 5754 5755```ts 5756const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5757``` 5758 5759## ImagePacker 5760 5761图片编码器类，用于图片压缩和编码。在调用ImagePacker的方法前，需要先通过[createImagePacker](#imagecreateimagepacker)构建一个ImagePacker实例，当前支持格式有：jpeg、webp、png、heif<sup>12+</sup>（不同硬件设备支持情况不同）。 5762 5763### 属性 5764 5765**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5766 5767| 名称 | 类型 | 可读 | 可写 | 说明 | 5768| ---------------- | -------------- | ---- | ---- | -------------------------- | 5769| supportedFormats | Array\<string> | 是 | 否 | 图片编码支持的格式 jpeg、webp、png、heic<sup>12+</sup>（不同硬件设备支持情况不同）。 | 5770 5771### packToData<sup>13+</sup> 5772 5773packToData(source: ImageSource, options: PackingOption): Promise\<ArrayBuffer> 5774 5775图片压缩或重新编码，使用Promise形式返回结果。 5776 5777**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 5778 5779**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5780 5781**参数：** 5782 5783| 参数名 | 类型 | 必填 | 说明 | 5784| ------ | ------------------------------- | ---- | -------------- | 5785| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 5786| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 5787 5788**错误码：** 5789 5790以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5791 5792| 错误码ID | 错误信息 | 5793| ------- | --------------------------------------------| 5794| 401 | If the parameter is invalid. | 5795| 62980096| The Operation failed. | 5796| 62980101 | The image data is abnormal. | 5797| 62980106 | The image is too large. | 5798| 62980113 | Unknown image format. | 5799| 62980119 | If encoder occur error during encoding. | 5800| 62980120 | Add pixelmap out of range. | 5801| 62980172 | Failed to encode icc. | 5802| 62980252 | Failed to create surface. | 5803 5804**返回值：** 5805 5806| 类型 | 说明 | 5807| ---------------------------- | --------------------------------------------- | 5808| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。 | 5809 5810**示例：** 5811 5812```ts 5813import { BusinessError } from '@kit.BasicServicesKit'; 5814 5815// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 5816let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5817//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 5818let filePath: string = context.filesDir + "/test.jpg"; 5819const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 5820let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5821const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5822imagePackerApi.packToData(imageSourceApi, packOpts) 5823 .then((data: ArrayBuffer) => { 5824 console.info('Succeeded in packing the image.'); 5825 }).catch((error: BusinessError) => { 5826 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 5827 }) 5828``` 5829 5830### packToData<sup>13+</sup> 5831 5832packToData(source: PixelMap, options: PackingOption): Promise\<ArrayBuffer> 5833 5834图片压缩或重新编码，使用Promise形式返回结果。 5835 5836> **注意：** 5837> 接口如果返回401错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 5838 5839**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 5840 5841**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5842 5843**参数：** 5844 5845| 参数名 | 类型 | 必填 | 说明 | 5846| ------ | ------------------------------- | ---- | ------------------ | 5847| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap源。 | 5848| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 5849 5850**返回值：** 5851 5852| 类型 | 说明 | 5853| --------------------- | -------------------------------------------- | 5854| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。| 5855 5856**错误码：** 5857 5858以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5859 5860| 错误码ID | 错误信息 | 5861| ------- | --------------------------------------------| 5862| 401 | If the parameter is invalid. | 5863| 62980096| The Operation failed. | 5864| 62980101 | The image data is abnormal. | 5865| 62980106 | The image is too large. | 5866| 62980113 | Unknown image format. | 5867| 62980119 | If encoder occur error during encoding. | 5868| 62980120 | Add pixelmap out of range. | 5869| 62980172 | Failed to encode icc. | 5870| 62980252 | Failed to create surface. | 5871 5872**示例：** 5873 5874```ts 5875import { BusinessError } from '@kit.BasicServicesKit'; 5876 5877const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 5878let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 5879image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 5880 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 5881 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5882 imagePackerApi.packToData(pixelMap, packOpts) 5883 .then((data: ArrayBuffer) => { 5884 console.info('Succeeded in packing the image.'); 5885 }).catch((error: BusinessError) => { 5886 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 5887 }) 5888}).catch((error: BusinessError) => { 5889 console.error(`Failed to create PixelMap.code ${error.code},message is ${error.message}`); 5890}) 5891``` 5892 5893### packing<sup>13+</sup> 5894 5895packing(picture: Picture, options: PackingOption): Promise\<ArrayBuffer> 5896 5897将图像压缩或重新编码，使用Promise形式返回结果。 5898 5899**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5900 5901**参数：** 5902 5903| 参数名 | 类型 | 必填 | 说明 | 5904| ---------------- | ---------------------------------------------------- | ---- | -------------------- | 5905| picture | [Picture](#picture13) | 是 | 编码的Picture对象。 | 5906| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 5907 5908**返回值：** 5909 5910| 类型 | 说明 | 5911| --------------------- | ------------------------------------- | 5912| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。 | 5913 5914**错误码：** 5915 5916以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 5917 5918| 错误码ID | 错误信息 | 5919| -------- | ------------------------------------------------------------ | 5920| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 5921| 7800301 | Encode failed. | 5922 5923**示例：** 5924 5925```ts 5926import { BusinessError } from '@kit.BasicServicesKit'; 5927import { image } from '@kit.ImageKit'; 5928 5929async function Packing(context: Context) { 5930 const resourceMgr = context.resourceManager; 5931 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 5932 let ops: image.SourceOptions = { 5933 sourceDensity: 98, 5934 } 5935 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 5936 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 5937 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 5938 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 5939 let funcName = "Packing"; 5940 if (imagePackerApi != null) { 5941 let opts: image.PackingOption = { 5942 format: "image/jpeg", 5943 quality: 98, 5944 bufferSize: 10, 5945 desiredDynamicRange: image.PackingDynamicRange.AUTO, 5946 needsPackProperties: true}; 5947 await imagePackerApi.packing(pictureObj, opts).then((data: ArrayBuffer) => { 5948 console.info(funcName, 'Succeeded in packing the image.'+ data); 5949 }).catch((error: BusinessError) => { 5950 console.error(funcName, 'Failed to pack the image.code ${error.code},message is ${error.message}'); 5951 }); 5952 } 5953} 5954``` 5955 5956### packToDataFromPixelmapSequence<sup>18+</sup> 5957 5958packToDataFromPixelmapSequence(pixelmapSequence: Array\<PixelMap>, options: PackingOptionsForSequence): Promise\<ArrayBuffer> 5959 5960将多个PixelMap编码成GIF数据。使用Promise形式返回结果。 5961 5962**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 5963 5964**参数：** 5965 5966| 参数名 | 类型 | 必填 | 说明 | 5967| ---------------- | --------------------------------------------------------- | ---- | ---------------------- | 5968| pixelmapSequence | Array\<[PixelMap](#pixelmap7)> | 是 | 待编码的PixelMap序列。 | 5969| options | [PackingOptionsForSequence](#packingoptionsforsequence18) | 是 | 动图编码参数。 | 5970 5971**返回值：** 5972 5973| 类型 | 说明 | 5974| --------------------- | ------------------------------- | 5975| Promise\<ArrayBuffer> | Promise对象，返回编码后的数据。 | 5976 5977**错误码：** 5978 5979以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 5980 5981| 错误码ID | 错误信息 | 5982| -------- | ------------------------------------------------------------ | 5983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 5984| 7800201 | Unsupported options. | 5985| 7800301 | Encoding failed. | 5986 5987**示例：** 5988 5989```ts 5990import { BusinessError } from '@ohos.base'; 5991import image from "@ohos.multimedia.image"; 5992 5993// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 5994let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 5995const resourceMgr = context.resourceManager; 5996// 此处'moving_test.gif'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 5997const fileData = resourceMgr.getRawFileContent('moving_test.gif'); 5998const color = fileData.buffer; 5999let imageSource = image.createImageSource(color); 6000let pixelMapList = imageSource.createPixelMapList(); 6001let ops: image.PackingOptionsForSequence = { 6002 frameCount: 3, // 指定GIF编码中的帧数为3。 6003 delayTimeList: [10, 10, 10], // 指定GIF编码中3帧的延迟时间分别为100ms、100ms、100ms。 6004 disposalTypes: [3, 2, 3], // 指定GIF编码中3帧的帧过渡模式分别为3（恢复到之前的状态）、2（恢复背景色)、3(恢复到之前的状态)。 6005 loopCount: 0 // 指定GIF编码中循环次数为无限循环。 6006}; 6007let Packer = image.createImagePacker(); 6008Packer.packToDataFromPixelmapSequence(pixelMapList, ops) 6009 .then((data: ArrayBuffer) => { 6010 console.info('Succeeded in packing.'); 6011 }).catch((error: BusinessError) => { 6012 console.error('Failed to packing.'); 6013 }) 6014``` 6015 6016### packing<sup>(deprecated)</sup> 6017 6018packing(source: ImageSource, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 6019 6020图片压缩或重新编码，使用callback形式返回结果。 6021 6022> **说明：** 6023> 6024> 从API version 6开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6025 6026**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6027 6028**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6029 6030**参数：** 6031 6032| 参数名 | 类型 | 必填 | 说明 | 6033| -------- | ---------------------------------- | ---- | ---------------------------------- | 6034| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6035| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6036| callback | AsyncCallback\<ArrayBuffer> | 是 | 回调函数，当图片编码成功，err为undefined，data为获取到的压缩或编码数据；否则为错误对象。 | 6037 6038**示例：** 6039 6040```ts 6041import { BusinessError } from '@kit.BasicServicesKit'; 6042 6043// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6044let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6045//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6046let filePath: string = context.filesDir + "/test.jpg"; 6047const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 6048let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6049const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6050imagePackerApi.packing(imageSourceApi, packOpts, (err: BusinessError, data: ArrayBuffer) => { 6051 if (err) { 6052 console.error(`Failed to pack the image.code ${err.code},message is ${err.message}`); 6053 } else { 6054 console.info('Succeeded in packing the image.'); 6055 } 6056}) 6057``` 6058 6059### packing<sup>(deprecated)</sup> 6060 6061packing(source: ImageSource, option: PackingOption): Promise\<ArrayBuffer> 6062 6063图片压缩或重新编码，使用Promise形式返回结果。 6064 6065> **说明：** 6066> 6067> 从API version 6开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6068 6069**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6070 6071**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6072 6073**参数：** 6074 6075| 参数名 | 类型 | 必填 | 说明 | 6076| ------ | ------------------------------- | ---- | -------------- | 6077| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6078| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6079 6080**返回值：** 6081 6082| 类型 | 说明 | 6083| ---------------------------- | --------------------------------------------- | 6084| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。 | 6085 6086**示例：** 6087 6088```ts 6089import { BusinessError } from '@kit.BasicServicesKit'; 6090 6091// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6092let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6093//此处'test.jpg'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6094let filePath: string = context.filesDir + "/test.jpg"; 6095const imageSourceApi: image.ImageSource = image.createImageSource(filePath); 6096let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6097const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6098imagePackerApi.packing(imageSourceApi, packOpts) 6099 .then((data: ArrayBuffer) => { 6100 console.info('Succeeded in packing the image.'); 6101 }).catch((error: BusinessError) => { 6102 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 6103 }) 6104``` 6105 6106### packing<sup>(deprecated)</sup> 6107 6108packing(source: PixelMap, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 6109 6110图片压缩或重新编码，使用callback形式返回结果。 6111 6112> **说明：** 6113> 6114> 从API version 8开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6115 6116> **注意：** 6117> 接口如果返回"PixelMap mismatch"，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6118 6119**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6120 6121**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6122 6123**参数：** 6124 6125| 参数名 | 类型 | 必填 | 说明 | 6126| -------- | ------------------------------- | ---- | ---------------------------------- | 6127| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap资源。 | 6128| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6129| callback | AsyncCallback\<ArrayBuffer> | 是 | 回调函数，当图片编码成功，err为undefined，data为获取到的压缩或编码数据；否则为错误对象。 | 6130 6131**示例：** 6132 6133```ts 6134import { BusinessError } from '@kit.BasicServicesKit'; 6135 6136const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6137let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6138image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 6139 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6140 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6141 imagePackerApi.packing(pixelMap, packOpts, (err: BusinessError, data: ArrayBuffer) => { 6142 if (err) { 6143 console.error(`Failed to pack the image.code ${err.code},message is ${err.message}`); 6144 } else { 6145 console.info('Succeeded in packing the image.'); 6146 } 6147 }) 6148}).catch((error: BusinessError) => { 6149 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 6150}) 6151``` 6152 6153### packing<sup>(deprecated)</sup> 6154 6155packing(source: PixelMap, option: PackingOption): Promise\<ArrayBuffer> 6156 6157图片压缩或重新编码，使用Promise形式返回结果。 6158 6159> **说明：** 6160> 6161> 从API version 8开始支持，从API version 13开始废弃，建议使用[packToData](#packtodata13)代替。 6162 6163> **注意：** 6164> 接口如果返回"PixelMap mismatch"，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6165 6166**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 6167 6168**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6169 6170**参数：** 6171 6172| 参数名 | 类型 | 必填 | 说明 | 6173| ------ | ------------------------------- | ---- | ------------------ | 6174| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap源。 | 6175| option | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6176 6177**返回值：** 6178 6179| 类型 | 说明 | 6180| --------------------- | -------------------------------------------- | 6181| Promise\<ArrayBuffer> | Promise对象，返回压缩或编码后的数据。| 6182 6183**示例：** 6184 6185```ts 6186import { BusinessError } from '@kit.BasicServicesKit'; 6187 6188const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6189let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6190image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 6191 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6192 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6193 imagePackerApi.packing(pixelMap, packOpts) 6194 .then((data: ArrayBuffer) => { 6195 console.info('Succeeded in packing the image.'); 6196 }).catch((error: BusinessError) => { 6197 console.error(`Failed to pack the image.code ${error.code},message is ${error.message}`); 6198 }) 6199}).catch((error: BusinessError) => { 6200 console.error(`Failed to create PixelMap.code ${error.code},message is ${error.message}`); 6201}) 6202``` 6203 6204### release 6205 6206release(callback: AsyncCallback\<void>): void 6207 6208释放图片编码实例，使用callback形式返回结果。 6209 6210ArkTS有内存回收机制，ImagePacker对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 6211 6212**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6213 6214**参数：** 6215 6216| 参数名 | 类型 | 必填 | 说明 | 6217| -------- | -------------------- | ---- | ------------------------------ | 6218| callback | AsyncCallback\<void> | 是 | 回调函数，当释放图片编码实例成功，err为undefined，否则为错误对象。 | 6219 6220**示例：** 6221 6222```ts 6223import { BusinessError } from '@kit.BasicServicesKit'; 6224 6225const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6226imagePackerApi.release((err: BusinessError)=>{ 6227 if (err) { 6228 console.error(`Failed to release image packaging.code ${err.code},message is ${err.message}`); 6229 } else { 6230 console.info('Succeeded in releasing image packaging.'); 6231 } 6232}) 6233``` 6234 6235### release 6236 6237release(): Promise\<void> 6238 6239释放图片编码实例，使用Promise形式返回释放结果。 6240 6241ArkTS有内存回收机制，ImagePacker对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 6242 6243**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6244 6245**返回值：** 6246 6247| 类型 | 说明 | 6248| -------------- | ------------------------------------------------------ | 6249| Promise\<void> | Promise对象。无返回结果的Promise对象。| 6250 6251**示例：** 6252 6253```ts 6254import { BusinessError } from '@kit.BasicServicesKit'; 6255 6256const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6257imagePackerApi.release().then(() => { 6258 console.info('Succeeded in releasing image packaging.'); 6259}).catch((error: BusinessError) => { 6260 console.error(`Failed to release image packaging.code ${error.code},message is ${error.message}`); 6261}) 6262``` 6263 6264### packToFile<sup>11+</sup> 6265 6266packToFile(source: ImageSource, fd: number, options: PackingOption, callback: AsyncCallback\<void>): void 6267 6268指定编码参数，将ImageSource直接编码进文件。使用callback形式返回结果。 6269 6270**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6271 6272**参数：** 6273 6274| 参数名 | 类型 | 必填 | 说明 | 6275| -------- | ------------------------------- | ---- | ------------------------------ | 6276| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6277| fd | number | 是 | 文件描述符。 | 6278| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6279| callback | AsyncCallback\<void> | 是 | 回调函数，当编码进文件成功，err为undefined，否则为错误对象。 | 6280 6281**错误码：** 6282 6283以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6284 6285| 错误码ID | 错误信息 | 6286| ------- | --------------------------------------------| 6287| 62980096| The Operation failed. | 6288| 62980101 | The image data is abnormal. | 6289| 62980106 | The image is too large. | 6290| 62980113 | Unknown image format. | 6291| 62980115 | If the parameter is invalid. | 6292| 62980119 | If encoder occur error during encoding. | 6293| 62980120 | Add pixelmap out of range. | 6294| 62980172 | Failed to encode icc. | 6295| 62980252 | Failed to create surface. | 6296 6297**示例：** 6298 6299```ts 6300import { BusinessError } from '@kit.BasicServicesKit'; 6301import { fileIo as fs } from '@kit.CoreFileKit'; 6302 6303// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6304let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6305//此处'test.png'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6306const path: string = context.filesDir + "/test.png"; 6307const imageSourceApi: image.ImageSource = image.createImageSource(path); 6308let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6309const filePath: string = context.filesDir + "/image_source.jpg"; 6310let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6311const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6312imagePackerApi.packToFile(imageSourceApi, file.fd, packOpts, (err: BusinessError) => { 6313 if (err) { 6314 console.error(`Failed to pack the image to file.code ${err.code},message is ${err.message}`); 6315 } else { 6316 console.info('Succeeded in packing the image to file.'); 6317 } 6318}) 6319``` 6320 6321### packToFile<sup>11+</sup> 6322 6323packToFile (source: ImageSource, fd: number, options: PackingOption): Promise\<void> 6324 6325指定编码参数，将ImageSource直接编码进文件。使用Promise形式返回结果。 6326 6327**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6328 6329**参数：** 6330 6331| 参数名 | 类型 | 必填 | 说明 | 6332| ------ | ------------------------------- | ---- | -------------- | 6333| source | [ImageSource](#imagesource) | 是 | 编码的ImageSource。 | 6334| fd | number | 是 | 文件描述符。 | 6335| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6336 6337**返回值：** 6338 6339| 类型 | 说明 | 6340| -------------- | --------------------------------- | 6341| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6342 6343**错误码：** 6344 6345以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6346 6347| 错误码ID | 错误信息 | 6348| ------- | --------------------------------------------| 6349| 62980096| The Operation failed. | 6350| 62980101 | The image data is abnormal. | 6351| 62980106 | The image is too large. | 6352| 62980113 | Unknown image format. | 6353| 62980115 | If the parameter is invalid. | 6354| 62980119 | If encoder occur error during encoding. | 6355| 62980120 | Add pixelmap out of range. | 6356| 62980172 | Failed to encode icc. | 6357| 62980252 | Failed to create surface. | 6358 6359**示例：** 6360 6361```ts 6362import { BusinessError } from '@kit.BasicServicesKit'; 6363import { fileIo as fs } from '@kit.CoreFileKit'; 6364 6365// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6366let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6367//此处'test.png'仅作示例，请开发者自行替换，否则imageSource会创建失败导致后续无法正常执行。 6368const path: string = context.filesDir + "/test.png"; 6369const imageSourceApi: image.ImageSource = image.createImageSource(path); 6370let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 }; 6371const filePath: string = context.filesDir + "/image_source.jpg"; 6372let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6373const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6374imagePackerApi.packToFile(imageSourceApi, file.fd, packOpts).then(() => { 6375 console.info('Succeeded in packing the image to file.'); 6376}).catch((error: BusinessError) => { 6377 console.error(`Failed to pack the image to file.code ${error.code},message is ${error.message}`); 6378}) 6379``` 6380 6381### packToFile<sup>11+</sup> 6382 6383packToFile (source: PixelMap, fd: number, options: PackingOption, callback: AsyncCallback\<void>): void 6384 6385指定编码参数，将PixelMap直接编码进文件。使用callback形式返回结果。 6386 6387> **注意：** 6388> 接口如果返回62980115错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6389 6390**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6391 6392**参数：** 6393 6394| 参数名 | 类型 | 必填 | 说明 | 6395| -------- | ------------------------------- | ---- | ------------------------------ | 6396| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap资源。 | 6397| fd | number | 是 | 文件描述符。 | 6398| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6399| callback | AsyncCallback\<void> | 是 | 回调函数，当编码图片进文件成功，err为undefined，否则为错误对象。 | 6400 6401**错误码：** 6402 6403以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6404 6405| 错误码ID | 错误信息 | 6406| ------- | --------------------------------------------| 6407| 62980096| The Operation failed. | 6408| 62980101 | The image data is abnormal. | 6409| 62980106 | The image is too large. | 6410| 62980113 | Unknown image format. | 6411| 62980115 | If the parameter is invalid. | 6412| 62980119 | If encoder occur error during encoding. | 6413| 62980120 | Add pixelmap out of range. | 6414| 62980172 | Failed to encode icc. | 6415| 62980252 | Failed to create surface. | 6416 6417**示例：** 6418 6419```ts 6420import { BusinessError } from '@kit.BasicServicesKit'; 6421import { fileIo as fs } from '@kit.CoreFileKit'; 6422 6423const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6424let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6425// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6426let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6427const path: string = context.filesDir + "/pixel_map.jpg"; 6428image.createPixelMap(color, opts).then((pixelmap: image.PixelMap) => { 6429 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6430 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6431 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6432 imagePackerApi.packToFile(pixelmap, file.fd, packOpts, (err: BusinessError) => { 6433 if (err) { 6434 console.error(`Failed to pack the image to file.code ${err.code},message is ${err.message}`); 6435 } else { 6436 console.info('Succeeded in packing the image to file.'); 6437 } 6438 }) 6439}) 6440``` 6441 6442### packToFile<sup>11+</sup> 6443 6444packToFile (source: PixelMap, fd: number, options: PackingOption): Promise\<void> 6445 6446指定编码参数，将PixelM直接编码进文件。使用Promise形式返回结果。 6447 6448> **注意：** 6449> 接口如果返回62980115错误码，表明参数异常，可能是PixelMap对象被提前释放了。需要调用方排查，在该方法调用结束后再释放PixelMap对象。 6450 6451**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6452 6453**参数：** 6454 6455| 参数名 | 类型 | 必填 | 说明 | 6456| ------ | ------------------------------- | ---- | -------------------- | 6457| source | [PixelMap](#pixelmap7) | 是 | 编码的PixelMap资源。 | 6458| fd | number | 是 | 文件描述符。 | 6459| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6460 6461**返回值：** 6462 6463| 类型 | 说明 | 6464| -------------- | --------------------------------- | 6465| Promise\<void> | Promise对象。无返回结果的Promise对象。| 6466 6467**错误码：** 6468 6469以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6470 6471| 错误码ID | 错误信息 | 6472| ------- | --------------------------------------------| 6473| 62980096| The Operation failed. | 6474| 62980101 | The image data is abnormal. | 6475| 62980106 | The image is too large. | 6476| 62980113 | Unknown image format. | 6477| 62980115 | If the parameter is invalid. | 6478| 62980119 | If encoder occur error during encoding. | 6479| 62980120 | Add pixelmap out of range. | 6480| 62980172 | Failed to encode icc. | 6481| 62980252 | Failed to create surface. | 6482 6483**示例：** 6484 6485```ts 6486import { BusinessError } from '@kit.BasicServicesKit'; 6487import { fileIo as fs } from '@kit.CoreFileKit'; 6488 6489const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 6490let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 6491// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6492let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6493const path: string = context.filesDir + "/pixel_map.jpg"; 6494image.createPixelMap(color, opts).then((pixelmap: image.PixelMap) => { 6495 let packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 } 6496 let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6497 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6498 imagePackerApi.packToFile(pixelmap, file.fd, packOpts) 6499 .then(() => { 6500 console.info('Succeeded in packing the image to file.'); 6501 }).catch((error: BusinessError) => { 6502 console.error(`Failed to pack the image to file.code ${error.code},message is ${error.message}`); 6503 }) 6504}) 6505``` 6506 6507### packToFile<sup>13+</sup> 6508 6509packToFile(picture: Picture, fd: number, options: PackingOption): Promise\<void> 6510 6511指定编码参数，将Picture直接编码进文件。使用Promise形式返回结果。 6512 6513**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6514 6515**参数：** 6516 6517| 参数名 | 类型 | 必填 | 说明 | 6518| ------- | ---------------------------- | ---- | -------------------- | 6519| picture | [Picture](#picture13) | 是 | 编码的Picture资源。 | 6520| fd | number | 是 | 文件描述符。 | 6521| options | [PackingOption](#packingoption) | 是 | 设置编码参数。 | 6522 6523**返回值：** 6524 6525| 类型 | 说明 | 6526| -------------- | ------------------------- | 6527| Promise\<void> | 无返回结果的Promise对象。 | 6528 6529**错误码：** 6530 6531以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6532 6533| 错误码ID | 错误信息 | 6534| -------- | ------------------------------------------------------------ | 6535| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6536| 7800301 | Encode failed. | 6537 6538**示例：** 6539 6540```ts 6541import { BusinessError } from '@kit.BasicServicesKit'; 6542import { image } from '@kit.ImageKit'; 6543import { fileIo as fs } from '@kit.CoreFileKit'; 6544 6545async function PackToFile(context: Context) { 6546 const resourceMgr = context.resourceManager; 6547 const rawFile = await resourceMgr.getRawFileContent("test.jpg"); 6548 let ops: image.SourceOptions = { 6549 sourceDensity: 98, 6550 } 6551 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6552 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6553 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6554 6555 let funcName = "PackToFile"; 6556 const imagePackerApi: image.ImagePacker = image.createImagePacker(); 6557 if (imagePackerApi != null) { 6558 const filePath: string = context.filesDir + "/test.jpg"; 6559 let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6560 let packOpts: image.PackingOption = { 6561 format: "image/jpeg", 6562 quality: 98, 6563 bufferSize: 10, 6564 desiredDynamicRange: image.PackingDynamicRange.AUTO, 6565 needsPackProperties: true}; 6566 await imagePackerApi.packToFile(pictureObj, file.fd, packOpts).then(() => { 6567 console.info(funcName, 'Succeeded in packing the image to file.'); 6568 }).catch((error: BusinessError) => { 6569 console.error(funcName, 'Failed to pack the image to file.code ${error.code},message is ${error.message}'); 6570 }); 6571 } 6572} 6573``` 6574 6575### packToFileFromPixelmapSequence<sup>18+</sup> 6576 6577packToFileFromPixelmapSequence(pixelmapSequence: Array\<PixelMap>, fd: number, options: PackingOptionsForSequence): Promise\<void> 6578 6579指定编码参数，将多个PixelMap编码成GIF文件。使用Promise形式返回结果。 6580 6581**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 6582 6583**参数：** 6584 6585| 参数名 | 类型 | 必填 | 说明 | 6586| ---------------- | --------------------------------------------------------- | ---- | ---------------------- | 6587| pixelmapSequence | Array<[PixelMap](#pixelmap7)> | 是 | 待编码的PixelMap序列。 | 6588| fd | number | 是 | 文件描述符。 | 6589| options | [PackingOptionsForSequence](#packingoptionsforsequence18) | 是 | 动图编码参数。 | 6590 6591**返回值：** 6592 6593| 类型 | 说明 | 6594| -------------- | ------------------------- | 6595| Promise\<void> | 无返回结果的Promise对象。 | 6596 6597**错误码：** 6598 6599以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Image错误码](errorcode-image.md)。 6600 6601| 错误码ID | 错误信息 | 6602| -------- | ------------------------------------------------------------ | 6603| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6604| 7800201 | Unsupported options. | 6605| 7800301 | Encoding failed. | 6606 6607**示例：** 6608 6609```ts 6610import { BusinessError } from '@ohos.base'; 6611import fs from '@ohos.file.fs'; 6612import image from "@ohos.multimedia.image"; 6613 6614// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 6615let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 6616const resourceMgr = context.resourceManager; 6617// 此处'moving_test.gif'仅作示例，请开发者自行替换。否则imageSource会创建失败，导致后续无法正常执行。 6618const fileData = await resourceMgr.getRawFileContent('moving_test.gif'); 6619const color = fileData.buffer; 6620let imageSource = image.createImageSource(color); 6621let pixelMapList = await imageSource.createPixelMapList(); 6622let path: string = context.cacheDir + '/result.gif'; 6623let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 6624let ops: image.PackingOptionsForSequence = { 6625 frameCount: 3, // 指定GIF编码中的帧数为3。 6626 delayTimeList: [10, 10, 10], // 指定GIF编码中3帧的延迟时间分别为100ms、100ms、100ms。 6627 disposalTypes: [3, 2, 3], // 指定GIF编码中3帧的帧过渡模式分别为3（恢复到之前的状态）、2（恢复背景色)、3(恢复到之前的状态)。 6628 loopCount: 0 // 指定GIF编码中循环次数为无限循环。 6629}; 6630let Packer = image.createImagePacker(); 6631Packer.packToFileFromPixelmapSequence(pixelMapList, file.fd, ops) 6632 .then(() => { 6633 console.info('Succeeded in packToFileMultiFrames.'); 6634 }).catch((error: BusinessError) => { 6635 console.error('Failed to packToFileMultiFrames.'); 6636 }) 6637``` 6638 6639## image.createAuxiliaryPicture<sup>13+</sup> 6640 6641createAuxiliaryPicture(buffer: ArrayBuffer, size: Size, type: AuxiliaryPictureType): AuxiliaryPicture 6642 6643通过ArrayBuffer图片数据、辅助图尺寸、辅助图类型创建AuxiliaryPicture实例。 6644 6645**系统能力：** SystemCapability.Multimedia.Image.Core 6646 6647**参数：** 6648 6649| 参数名 | 类型 | 必填 | 说明 | 6650| ------ | ----------------------------------------------- | ---- | ---------------------------- | 6651| buffer | ArrayBuffer | 是 | 以buffer形式存放的图像数据。 | 6652| size | [Size](#size) | 是 | 辅助图的尺寸。单位：像素。 | 6653| type | [AuxiliaryPictureType](#auxiliarypicturetype13) | 是 | 辅助图类型。 | 6654 6655**返回值：** 6656 6657| 类型 | 说明 | 6658| --------------------------------------- | ------------------------------------------ | 6659| [AuxiliaryPicture](#auxiliarypicture13) | 如果操作成功，则返回AuxiliaryPicture实例。 | 6660 6661**错误码：** 6662 6663以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6664 6665| 错误码ID | 错误信息 | 6666| -------- | ------------------------------------------------------------ | 6667| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6668 6669**示例：** 6670 6671```ts 6672import { image } from '@kit.ImageKit'; 6673 6674async function CreateAuxiliaryPicture(context: Context) { 6675 let funcName = "CreateAuxiliaryPicture"; 6676 const resourceMgr = context.resourceManager; 6677 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 6678 let auxBuffer: ArrayBuffer = rawFile.buffer as ArrayBuffer; 6679 let auxSize: Size = { 6680 height: 180, 6681 width: 240 6682 }; 6683 let auxType: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP; 6684 let auxPictureObj: image.AuxiliaryPicture | null = image.createAuxiliaryPicture(auxBuffer, auxSize, auxType); 6685 if(auxPictureObj != null) { 6686 let type: image.AuxiliaryPictureType = auxPictureObj.getType(); 6687 console.info(funcName, 'CreateAuxiliaryPicture succeeded this.Aux_picture.type.' + JSON.stringify(type)); 6688 } else { 6689 console.error(funcName, 'CreateAuxiliaryPicture failed'); 6690 } 6691} 6692``` 6693 6694## AuxiliaryPicture<sup>13+</sup> 6695 6696辅助图一般用于辅助主图进行特殊信息的展示，使图像包含更丰富的信息。辅助图图像类，用于读取或写入图像的辅助图数据以及获取图像的辅助图信息。在调用AuxiliaryPicture的方法前，需要先通过[createAuxiliaryPicture](#imagecreateauxiliarypicture13)创建一个AuxiliaryPicture实例。 6697 6698### 属性 6699 6700**系统能力：** SystemCapability.Multimedia.Image.Core 6701 6702### writePixelsFromBuffer<sup>13+</sup> 6703 6704writePixelsFromBuffer(data: ArrayBuffer): Promise\<void> 6705 6706读取ArrayBuffer中的辅助图片数据，并将数据写入AuxiliaryPicture对象，使用Promise形式返回。 6707 6708**系统能力：** SystemCapability.Multimedia.Image.Core 6709 6710**参数：** 6711 6712| 参数名 | 类型 | 必填 | 说明 | 6713| ------ | ----------- | ---- | ---------------- | 6714| data | ArrayBuffer | 是 | 辅助图像素数据。 | 6715 6716**返回值：** 6717 6718| 类型 | 说明 | 6719| -------------- | -------------------------------------- | 6720| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6721 6722**错误码：** 6723 6724以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6725 6726| 错误码ID | 错误信息 | 6727| -------- | ------------------------------------------------------------ | 6728| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6729| 7600301 | Memory alloc failed. | 6730| 7600302 | Memory copy failed. | 6731 6732**示例:** 6733 6734```ts 6735import { image } from '@kit.ImageKit'; 6736 6737async function WritePixelsFromBuffer(context: Context) { 6738 const resourceMgr = context.resourceManager; 6739 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 6740 let ops: image.SourceOptions = { 6741 sourceDensity: 98, 6742 } 6743 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6744 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6745 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6746 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP); 6747 if(auxPictureObj != null) { 6748 let auxBuffer: ArrayBuffer = await auxPictureObj.readPixelsToBuffer(); 6749 await auxPictureObj.writePixelsFromBuffer(auxBuffer); 6750 console.info('Write pixels from buffer success.'); 6751 } else { 6752 console.error('AuxPictureObj is null.'); 6753 } 6754} 6755``` 6756 6757### readPixelsToBuffer<sup>13+</sup> 6758 6759readPixelsToBuffer(): Promise\<ArrayBuffer> 6760 6761读取图像像素映射数据并将数据写入ArrayBuffer，使用Promise形式返回。 6762 6763**系统能力：** SystemCapability.Multimedia.Image.Core 6764 6765**返回值：** 6766 6767| 类型 | 说明 | 6768| --------------------- | --------------------------------- | 6769| Promise\<ArrayBuffer> | Promise对象。返回辅助图像素数据。 | 6770 6771**错误码：** 6772 6773以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6774 6775| 错误码ID | 错误信息 | 6776| -------- | -------------------- | 6777| 7600301 | Memory alloc failed. | 6778| 7600302 | Memory copy failed. | 6779 6780**示例：** 6781 6782```ts 6783import { BusinessError } from '@kit.BasicServicesKit'; 6784import { image } from '@kit.ImageKit'; 6785 6786async function ReadPixelsToBuffer(context: Context) { 6787 const resourceMgr = context.resourceManager; 6788 const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); //需要支持hdr的图片。 6789 let ops: image.SourceOptions = { 6790 sourceDensity: 98, 6791 } 6792 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 6793 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 6794 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 6795 let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP); 6796 if(auxPictureObj != null) { 6797 await auxPictureObj.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => { 6798 console.info('Read pixels to buffer success.' ); 6799 }).catch((error: BusinessError) => { 6800 console.error('Read pixels to buffer failed error.code: ' + JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 6801 }); 6802 } else { 6803 console.error('AuxPictureObj is null.'); 6804 } 6805} 6806``` 6807 6808### getType<sup>13+</sup> 6809 6810getType(): AuxiliaryPictureType 6811 6812获取辅助图的类型。 6813 6814**系统能力：** SystemCapability.Multimedia.Image.Core 6815 6816**返回值：** 6817 6818| 类型 | 说明 | 6819| ----------------------------------------------- | ---------------------------- | 6820| [AuxiliaryPictureType](#auxiliarypicturetype13) | 操作成功，返回辅助图的类型。 | 6821 6822**示例：** 6823 6824```ts 6825import { image } from '@kit.ImageKit'; 6826 6827async function GetAuxiliaryPictureType() { 6828 if (auxPictureObj != null) { 6829 let type: image.AuxiliaryPictureType = auxPictureObj.getType(); 6830 console.info('Success get auxiliary picture type ' + JSON.stringify(type)); 6831 } else { 6832 console.info('Failed get auxiliary picture type '); 6833 } 6834} 6835``` 6836 6837### setMetadata<sup>13+</sup> 6838 6839setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void> 6840 6841设置辅助图元数据。 6842 6843**系统能力：** SystemCapability.Multimedia.Image.Core 6844 6845**参数：** 6846 6847| 参数名 | 类型 | 必填 | 说明 | 6848| ------------ | ------------------------------- | ---- | ------------------------------------ | 6849| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据的类型，用于设置对应的元数据。 | 6850| metadata | [Metadata](#metadata13) | 是 | 元数据对象。 | 6851 6852**返回值：** 6853 6854| 类型 | 说明 | 6855| -------------- | -------------------------------------- | 6856| Promise\<void> | Promise对象，无返回结果的Promise对象。 | 6857 6858**错误码：** 6859 6860以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6861 6862| 错误码ID | 错误信息 | 6863| -------- | ------------------------------------------------------------ | 6864| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6865| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 6866 6867**示例：** 6868 6869```ts 6870import { BusinessError } from '@kit.BasicServicesKit'; 6871import { image } from '@kit.ImageKit'; 6872 6873async function SetAuxPictureObjMetadata(exifContext: Context) { 6874 const exifResourceMgr = exifContext.resourceManager; 6875 const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");//图片包含exif metadata。 6876 let exifOps: image.SourceOptions = { 6877 sourceDensity: 98, 6878 } 6879 let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps); 6880 let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap(); 6881 let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap); 6882 if (exifPictureObj != null) { 6883 console.info('Create picture succeeded'); 6884 } else { 6885 console.info('Create picture failed'); 6886 } 6887 6888 if (auxPictureObj != null) { 6889 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6890 let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType); 6891 auxPictureObj.setMetadata(metadataType, exifMetaData).then(() => { 6892 console.info('Set metadata success'); 6893 }).catch((error: BusinessError) => { 6894 console.error('Set metadata failed.error.code: ${error.code}, error.message: ${error.message}'); 6895 }); 6896 } else { 6897 console.info('AuxPictureObjMetaData is null'); 6898 } 6899} 6900``` 6901 6902### getMetadata<sup>13+</sup> 6903 6904getMetadata(metadataType: MetadataType): Promise\<Metadata> 6905 6906从辅助图中获取元数据。 6907 6908**系统能力：** SystemCapability.Multimedia.Image.Core 6909 6910**参数：** 6911 6912| 参数名 | 类型 | 必填 | 说明 | 6913| ------------ | ------------------------------- | ---- | -------------------------------------- | 6914| metadataType | [MetadataType](#metadatatype13) | 是 | 元数据类型，用于获取对应类型的元数据。 | 6915 6916**返回值：** 6917 6918| 类型 | 说明 | 6919| -------------------------------- | ---------------- | 6920| Promise<[Metadata](#metadata13)> | 返回元数据对象。 | 6921 6922**错误码：** 6923 6924以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 6925 6926| 错误码ID | 错误信息 | 6927| -------- | ------------------------------------------------------------ | 6928| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 6929| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 6930 6931**示例：** 6932 6933```ts 6934import { image } from '@kit.ImageKit'; 6935 6936async function GetAuxPictureObjMetadata() { 6937 if (auxPictureObj != null) { 6938 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 6939 let auxPictureObjMetaData: image.Metadata | null = await auxPictureObj.getMetadata(metadataType); 6940 if (auxPictureObjMetaData != null) { 6941 console.info('Get auxpictureobj Metadata success' ); 6942 } else { 6943 console.info('Get auxpictureobj Metadata failed'); 6944 } 6945 } else { 6946 console.info('Get auxpictureobj is null.'); 6947 } 6948} 6949``` 6950 6951### getAuxiliaryPictureinfo<sup>13+</sup> 6952 6953getAuxiliaryPictureInfo(): AuxiliaryPictureInfo 6954 6955获取有关此辅助图的图像信息。 6956 6957**系统能力：** SystemCapability.Multimedia.Image.Core 6958 6959**返回值：** 6960 6961| 类型 | 说明 | 6962| ----------------------------------------------- | --------------------------------- | 6963| [AuxiliaryPictureInfo](#auxiliarypictureinfo13) | Promise对象，返回辅助图图像信息。 | 6964 6965**示例：** 6966 6967```ts 6968import { image } from '@kit.ImageKit'; 6969 6970async function GetAuxiliaryPictureInfo() { 6971 if(auxPictureObj != null) { 6972 let auxinfo: image.AuxiliaryPictureInfo = auxPictureObj.getAuxiliaryPictureInfo(); 6973 console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType + 6974 ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width + 6975 ' rowStride: ' + auxinfo.rowStride + ' pixelFormat: ' + auxinfo.pixelFormat + 6976 ' colorSpace: ' + auxinfo.colorSpace); 6977 } else { 6978 console.info('Get auxiliary picture information failed'); 6979 } 6980} 6981``` 6982 6983### setAuxiliaryPictureinfo<sup>13+</sup> 6984 6985setAuxiliaryPictureInfo(info: AuxiliaryPictureInfo): void 6986 6987设置辅助图的图像信息。 6988 6989**系统能力：** SystemCapability.Multimedia.Image.Core 6990 6991**参数：** 6992 6993| 参数名 | 类型 | 必填 | 说明 | 6994| ------ | ----------------------------------------------- | ---- | ------------------ | 6995| info | [AuxiliaryPictureInfo](#auxiliarypictureinfo13) | 是 | 辅助图的图像信息。 | 6996 6997**错误码：** 6998 6999以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7000 7001| 错误码ID | 错误信息 | 7002| -------- | :----------------------------------------------------------- | 7003| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 7004 7005**示例：** 7006 7007```ts 7008import { colorSpaceManager } from '@kit.ArkGraphics2D'; 7009import { image } from '@kit.ImageKit'; 7010 7011async function SetAuxiliaryPictureInfo() { 7012 if(auxPictureObj != null) { 7013 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 7014 let info: image.AuxiliaryPictureInfo = { 7015 auxiliaryPictureType: image.AuxiliaryPictureType.GAINMAP, 7016 size: {height: 100, width: 200}, 7017 pixelFormat: image.PixelMapFormat.RGBA_8888, 7018 rowStride: 0, 7019 colorSpace: colorSpaceManager.create(colorSpaceName), 7020 }; 7021 auxPictureObj.setAuxiliaryPictureInfo(info); 7022 } 7023} 7024``` 7025 7026### release<sup>13+</sup> 7027 7028release():void 7029 7030释放辅助图对象，无返回值。 7031 7032**系统能力：** SystemCapability.Multimedia.Image.Core 7033 7034**示例：** 7035 7036```ts 7037import { image } from '@kit.ImageKit'; 7038 7039async function Release() { 7040 let funcName = "Release"; 7041 if (auxPictureObj != null) { 7042 auxPictureObj.release(); 7043 if (auxPictureObj.getType() == null) { 7044 console.info(funcName, 'Success !'); 7045 } else { 7046 console.info(funcName, 'Failed !'); 7047 } 7048 } else { 7049 console.info('PictureObj is null'); 7050 } 7051} 7052``` 7053 7054## Metadata<sup>13+</sup> 7055 7056图像元数据类，用于存储图像的元数据。目前支持的元数据类型可参考[MetadataType](#metadatatype13)。 7057 7058### 属性 7059 7060**系统能力：** SystemCapability.Multimedia.Image.Core 7061 7062### getProperties<sup>13+</sup> 7063 7064getProperties(key: Array\<string>): Promise\<Record\<string, string | null>> 7065 7066获取图像中属性的值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 7067 7068**系统能力：** SystemCapability.Multimedia.Image.Core 7069 7070**参数：** 7071 7072| 参数名 | 类型 | 必填 | 说明 | 7073| ------ | -------------- | ---- | ------------------------ | 7074| key | Array\<string> | 是 | 要获取其值的属性的名称。 | 7075 7076**返回值：** 7077 7078| 类型 | 说明 | 7079| ---------------------------------------- | ------------------------------------------------------------ | 7080| Promise\<Record<string, string \| null>> | Promise对象，返回元数据要获取的属性的值，如获取失败则返回错误码。 | 7081 7082**错误码：** 7083 7084以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7085 7086| 错误码ID | 错误信息 | 7087| -------- | ------------------------------------------------------------ | 7088| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 7089| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 7090 7091**示例：** 7092 7093```ts 7094import { BusinessError } from '@kit.BasicServicesKit'; 7095import { image } from '@kit.ImageKit'; 7096 7097async function GetProperties(context: Context) { 7098 const resourceMgr = context.resourceManager; 7099 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7100 let ops: image.SourceOptions = { 7101 sourceDensity: 98, 7102 } 7103 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7104 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7105 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7106 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7107 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7108 if (metaData != null) { 7109 await metaData.getProperties(["ImageWidth", "ImageLength"]).then((data2) => { 7110 console.info('Get properties ',JSON.stringify(data2)); 7111 }).catch((error: BusinessError) => { 7112 console.info('Get properties failed error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 7113 }); 7114 } else { 7115 console.info('Metadata is null.'); 7116 } 7117} 7118``` 7119 7120### setProperties<sup>13+</sup> 7121 7122setProperties(records: Record\<string, string | null>): Promise\<void> 7123 7124批量设置图片元数据中的指定属性的值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 7125 7126**系统能力：** SystemCapability.Multimedia.Image.Core 7127 7128**参数：** 7129 7130| 参数名 | 类型 | 必填 | 说明 | 7131| ------- | ------------------------------ | ---- | ------------------------ | 7132| records | Record<string, string \| null> | 是 | 要修改的属性和值的数组。 | 7133 7134**返回值：** 7135 7136| 类型 | 说明 | 7137| -------------- | ------------------------------------- | 7138| Promise\<void> | Promise对象，如获取失败则返回错误码。 | 7139 7140**错误码：** 7141 7142以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7143 7144| 错误码ID | 错误信息 | 7145| -------- | ------------------------------------------------------------ | 7146| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed; | 7147| 7600202 | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. | 7148 7149**示例：** 7150 7151```ts 7152import { BusinessError } from '@kit.BasicServicesKit'; 7153import { image } from '@kit.ImageKit'; 7154 7155async function SetProperties(context: Context) { 7156 const resourceMgr = context.resourceManager; 7157 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7158 let ops: image.SourceOptions = { 7159 sourceDensity: 98, 7160 } 7161 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7162 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7163 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7164 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7165 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7166 if (metaData != null) { 7167 let setkey: Record<string, string | null> = { 7168 "ImageWidth": "200", 7169 "ImageLength": "300" 7170 }; 7171 await metaData.setProperties(setkey).then(async () => { 7172 console.info('Set auxpictureobj properties success.'); 7173 }).catch((error: BusinessError) => { 7174 console.error('Failed to set metadata Properties. code is ${error.code}, message is ${error.message}'); 7175 }) 7176 } else { 7177 console.info('AuxPictureObj metadata is null. '); 7178 } 7179} 7180``` 7181 7182### getAllProperties<sup>13+</sup> 7183 7184getAllProperties(): Promise\<Record<string, string | null>> 7185 7186获取图片中所有元数据的属性和值，使用Promise形式返回。如要查询属性值信息请参考[PropertyKey](#propertykey7)和[FragmentMapPropertyKey](#fragmentmappropertykey13)。 7187 7188**系统能力：** SystemCapability.Multimedia.Image.Core 7189 7190**返回值：** 7191 7192| 类型 | 说明 | 7193| ---------------------------------------- | ------------------------------------------- | 7194| Promise\<Record<string, string \| null>> | Promise对象，返回元数据拥有的所有属性的值。 | 7195 7196**示例：** 7197 7198```ts 7199import { BusinessError } from '@kit.BasicServicesKit'; 7200import { image } from '@kit.ImageKit'; 7201 7202async function GetAllProperties(context: Context) { 7203 const resourceMgr = context.resourceManager; 7204 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7205 let ops: image.SourceOptions = { 7206 sourceDensity: 98, 7207 } 7208 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7209 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7210 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7211 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7212 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7213 if (metaData != null) { 7214 await metaData.getAllProperties().then((data2) => { 7215 const count = Object.keys(data2).length; 7216 console.info('Metadata have ', count, ' properties'); 7217 console.info('Get metadata all properties: ', JSON.stringify(data2)); 7218 }).catch((error: BusinessError) => { 7219 console.error('Get metadata all properties failed error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message)); 7220 }); 7221 } else { 7222 console.info('Metadata is null.'); 7223 } 7224} 7225``` 7226 7227### clone<sup>13+</sup> 7228 7229clone(): Promise\<Metadata> 7230 7231对元数据进行克隆，用Promise形式返回结果。 7232 7233**系统能力：** SystemCapability.Multimedia.Image.Core 7234 7235**返回值：** 7236 7237| 类型 | 说明 | 7238| --------------------------------- | --------------------------------- | 7239| Promise\<[Metadata](#metadata13)> | Promise对象，成功返回元数据实例。 | 7240 7241**错误码：** 7242 7243以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7244 7245| 错误码ID | 错误信息 | 7246| -------- | -------------------- | 7247| 7600301 | Memory alloc failed. | 7248| 7600302 | Memory copy failed. | 7249 7250**示例：** 7251 7252```ts 7253import { BusinessError } from '@kit.BasicServicesKit'; 7254import { image } from '@kit.ImageKit'; 7255 7256async function clone(context: Context) { 7257 const resourceMgr = context.resourceManager; 7258 const rawFile = await resourceMgr.getRawFileContent("exif.jpg"); //图片包含exif metadata。 7259 let ops: image.SourceOptions = { 7260 sourceDensity: 98, 7261 } 7262 let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops); 7263 let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap(); 7264 let pictureObj: image.Picture = image.createPicture(commodityPixelMap); 7265 let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA; 7266 let metaData: image.Metadata | null = await pictureObj.getMetadata(metadataType); 7267 if (metaData != null) { 7268 let new_metadata: image.Metadata = await metaData.clone(); 7269 new_metadata.getProperties(["ImageWidth"]).then((data1) => { 7270 console.info('Clone new_metadata and get Properties.', JSON.stringify(data1)); 7271 }).catch((err: BusinessError) => { 7272 console.error('Clone new_metadata failed.', JSON.stringify(err)); 7273 }); 7274 } else { 7275 console.info('Metadata is null.'); 7276 } 7277} 7278``` 7279 7280## image.createImageReceiver<sup>11+</sup> 7281 7282createImageReceiver(size: Size, format: ImageFormat, capacity: number): ImageReceiver 7283 7284通过图片大小、图片格式、容量创建ImageReceiver实例。 7285 7286**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7287 7288**参数：** 7289 7290| 参数名 | 类型 | 必填 | 说明 | 7291| -------- | ------ | ---- | ---------------------- | 7292| size | [Size](#size) | 是 | 图像的默认大小。 | 7293| format | [ImageFormat](#imageformat9) | 是 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机）。 | 7294| capacity | number | 是 | 同时访问的最大图像数。 | 7295 7296**返回值：** 7297 7298| 类型 | 说明 | 7299| -------------------------------- | --------------------------------------- | 7300| [ImageReceiver](#imagereceiver9) | 如果操作成功，则返回ImageReceiver实例。 | 7301 7302**错误码：** 7303 7304以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7305 7306| 错误码ID | 错误信息 | 7307| ------- | --------------------------------------------| 7308| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 7309 7310**示例：** 7311 7312```ts 7313let size: image.Size = { 7314 height: 8192, 7315 width: 8 7316} 7317let receiver: image.ImageReceiver = image.createImageReceiver(size, image.ImageFormat.JPEG, 8); 7318``` 7319 7320## image.createImageReceiver<sup>(deprecated)</sup> 7321 7322createImageReceiver(width: number, height: number, format: number, capacity: number): ImageReceiver 7323 7324通过宽、高、图片格式、容量创建ImageReceiver实例。 7325 7326> **说明：** 7327> 7328> 从API version 11开始不再维护，建议使用[createImageReceiver](#imagecreateimagereceiver11)代替。 7329 7330**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7331 7332**参数：** 7333 7334| 参数名 | 类型 | 必填 | 说明 | 7335| -------- | ------ | ---- | ---------------------- | 7336| width | number | 是 | 图像的默认宽度。单位：像素。 | 7337| height | number | 是 | 图像的默认高度。单位：像素。 | 7338| format | number | 是 | 图像格式，取值为[ImageFormat](#imageformat9)常量（目前仅支持 ImageFormat:JPEG，实际返回格式由生产者决定，如相机）。 | 7339| capacity | number | 是 | 同时访问的最大图像数。 | 7340 7341**返回值：** 7342 7343| 类型 | 说明 | 7344| -------------------------------- | --------------------------------------- | 7345| [ImageReceiver](#imagereceiver9) | 如果操作成功，则返回ImageReceiver实例。 | 7346 7347**示例：** 7348 7349```ts 7350let receiver: image.ImageReceiver = image.createImageReceiver(8192, 8, image.ImageFormat.JPEG, 8); 7351``` 7352 7353## ImageReceiver<sup>9+</sup> 7354 7355图像接收类，用于获取组件surface id，接收最新的图片和读取下一张图片，以及释放ImageReceiver实例。 7356 7357在调用以下方法前需要先创建ImageReceiver实例。 7358 7359### 属性 7360 7361**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7362 7363| 名称 | 类型 | 可读 | 可写 | 说明 | 7364| -------- | ---------------------------- | ---- | ---- | ------------------ | 7365| size | [Size](#size) | 是 | 否 | 图片大小。 | 7366| capacity | number | 是 | 否 | 同时访问的图像数。 | 7367| format | [ImageFormat](#imageformat9) | 是 | 否 | 图像格式。 | 7368 7369### getReceivingSurfaceId<sup>9+</sup> 7370 7371getReceivingSurfaceId(callback: AsyncCallback\<string>): void 7372 7373用于获取一个surface id供Camera或其他组件使用。使用callback返回结果。 7374 7375**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7376 7377**参数：** 7378 7379| 参数名 | 类型 | 必填 | 说明 | 7380| -------- | ---------------------- | ---- | -------------------------- | 7381| callback | AsyncCallback\<string> | 是 | 回调函数，当获取surface id成功，err为undefined，data为获取到的surface id；否则为错误对象。 | 7382 7383**示例:** 7384 7385```ts 7386import { BusinessError } from '@kit.BasicServicesKit'; 7387 7388receiver.getReceivingSurfaceId((err: BusinessError, id: string) => { 7389 if (err) { 7390 console.error(`Failed to get the ReceivingSurfaceId.code ${err.code},message is ${err.message}`); 7391 } else { 7392 console.info('Succeeded in getting the ReceivingSurfaceId.'); 7393 } 7394}); 7395``` 7396 7397### getReceivingSurfaceId<sup>9+</sup> 7398 7399getReceivingSurfaceId(): Promise\<string> 7400 7401用于获取一个surface id供Camera或其他组件使用。使用promise返回结果。 7402 7403**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7404 7405**返回值：** 7406 7407| 类型 | 说明 | 7408| ---------------- | -------------------- | 7409| Promise\<string> | Promise对象，返回surface id。 | 7410 7411**示例：** 7412 7413```ts 7414import { BusinessError } from '@kit.BasicServicesKit'; 7415 7416receiver.getReceivingSurfaceId().then((id: string) => { 7417 console.info('Succeeded in getting the ReceivingSurfaceId.'); 7418}).catch((error: BusinessError) => { 7419 console.error(`Failed to get the ReceivingSurfaceId.code ${error.code},message is ${error.message}`); 7420}) 7421``` 7422 7423### readLatestImage<sup>9+</sup> 7424 7425readLatestImage(callback: AsyncCallback\<Image>): void 7426 7427从ImageReceiver读取最新的图片，并使用callback返回结果。 7428 7429**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7430 7431**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7432 7433**参数：** 7434 7435| 参数名 | 类型 | 必填 | 说明 | 7436| -------- | ------------------------------- | ---- | ------------------------ | 7437| callback | AsyncCallback<[Image](#image9)> | 是 | 回调函数，当读取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 7438 7439**示例：** 7440 7441```ts 7442import { BusinessError } from '@kit.BasicServicesKit'; 7443 7444receiver.readLatestImage((err: BusinessError, img: image.Image) => { 7445 if (err) { 7446 console.error(`Failed to read the latest Image.code ${err.code},message is ${err.message}`); 7447 } else { 7448 console.info('Succeeded in reading the latest Image.'); 7449 } 7450}); 7451``` 7452 7453### readLatestImage<sup>9+</sup> 7454 7455readLatestImage(): Promise\<Image> 7456 7457从ImageReceiver读取最新的图片，并使用promise返回结果。 7458 7459**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7460 7461**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7462 7463**返回值：** 7464 7465| 类型 | 说明 | 7466| ------------------------- | ------------------ | 7467| Promise<[Image](#image9)> | Promise对象，返回最新图片。 | 7468 7469**示例：** 7470 7471```ts 7472import { BusinessError } from '@kit.BasicServicesKit'; 7473 7474receiver.readLatestImage().then((img: image.Image) => { 7475 console.info('Succeeded in reading the latest Image.'); 7476}).catch((error: BusinessError) => { 7477 console.error(`Failed to read the latest Image.code ${error.code},message is ${error.message}`); 7478}) 7479``` 7480 7481### readNextImage<sup>9+</sup> 7482 7483readNextImage(callback: AsyncCallback\<Image>): void 7484 7485从ImageReceiver读取下一张图片，并使用callback返回结果。 7486 7487**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7488 7489**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7490 7491**参数：** 7492 7493| 参数名 | 类型 | 必填 | 说明 | 7494| -------- | ------------------------------- | ---- | -------------------------- | 7495| callback | AsyncCallback<[Image](#image9)> | 是 | 回调函数，当获取下一张图片成功，err为undefined，data为获取到的下一张图片；否则为错误对象。 | 7496 7497**示例：** 7498 7499```ts 7500import { BusinessError } from '@kit.BasicServicesKit'; 7501 7502receiver.readNextImage((err: BusinessError, img: image.Image) => { 7503 if (err) { 7504 console.error(`Failed to read the next Image.code ${err.code},message is ${err.message}`); 7505 } else { 7506 console.info('Succeeded in reading the next Image.'); 7507 } 7508}); 7509``` 7510 7511### readNextImage<sup>9+</sup> 7512 7513readNextImage(): Promise\<Image> 7514 7515从ImageReceiver读取下一张图片，并使用promise返回结果。 7516 7517**注意**：此接口需要在[on](#on9)回调触发后调用，才能正常的接收到数据。且此接口返回的[Image](#image9)对象使用完毕后需要调用[release](#release9-4)方法释放，释放后才可以继续接收新的数据。 7518 7519**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7520 7521**返回值：** 7522 7523| 类型 | 说明 | 7524| ------------------------- | -------------------- | 7525| Promise<[Image](#image9)> | Promise对象，返回下一张图片。 | 7526 7527**示例：** 7528 7529```ts 7530import { BusinessError } from '@kit.BasicServicesKit'; 7531 7532receiver.readNextImage().then((img: image.Image) => { 7533 console.info('Succeeded in reading the next Image.'); 7534}).catch((error: BusinessError) => { 7535 console.error(`Failed to read the next Image.code ${error.code},message is ${error.message}`); 7536}) 7537``` 7538 7539### on<sup>9+</sup> 7540 7541on(type: 'imageArrival', callback: AsyncCallback\<void>): void 7542 7543接收图片时注册回调。 7544 7545**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7546 7547**参数：** 7548 7549| 参数名 | 类型 | 必填 | 说明 | 7550| -------- | -------------------- | ---- | ------------------------------------------------------ | 7551| type | string | 是 | 注册事件的类型，固定为'imageArrival'，接收图片时触发。 | 7552| callback | AsyncCallback\<void> | 是 | 回调函数，当注册事件触发成功，err为undefined，否则为错误对象。 | 7553 7554**示例：** 7555 7556```ts 7557receiver.on('imageArrival', () => { 7558 // image arrival, do something. 7559}) 7560``` 7561 7562### off<sup>13+</sup> 7563 7564off(type: 'imageArrival', callback?: AsyncCallback\<void>): void 7565 7566释放buffer时移除注册回调。 7567 7568**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7569 7570**参数：** 7571 7572| 参数名 | 类型 | 必填 | 说明 | 7573| -------- | -------------------- |----|----------------------------------------| 7574| type | string | 是 | 注册事件的类型，固定为'imageArrival'，释放buffer时触发。 | 7575| callback | AsyncCallback\<void> | 否 | 移除的回调函数。 | 7576 7577**示例：** 7578 7579```ts 7580let callbackFunc = ()=>{ 7581 // do something. 7582} 7583receiver.on('imageArrival', callbackFunc) 7584receiver.off('imageArrival', callbackFunc) 7585``` 7586 7587### release<sup>9+</sup> 7588 7589release(callback: AsyncCallback\<void>): void 7590 7591释放ImageReceiver实例并使用回调返回结果。 7592 7593ArkTS有内存回收机制，ImageReceiver对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7594 7595**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7596 7597**参数：** 7598 7599| 参数名 | 类型 | 必填 | 说明 | 7600| -------- | -------------------- | ---- | ------------------------ | 7601| callback | AsyncCallback\<void> | 是 | 回调函数，当释放ImageReceiver实例成功，err为undefined，否则为错误对象。 | 7602 7603**示例：** 7604 7605```ts 7606import { BusinessError } from '@kit.BasicServicesKit'; 7607 7608receiver.release((err: BusinessError) => { 7609 if (err) { 7610 console.error(`Failed to release the receiver.code ${err.code},message is ${err.message}`); 7611 } else { 7612 console.info('Succeeded in releasing the receiver.'); 7613 } 7614}) 7615``` 7616 7617### release<sup>9+</sup> 7618 7619release(): Promise\<void> 7620 7621释放ImageReceiver实例并使用promise返回结果。 7622 7623ArkTS有内存回收机制，ImageReceiver对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7624 7625**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 7626 7627**返回值：** 7628 7629| 类型 | 说明 | 7630| -------------- | ------------------ | 7631| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7632 7633**示例：** 7634 7635```ts 7636import { BusinessError } from '@kit.BasicServicesKit'; 7637 7638receiver.release().then(() => { 7639 console.info('Succeeded in releasing the receiver.'); 7640}).catch((error: BusinessError) => { 7641 console.error(`Failed to release the receiver.code ${error.code},message is ${error.message}`); 7642}) 7643``` 7644 7645## image.createImageCreator<sup>11+</sup> 7646 7647createImageCreator(size: Size, format: ImageFormat, capacity: number): ImageCreator 7648 7649通过图片大小、图片格式、容量创建ImageCreator实例。 7650 7651**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7652 7653**参数：** 7654 7655| 参数名 | 类型 | 必填 | 说明 | 7656| -------- | ------ | ---- | ---------------------- | 7657| size | [Size](#size) | 是 | 图像的默认大小。 | 7658| format | [ImageFormat](#imageformat9) | 是 | 图像格式，如YCBCR_422_SP，JPEG。 | 7659| capacity | number | 是 | 同时访问的最大图像数。 | 7660 7661**返回值：** 7662 7663| 类型 | 说明 | 7664| ------------------------------ | --------------------------------------- | 7665| [ImageCreator](#imagecreator9) | 如果操作成功，则返回ImageCreator实例。 | 7666 7667 7668**错误码：** 7669 7670以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 7671 7672| 错误码ID | 错误信息 | 7673| ------- | --------------------------------------------| 7674| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; | 7675 7676**示例：** 7677 7678```ts 7679let size: image.Size = { 7680 height: 8192, 7681 width: 8 7682} 7683let creator: image.ImageCreator = image.createImageCreator(size, image.ImageFormat.JPEG, 8); 7684``` 7685 7686## image.createImageCreator<sup>(deprecated)</sup> 7687 7688createImageCreator(width: number, height: number, format: number, capacity: number): ImageCreator 7689 7690通过宽、高、图片格式、容量创建ImageCreator实例。 7691 7692> **说明：** 7693> 7694> 从API version 11开始不再维护，建议使用[createImageCreator](#imagecreateimagecreator11)代替。 7695 7696**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7697 7698**参数：** 7699 7700| 参数名 | 类型 | 必填 | 说明 | 7701| -------- | ------ | ---- | ---------------------- | 7702| width | number | 是 | 图像的默认宽度。单位：像素。 | 7703| height | number | 是 | 图像的默认高度。单位：像素。 | 7704| format | number | 是 | 图像格式，如YCBCR_422_SP，JPEG。 | 7705| capacity | number | 是 | 同时访问的最大图像数。 | 7706 7707**返回值：** 7708 7709| 类型 | 说明 | 7710| ------------------------------ | --------------------------------------- | 7711| [ImageCreator](#imagecreator9) | 如果操作成功，则返回ImageCreator实例。 | 7712 7713**示例：** 7714 7715```ts 7716let creator: image.ImageCreator = image.createImageCreator(8192, 8, image.ImageFormat.JPEG, 8); 7717``` 7718 7719## ImageCreator<sup>9+</sup> 7720 7721图像创建模块，用于请求图像原生数据区域，并开放给应用编译原生图像数据的能力。 7722在调用以下方法前需要先创建[ImageCreator](#imagecreator9)实例，ImageCreator不支持多线程。 7723 7724### 属性 7725 7726**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7727 7728| 名称 | 类型 | 可读 | 可写 | 说明 | 7729| -------- | ---------------------------- | ---- | ---- | ------------------ | 7730| capacity | number | 是 | 否 | 同时访问的图像数。 | 7731| format | [ImageFormat](#imageformat9) | 是 | 否 | 图像格式。 | 7732 7733### dequeueImage<sup>9+</sup> 7734 7735dequeueImage(callback: AsyncCallback\<Image>): void 7736 7737从空闲队列中获取buffer图片，用于绘制UI内容，并使用callback返回结果。 7738 7739**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7740 7741**参数：** 7742 7743| 参数名 | 类型 | 必填 | 说明 | 7744| ------------- | ---------------------------------------| ---- | -------------------- | 7745| callback | AsyncCallback\<[Image](#image9)> | 是 | 回调函数，当获取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 7746 7747**示例：** 7748 7749```ts 7750import { BusinessError } from '@kit.BasicServicesKit'; 7751 7752creator.dequeueImage((err: BusinessError, img: image.Image) => { 7753 if (err) { 7754 console.error(`Failed to dequeue the Image.code ${err.code},message is ${err.message}`); 7755 } else { 7756 console.info('Succeeded in dequeuing the Image.'); 7757 } 7758}); 7759``` 7760 7761### dequeueImage<sup>9+</sup> 7762 7763dequeueImage(): Promise\<Image> 7764 7765从空闲队列中获取buffer图片，用于绘制UI内容，并使用promise返回结果。 7766 7767**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7768 7769**返回值：** 7770 7771| 类型 | 说明 | 7772| --------------- | ------------- | 7773| Promise\<[Image](#image9)> | Promise对象，返回最新图片。 | 7774 7775**示例：** 7776 7777```ts 7778import { BusinessError } from '@kit.BasicServicesKit'; 7779 7780creator.dequeueImage().then((img: image.Image) => { 7781 console.info('Succeeded in dequeuing the Image.'); 7782}).catch((error: BusinessError) => { 7783 console.error(`Failed to dequeue the Image.code ${error.code},message is ${error.message}`); 7784}) 7785``` 7786 7787### queueImage<sup>9+</sup> 7788 7789queueImage(interface: Image, callback: AsyncCallback\<void>): void 7790 7791将绘制好的图片放入队列，并使用callback返回结果。 7792 7793**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7794 7795**参数：** 7796 7797| 参数名 | 类型 | 必填 | 说明 | 7798| ------------- | -------------------------| ---- | -------------------- | 7799| interface | [Image](#image9) | 是 | 绘制好的buffer图像。 | 7800| callback | AsyncCallback\<void> | 是 | 回调函数，当将图片放入队列成功，err为undefined，否则为错误对象。 | 7801 7802**示例：** 7803 7804```ts 7805import { BusinessError } from '@kit.BasicServicesKit'; 7806 7807creator.dequeueImage().then((img: image.Image) => { 7808 //绘制图片。 7809 img.getComponent(4).then((component : image.Component) => { 7810 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 7811 for (let i = 0; i < bufferArr.length; i += 4) { 7812 bufferArr[i] = 0; //B 7813 bufferArr[i + 1] = 0; //G 7814 bufferArr[i + 2] = 255; //R 7815 bufferArr[i + 3] = 255; //A 7816 } 7817 }) 7818 creator.queueImage(img, (err: BusinessError) => { 7819 if (err) { 7820 console.error(`Failed to queue the Image.code ${err.code},message is ${err.message}`); 7821 } else { 7822 console.info('Succeeded in queuing the Image.'); 7823 } 7824 }) 7825}) 7826 7827``` 7828 7829### queueImage<sup>9+</sup> 7830 7831queueImage(interface: Image): Promise\<void> 7832 7833将绘制好的图片放入队列，并使用promise返回结果。 7834 7835**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7836 7837**参数：** 7838 7839| 参数名 | 类型 | 必填 | 说明 | 7840| ------------- | --------| ---- | ------------------- | 7841| interface | [Image](#image9) | 是 | 绘制好的buffer图像。 | 7842 7843**返回值：** 7844 7845| 类型 | 说明 | 7846| -------------- | ------------- | 7847| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7848 7849**示例：** 7850 7851```ts 7852import { BusinessError } from '@kit.BasicServicesKit'; 7853 7854creator.dequeueImage().then((img: image.Image) => { 7855 //绘制图片。 7856 img.getComponent(4).then((component: image.Component) => { 7857 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 7858 for (let i = 0; i < bufferArr.length; i += 4) { 7859 bufferArr[i] = 0; //B 7860 bufferArr[i + 1] = 0; //G 7861 bufferArr[i + 2] = 255; //R 7862 bufferArr[i + 3] = 255; //A 7863 } 7864 }) 7865 creator.queueImage(img).then(() => { 7866 console.info('Succeeded in queuing the Image.'); 7867 }).catch((error: BusinessError) => { 7868 console.error(`Failed to queue the Image.code ${error.code},message is ${error.message}`); 7869 }) 7870}) 7871 7872``` 7873 7874### on<sup>9+</sup> 7875 7876on(type: 'imageRelease', callback: AsyncCallback\<void>): void 7877 7878监听imageRelease事件，并使用callback返回结果。 7879 7880**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7881 7882**参数：** 7883 7884| 参数名 | 类型 | 必填 | 说明 | 7885| ------------- | -------------------------| ---- | -------------------- | 7886| type | string | 是 | 监听事件类型，如'imageRelease'。 | 7887| callback | AsyncCallback\<void> | 是 | 回调函数，当监听事件触发成功，err为undefined，否则为错误对象。 | 7888 7889**示例：** 7890 7891```ts 7892import { BusinessError } from '@kit.BasicServicesKit'; 7893 7894creator.on('imageRelease', (err: BusinessError) => { 7895 if (err) { 7896 console.error(`Failed to get the imageRelease callback.code ${err.code},message is ${err.message}`); 7897 } else { 7898 console.info('Succeeded in getting imageRelease callback.'); 7899 } 7900}) 7901``` 7902 7903### off<sup>13+</sup> 7904 7905off(type: 'imageRelease', callback?: AsyncCallback\<void>): void 7906 7907释放buffer时，移除注册的回调函数。 7908 7909**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7910 7911**参数：** 7912 7913| 参数名 | 类型 | 必填 | 说明 | 7914| ------------- | -------------------------|----|--------------------------------------------| 7915| type | string | 是 | 监听事件类型，如'imageRelease'。 | 7916| callback | AsyncCallback\<void> | 否 | 将被移除的回调函数。 | 7917 7918**示例：** 7919 7920```ts 7921let callbackFunc = ()=>{ 7922 // do something. 7923} 7924creator.on('imageRelease', callbackFunc) 7925creator.off('imageRelease', callbackFunc) 7926``` 7927 7928### release<sup>9+</sup> 7929 7930release(callback: AsyncCallback\<void>): void 7931 7932释放当前图像，并使用callback返回结果。 7933 7934ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7935 7936**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7937 7938**参数：** 7939 7940| 参数名 | 类型 | 必填 | 说明 | 7941| ------------- | -------------------------| ---- | -------------------- | 7942| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 7943 7944**示例：** 7945 7946```ts 7947import { BusinessError } from '@kit.BasicServicesKit'; 7948 7949creator.release((err: BusinessError) => { 7950 if (err) { 7951 console.error(`Failed to release the creator.code ${err.code},message is ${err.message}`); 7952 } else { 7953 console.info('Succeeded in releasing creator.'); 7954 } 7955}); 7956``` 7957### release<sup>9+</sup> 7958 7959release(): Promise\<void> 7960 7961释放当前图像，并使用promise返回结果。 7962 7963ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 7964 7965**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 7966 7967**返回值：** 7968 7969| 类型 | 说明 | 7970| -------------- | ------------- | 7971| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 7972 7973**示例：** 7974 7975```ts 7976import { BusinessError } from '@kit.BasicServicesKit'; 7977 7978creator.release().then(() => { 7979 console.info('Succeeded in releasing creator.'); 7980}).catch((error: BusinessError) => { 7981 console.error(`Failed to release the creator.code ${error.code},message is ${error.message}`); 7982}) 7983``` 7984 7985## Image<sup>9+</sup> 7986 7987提供基本的图像操作，包括获取图像信息、读写图像数据。调用[readNextImage](#readnextimage9)和[readLatestImage](#readlatestimage9)接口时会返回image。 7988 7989### 属性 7990 7991**系统能力：** SystemCapability.Multimedia.Image.Core 7992 7993| 名称 | 类型 | 可读 | 可写 | 说明 | 7994| -------- | ------------------ | ---- | ---- | -------------------------------------------------- | 7995| clipRect | [Region](#region8) | 是 | 是 | 要裁剪的图像区域。 | 7996| 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)。 | 7997| format | number | 是 | 否 | 图像格式，参考[OH_NativeBuffer_Format](../apis-arkgraphics2d/_o_h___native_buffer.md#oh_nativebuffer_format)。 | 7998| timestamp<sup>12+</sup> | number | 是 | 否 | 图像时间戳。时间戳以纳秒为单位，通常是单调递增的。时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。如果要获取某张照片的生成时间，可以通过[getImageProperty](#getimageproperty11)接口读取相关的EXIF信息。| 7999 8000### getComponent<sup>9+</sup> 8001 8002getComponent(componentType: ComponentType, callback: AsyncCallback\<Component>): void 8003 8004根据图像的组件类型从图像中获取组件缓存并使用callback返回结果。 8005 8006**系统能力：** SystemCapability.Multimedia.Image.Core 8007 8008**参数：** 8009 8010| 参数名 | 类型 | 必填 | 说明 | 8011| ------------- | --------------------------------------- | ---- | -------------------- | 8012| componentType | [ComponentType](#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机） | 8013| callback | AsyncCallback<[Component](#component9)> | 是 | 回调函数，当返回组件缓冲区成功，err为undefined，data为获取到的组件缓冲区；否则为错误对象。 | 8014 8015**示例：** 8016 8017```ts 8018import { BusinessError } from '@kit.BasicServicesKit'; 8019 8020img.getComponent(4, (err: BusinessError, component: image.Component) => { 8021 if (err) { 8022 console.error(`Failed to get the component.code ${err.code},message is ${err.message}`); 8023 } else { 8024 console.info('Succeeded in getting component.'); 8025 } 8026}) 8027``` 8028 8029### getComponent<sup>9+</sup> 8030 8031getComponent(componentType: ComponentType): Promise\<Component> 8032 8033根据图像的组件类型从图像中获取组件缓存并使用Promise方式返回结果。 8034 8035**系统能力：** SystemCapability.Multimedia.Image.Core 8036 8037**参数：** 8038 8039| 参数名 | 类型 | 必填 | 说明 | 8040| ------------- | -------------------------------- | ---- | ---------------- | 8041| componentType | [ComponentType](#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机） | 8042 8043**返回值：** 8044 8045| 类型 | 说明 | 8046| --------------------------------- | --------------------------------- | 8047| Promise<[Component](#component9)> | Promise对象，返回组件缓冲区。 | 8048 8049**示例：** 8050 8051```ts 8052import { BusinessError } from '@kit.BasicServicesKit'; 8053 8054img.getComponent(4).then((component: image.Component) => { 8055 console.info('Succeeded in getting component.'); 8056}).catch((error: BusinessError) => { 8057 console.error(`Failed to get the component.code ${error.code},message is ${error.message}`); 8058}) 8059``` 8060 8061### release<sup>9+</sup> 8062 8063release(callback: AsyncCallback\<void>): void 8064 8065释放当前图像并使用callback返回结果。 8066 8067在接收另一个图像前必须先释放对应资源。 8068 8069ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 8070 8071**系统能力：** SystemCapability.Multimedia.Image.Core 8072 8073**参数：** 8074 8075| 参数名 | 类型 | 必填 | 说明 | 8076| -------- | -------------------- | ---- | -------------- | 8077| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 8078 8079**示例：** 8080 8081```ts 8082import { BusinessError } from '@kit.BasicServicesKit'; 8083 8084img.release((err: BusinessError) => { 8085 if (err) { 8086 console.error(`Failed to release the image instance.code ${err.code},message is ${err.message}`); 8087 } else { 8088 console.info('Succeeded in releasing the image instance.'); 8089 } 8090}) 8091``` 8092 8093### release<sup>9+</sup> 8094 8095release(): Promise\<void> 8096 8097释放当前图像并使用Promise方式返回结果。 8098 8099在接收另一个图像前必须先释放对应资源。 8100 8101ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 8102 8103**系统能力：** SystemCapability.Multimedia.Image.Core 8104 8105**返回值：** 8106 8107| 类型 | 说明 | 8108| -------------- | --------------------- | 8109| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 8110 8111**示例：** 8112 8113```ts 8114import { BusinessError } from '@kit.BasicServicesKit'; 8115 8116img.release().then(() => { 8117 console.info('Succeeded in releasing the image instance.'); 8118}).catch((error: BusinessError) => { 8119 console.error(`Failed to release the image instance.code ${error.code},message is ${error.message}`); 8120}) 8121``` 8122 8123## PositionArea<sup>7+</sup> 8124 8125表示图片指定区域内的数据。 8126 8127**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8128 8129**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8130 8131**系统能力：** SystemCapability.Multimedia.Image.Core 8132 8133| 名称 | 类型 | 只读| 可选| 说明 | 8134| ------ | ------------------ | ---| -----|------------------------------------------------------- | 8135| pixels | ArrayBuffer | 否 | 否 | 像素。仅支持BGRA_8888格式的图像像素数据。 | 8136| offset | number | 否 | 否 | 偏移量。单位：字节。 | 8137| stride | number | 否 | 否 | 跨距，内存中每行像素所占的空间。stride >= region.size.width*4。 | 8138| region | [Region](#region8) | 否 | 否 |区域，按照区域读写。写入的区域宽度加X坐标不能大于原图的宽度，写入的区域高度加Y坐标不能大于原图的高度。 | 8139 8140## ImageInfo 8141 8142表示图片信息。 8143 8144**系统能力：** SystemCapability.Multimedia.Image.Core 8145 8146| 名称 | 类型 | 只读 | 可选 | 说明 | 8147| ---- | ------------- | --- |-----|---------- | 8148| size<sup>6+</sup> | [Size](#size) | 否 | 否 |图片大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8149| density<sup>9+</sup> | number | 否 | 否 |像素密度，单位为ppi。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8150| stride<sup>11+</sup> | number | 否 | 否 | 跨距，内存中每行像素所占的空间。stride >= region.size.width*4 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8151| pixelFormat<sup>12+</sup> | [PixelMapFormat](#pixelmapformat7) | 否 | 否 | 像素格式。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8152| alphaType<sup>12+</sup> | [AlphaType](#alphatype9) | 否 | 否 |透明度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8153| mimeType<sup>12+</sup> | string | 否 | 否 |图片真实格式（MIME type）。 | 8154| isHdr<sup>12+</sup> | boolean | 否 | 否 | true表示图片为高动态范围（HDR），false表示图片非高动态范围（SDR）。对于[ImageSource](#imagesource)，代表源图片是否为HDR；对于[PixelMap](#pixelmap7)，代表解码后的pixelmap是否为HDR。 | 8155 8156## Size 8157 8158表示图片尺寸。 8159 8160**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8161 8162**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8163 8164**系统能力：** SystemCapability.Multimedia.Image.Core 8165 8166| 名称 | 类型 | 只读 | 可选 |说明 | 8167| ------ | ------ | -- |-----| -------------- | 8168| height | number | 否 | 否 |输出图片的高，单位：像素。 | 8169| width | number | 否 | 否 | 输出图片的宽，单位：像素。 | 8170 8171## PixelMapFormat<sup>7+</sup> 8172 8173枚举，图片像素格式。 8174 8175**系统能力：** SystemCapability.Multimedia.Image.Core 8176 8177| 名称 | 值 | 说明 | 8178| ---------------------- | ------ | ----------------- | 8179| UNKNOWN | 0 | 未知格式。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8180| ARGB_8888<sup>18+</sup> | 1 | 颜色信息由透明度（Alpha）与R（Red），G（Green），B（Blue）四部分组成，每个部分占8位，总共占32位。 该格式当前仅支持PixelMap的接口。| 8181| 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卡片中使用。 | 8182| RGBA_8888 | 3 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，每个部分占8位，总共占32位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8183| 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卡片中使用。 | 8184| RGB_888<sup>9+</sup> | 5 | 颜色信息由R（Red），G（Green），B（Blue）三部分组成，每个部分占8位，总共占24位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8185| ALPHA_8<sup>9+</sup> | 6 | 颜色信息仅包含透明度（Alpha），每个像素占8位。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8186| 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卡片中使用。 | 8187| 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卡片中使用。 | 8188| 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卡片中使用。 | 8189| RGBA_1010102<sup>12+</sup> | 10 | 颜色信息由R（Red），G（Green），B（Blue）与透明度（Alpha）四部分组成，其中R、G、B分别占10位，透明度占2位，总共占32位。 | 8190| YCBCR_P010<sup>12+</sup> | 11 | 颜色信息由亮度分量Y和色度分量Cb与Cr组成，每个分量有效10位，实际存储时，Y平面每个像素占16位数据（10位有效），UV平面交错排列，每4个像素占32位数据（每色度分量10位有效），平均有效占15位。 8191| YCRCB_P010<sup>12+</sup> | 12 | 颜色信息由亮度分量Y和色度分量Cr与Cb组成，每个分量有效10位，实际存储时，Y平面每个像素占16位数据（10位有效），UV平面交错排列，每4个像素占32位数据（每色度分量10位有效），平均有效占15位。 | 8192| ASTC_4x4<sup>18+</sup> | 102 | 存储格式为 ASTC 4x4 格式，内存使用量仅为 RGBA_8888 的 1/4。该格式仅用于直接显示场景，不支持像素访问或后期处理编辑。 | 8193 8194## AlphaType<sup>9+</sup> 8195 8196枚举，图像的透明度类型。 8197 8198**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8199 8200**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8201 8202**系统能力：** SystemCapability.Multimedia.Image.Core 8203 8204| 名称 | 值 | 说明 | 8205| -------- | ------ | ----------------------- | 8206| UNKNOWN | 0 | 未知透明度。 | 8207| OPAQUE | 1 | 没有alpha或图片不透明。 | 8208| PREMUL | 2 | RGB预乘alpha。 | 8209| UNPREMUL | 3 | RGB非预乘alpha。 | 8210 8211## AuxiliaryPictureType<sup>13+</sup> 8212 8213枚举，辅助图的图像类型。 8214 8215**系统能力：** SystemCapability.Multimedia.Image.Core 8216 8217| 名称 | 值 | 说明 | 8218| ------------- | ---- | ------------ | 8219| GAINMAP | 1 | 增益图，代表了一种增强SDR图像以产生具有可变显示调整能力的HDR图像的机制。它是一组描述如何应用gainmap元数据的组合。 | 8220| DEPTH_MAP | 2 | 深度图，储存图像的深度数据，通过捕捉每个像素与摄像机之间的距离，提供场景的三维结构信息，通常用于3D重建和场景理解。 | 8221| UNREFOCUS_MAP | 3 | 人像未对焦的原图，提供了一种在人像拍摄中突出背景模糊效果的方式，能够帮助用户在后期处理中选择焦点区域，增加创作自由度。 | 8222| LINEAR_MAP | 4 | 线性图，用于提供额外的数据视角或补充信息，通常用于视觉效果的增强，它可以包含场景中光照、颜色或其他视觉元素的线性表示。 | 8223| FRAGMENT_MAP | 5 | 水印裁剪图，表示在原图中被水印覆盖的区域，该图像用于修复或移除水印影响，恢复图像的完整性和可视性。 | 8224 8225## AuxiliaryPictureInfo<sup>13+</sup> 8226 8227表示辅助图图像信息。 8228 8229**系统能力：** SystemCapability.Multimedia.Image.Core 8230 8231| 名称 | 类型 | 只读 | 可选 | 说明 | 8232| ------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 8233| auxiliaryPictureType | [AuxiliaryPictureType](#auxiliarypicturetype13) | 否 | 否 | 辅助图的图像类型。 | 8234| size | [Size](#size) | 否 | 否 | 图片大小。 | 8235| rowStride | number | 否 | 否 | 行距。 | 8236| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 否 | 像素格式。 | 8237| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 否 | 否 | 目标色彩空间。 | 8238 8239## MetadataType<sup>13+</sup> 8240 8241枚举，图片元数据类型。 8242 8243**系统能力：** SystemCapability.Multimedia.Image.Core 8244 8245| 名称 | 值 | 说明 | 8246| ----------------- | ---- | ------------------ | 8247| EXIF_METADATA | 1 | exif数据。 | 8248| FRAGMENT_METADATA | 2 | 水印裁剪图元数据。 | 8249 8250## ScaleMode<sup>9+</sup> 8251 8252枚举，图像的缩放模式。 8253 8254**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8255 8256**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8257 8258**系统能力：** SystemCapability.Multimedia.Image.Core 8259 8260| 名称 | 值 | 说明 | 8261| --------------- | ------ | -------------------------------------------------- | 8262| CENTER_CROP | 1 | 缩放图像以填充目标图像区域并居中裁剪区域外的效果。 | 8263| FIT_TARGET_SIZE | 0 | 图像适合目标尺寸的效果。 | 8264 8265## SourceOptions<sup>9+</sup> 8266 8267ImageSource的初始化选项。 8268 8269**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8270 8271**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8272 8273**系统能力：** SystemCapability.Multimedia.Image.Core 8274 8275| 名称 | 类型 | 只读 | 可选 | 说明 | 8276| ----------------- | ---------------------------------- | ---- | ---- | ------------------ | 8277| sourceDensity | number | 否 | 否 | 图片资源像素密度，单位为ppi。<br>在解码参数[DecodingOptions](#decodingoptions7)未设置desiredSize的前提下，当前参数SourceOptions.sourceDensity与DecodingOptions.fitDensity非零时将对解码输出的pixelmap进行缩放。<br>缩放后宽计算公式如下(高同理)：(width * fitDensity + (sourceDensity >> 1)) / sourceDensity。| 8278| sourcePixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 图片像素格式，默认值为UNKNOWN。 | 8279| sourceSize | [Size](#size) | 否 | 是 | 图像像素大小，默认值为空。 | 8280 8281 8282## InitializationOptions<sup>8+</sup> 8283 8284PixelMap的初始化选项。 8285 8286**系统能力：** SystemCapability.Multimedia.Image.Core 8287 8288| 名称 | 类型 | 只读 |可选 | 说明 | 8289| ------------------------ | ---------------------------------- | ----| -----| -------------- | 8290| alphaType<sup>9+</sup> | [AlphaType](#alphatype9) | 否 | 是| 透明度。默认值为IMAGE_ALPHA_TYPE_PREMUL。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8291| editable | boolean | 否 | 是| true表示可编辑，false表示不可编辑。默认值为false。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。| 8292| srcPixelFormat<sup>12+</sup> | [PixelMapFormat](#pixelmapformat7) | 否 | 是 | 传入的buffer数据的像素格式。默认值为BGRA_8888。| 8293| pixelFormat | [PixelMapFormat](#pixelmapformat7) | 否 | 是| 生成的pixelMap的像素格式。默认值为RGBA_8888。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8294| scaleMode<sup>9+</sup> | [ScaleMode](#scalemode9) | 否 | 是 | 缩略值。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8295| size | [Size](#size) | 否 | 否|创建图片大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8296 8297## DecodingOptions<sup>7+</sup> 8298 8299图像解码设置选项。 8300 8301**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8302 8303| 名称 | 类型 | 只读 | 可选 | 说明 | 8304| ------------------ | ---------------------------------- | ---- | ---- | ---------------- | 8305| sampleSize | number | 否 | 是 | 缩略图采样大小，默认值为1。当前只能取1。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8306| rotate | number | 否 | 是 | 旋转角度。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8307| editable | boolean | 否 | 是 | true表示可编辑，false表示不可编辑。默认值为false。当取值为false时，图片不可二次编辑，如writepixels操作将失败。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8308| desiredSize | [Size](#size) | 否 | 是 | 期望输出大小，必须为正整数，若与原尺寸比例不一致，则会进行拉伸/缩放到指定尺寸，默认为原始尺寸。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8309| desiredRegion | [Region](#region8) | 否 | 是 | 解码图像中由Region指定的矩形区域，当原始图像很大而只需要解码图像的一部分时，可以设置该参数，有助于提升性能，默认为原始大小。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8310| 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卡片中使用。 | 8311| index | number | 否 | 是 | 解码图片序号。默认值为0，表示第一张图片。当取值为N时，表示第N-1张图片。单帧图片场景中取值只能为0，动图等多帧图片场景中取值范围为：0~（帧数-1）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8312| fitDensity<sup>9+</sup> | number | 否 | 是 | 图像像素密度，单位为ppi。默认值为0。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 8313| desiredColorSpace<sup>11+</sup> | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 否 | 是 | 目标色彩空间。默认值为UNKNOWN。 | 8314| desiredDynamicRange<sup>12+</sup> | [DecodingDynamicRange](#decodingdynamicrange12) | 否 | 是 | 目标动态范围，默认值为SDR。<br>通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource不支持设置此属性，默认解码为SDR内容。<br>如果平台不支持HDR，设置无效，默认解码为SDR内容。 | 8315| cropAndScaleStrategy<sup>18+</sup> | [CropAndScaleStrategy](#cropandscalestrategy18) | 否 | 是 | 解码参数如果同时设置desiredRegion与desiredSize，由此决定裁剪与缩放操作的先后策略。<br>仅支持设置：SCALE_FIRST、CROP_FIRST。 | 8316 8317## DecodingOptionsForPicture<sup>13+</sup> 8318 8319图像解码设置选项。 8320 8321**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8322 8323| 名称 | 类型 | 只读 | 可选 | 说明 | 8324| ------------------------ | ------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | 8325| desiredAuxiliaryPictures | Array\<[AuxiliaryPictureType](#auxiliarypicturetype13)> | 否 | 否 | 设置AuxiliaryPicture类型，默认解码所有AuxiliaryPicture类型。 | 8326 8327## Region<sup>8+</sup> 8328 8329表示区域信息。 8330 8331**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 8332 8333**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 8334 8335**系统能力：** SystemCapability.Multimedia.Image.Core 8336 8337| 名称 | 类型 | 只读 | 可选| 说明 | 8338| ---- | ------------- | ---- | ---- | ------------ | 8339| size<sup>7+</sup> | [Size](#size) | 否 | 否 | 区域大小。 | 8340| x<sup>7+</sup> | number | 否 | 否 | 区域左上角横坐标。单位：像素。 | 8341| y<sup>7+</sup> | number | 否 | 否 | 区域左上角纵坐标。单位：像素。 | 8342 8343## PackingOption 8344 8345表示图片编码选项。 8346 8347**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 8348 8349| 名称 | 类型 | 只读 | 可选 | 说明 | 8350| ------- | ------ | ---- | ---- | --------------------------------------------------- | 8351| format | string | 否 | 否 | 目标格式。</br>当前只支持"image/jpeg"、"image/webp"、"image/png"和"image/heic(或者image/heif)"<sup>12+</sup>（不同硬件设备支持情况不同）。<br>**说明：** 因为jpeg不支持透明通道，若使用带透明通道的数据编码jpeg格式，透明色将变为黑色。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8352| quality | number | 否 | 否 | 编码中设定输出图片质量的参数，该参数仅对JPEG图片和HEIF图片生效。取值范围为0-100。0质量最低，100质量最高，质量越高生成图片所占空间越大。WebP、PNG等图片均为无损编码。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8353| bufferSize<sup>9+</sup> | number | 否 | 是 | 接收编码数据的缓冲区大小，单位为Byte。如果不设置大小，默认为25M。如果编码图片超过25M，需要指定大小。bufferSize需大于编码后图片大小。使用[packToFile](#packtofile11)不受此参数限制。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 8354| desiredDynamicRange<sup>12+</sup> | [PackingDynamicRange](#packingdynamicrange12) | 否 | 是 | 目标动态范围。默认值为SDR。 | 8355| needsPackProperties<sup>12+</sup> | boolean | 否 | 是 | 是否需要编码图片属性信息，例如EXIF。true表示需要，false表示不需要。默认值为false。 | 8356 8357## PackingOptionsForSequence<sup>18+</sup> 8358 8359描述动图编码参数的选项。 8360 8361**系统能力：** SystemCapability.Multimedia.Image.ImagePacker 8362 8363| 名称 | 类型 | 只读 | 可选 | 说明 | 8364| ------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 8365| frameCount | number | 否 | 否 | GIF编码中指定的帧数。 | 8366| delayTimeList | Array\<number> | 否 | 否 | GIF编码中设定每帧输出图像的延迟时间，取值需大于0。<br>- 单位为10毫秒。例如，取值为10时，实际单帧延迟是100毫秒。<br>- 如果长度小于frameCount，不足的部分将使用delayTimeList中的最后一个值进行填充。 | 8367| disposalTypes | Array\<number> | 否 | 是 | GIF编码中设定每帧输出图像的帧过渡模式，如果长度小于frameCount，不足的部分将使用disposalTypes中的最后一个值进行填充，可取值如下：<br>- 0：不需要任何操作。<br>- 1：保持图形不变。<br>- 2：恢复背景色。<br>- 3：恢复到之前的状态。 | 8368| loopCount | number | 否 | 是 | 表示在GIF编码中输出图片循环播放次数，取值范围为[0，65535]。<br>0表示无限循环；若无此字段，则表示不循环播放。 | 8369 8370## ImagePropertyOptions<sup>11+</sup> 8371 8372表示查询图片属性的索引。 8373 8374**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8375 8376| 名称 | 类型 | 只读 | 可选 | 说明 | 8377| ------------ | ------ | ---- | ---- | ------------ | 8378| index | number | 是 | 是 | 图片序号。默认值为0。 | 8379| defaultValue | string | 是 | 是 | 默认属性值。默认值为空。 | 8380 8381## GetImagePropertyOptions<sup>(deprecated)</sup> 8382 8383表示查询图片属性的索引。 8384 8385> **说明：** 8386> 8387> 从API version 11开始不再维护，建议使用[ImagePropertyOptions](#imagepropertyoptions11)代替。 8388 8389**系统能力：** SystemCapability.Multimedia.Image.ImageSource 8390 8391| 名称 | 类型 | 只读 | 可选 | 说明 | 8392| ------------ | ------ | ---- | ---- | ------------ | 8393| index | number | 否 | 是 | 图片序号。默认值为0。 | 8394| defaultValue | string | 否 | 是 | 默认属性值。默认值为空。 | 8395 8396## PropertyKey<sup>7+</sup> 8397 8398枚举，Exif（Exchangeable image file format）图片信息。 8399 8400**系统能力：** SystemCapability.Multimedia.Image.Core 8401 8402| 名称 | 值 | 说明 | 8403| ----------------- | ----------------------- |---------------------------| 8404| NEW_SUBFILE_TYPE <sup>12+</sup> | "NewSubfileType" | **读写能力：** 可读写<br> 在Exif中，"NewSubfileType"字段用于标识子文件的数据类型，如全分辨率图像、缩略图或多帧图像的一部分。其值是位掩码，0代表全分辨率图像，1代表缩略图，2代表多帧图像的一部分。| 8405| SUBFILE_TYPE <sup>12+</sup> | "SubfileType" | **读写能力：** 可读写<br> 此标签指示此子文件中的数据类型。标签已弃用，请使用NewSubfileType替代。| 8406| IMAGE_WIDTH | "ImageWidth" | **读写能力：** 可读写<br> 图片宽度。| 8407| IMAGE_LENGTH | "ImageLength" | **读写能力：** 可读写<br> 图片长度。| 8408| BITS_PER_SAMPLE | "BitsPerSample" | **读写能力：** 可读写<br> 像素各分量的位数，如RGB，3分量，格式是8, 8, 8。| 8409| COMPRESSION <sup>12+</sup> | "Compression" | **读写能力：** 可读写<br> 图像压缩方案。| 8410| PHOTOMETRIC_INTERPRETATION <sup>12+</sup> | "PhotometricInterpretation" | **读写能力：** 可读写<br> 像素构成，例如 RGB 或 YCbCr。| 8411| IMAGE_DESCRIPTION<sup>10+</sup> | "ImageDescription" | **读写能力：** 可读写<br> 图像信息描述。| 8412| MAKE<sup>10+</sup> | "Make" | **读写能力：** 可读写<br> 生产商。| 8413| MODEL<sup>10+</sup> | "Model" | **读写能力：** 可读写<br> 设备型号。| 8414| STRIP_OFFSETS <sup>12+</sup> | "StripOffsets" | **读写能力：** 可读写<br> 每个strip的字节偏移量。| 8415| ORIENTATION | "Orientation" | **读写能力：** 可读写<br> 图片方向。<br/> 1："Top-left"，图像未旋转。<br/> 2："Top-right"，镜像水平翻转。<br/> 3："Bottom-right"，图像旋转180°。<br/> 4："Bottom-left"，镜像垂直翻转。<br/> 5："Left-top"，镜像水平翻转再顺时针旋转270°。<br/> 6："Right-top"，顺时针旋转90°。<br/> 7："Right-bottom"，镜像水平翻转再顺时针旋转90°。<br/> 8："Left-bottom"，顺时针旋转270°。<br/> 如果读到未定义值会返回"Unknown Value 0"。获取该属性时会以字符串的形式返回。修改该属性时既可以以数字形式指定，也可以以字符串形式指定。| 8416| SAMPLES_PER_PIXEL <sup>12+</sup> | "SamplesPerPixel" | **读写能力：** 可读写<br> 每个像素的分量数。由于该标准适用于 RGB 和 YCbCr 图像，因此该标签的值设置为 3。在 JPEG 压缩数据中，使用 JPEG 标记代替该标签。| 8417| ROWS_PER_STRIP <sup>12+</sup> | "RowsPerStrip" | **读写能力：** 可读写<br> 每个strip的图像数据行数。| 8418| STRIP_BYTE_COUNTS <sup>12+</sup> | "StripByteCounts" | **读写能力：** 可读写<br> 每个图像数据带的总字节数。| 8419| X_RESOLUTION <sup>12+</sup> | "XResolution" | **读写能力：** 可读写<br> 图像宽度方向的分辨率。| 8420| Y_RESOLUTION <sup>12+</sup> | "YResolution" | **读写能力：** 可读写<br> 图像高度方向的分辨率。| 8421| PLANAR_CONFIGURATION <sup>12+</sup> | "PlanarConfiguration" | **读写能力：** 可读写<br> 表示像素组件的记录格式，chunky格式或是planar格式。| 8422| RESOLUTION_UNIT <sup>12+</sup> | "ResolutionUnit" | **读写能力：** 可读写<br> 用于测量XResolution和YResolution的单位。| 8423| TRANSFER_FUNCTION <sup>12+</sup> | "TransferFunction" | **读写能力：** 可读写<br> 图像的传递函数，通常用于颜色校正。| 8424| SOFTWARE <sup>12+</sup> | "Software" | **读写能力：** 可读写<br> 用于生成图像的软件的名称和版本。| 8425| DATE_TIME<sup>10+</sup> | "DateTime" | **读写能力：** 可读写<br> 日期时间。格式如2024:01:25 05:51:34。| 8426| ARTIST <sup>12+</sup> | "Artist" | **读写能力：** 可读写<br> 创建图像的用户名称。| 8427| WHITE_POINT <sup>12+</sup> | "WhitePoint" | **读写能力：** 可读写<br> 图像的白点色度。| 8428| PRIMARY_CHROMATICITIES <sup>12+</sup> | "PrimaryChromaticities" | **读写能力：** 可读写<br> 图像的主要颜色的色度。| 8429| PHOTO_MODE<sup>10+</sup> | "PhotoMode" | **读写能力：** 可读写<br> 拍照模式。| 8430| JPEG_INTERCHANGE_FORMAT <sup>12+</sup> | "JPEGInterchangeFormat" | **读写能力：** 可读写<br> JPEG压缩缩略图数据开始字节（SOI）的偏移。| 8431| JPEG_INTERCHANGE_FORMAT_LENGTH <sup>12+</sup> | "JPEGInterchangeFormatLength" | **读写能力：** 可读写<br> JPEG压缩缩略图数据的字节数。| 8432| YCBCR_COEFFICIENTS <sup>12+</sup> | "YCbCrCoefficients" | **读写能力：** 可读写<br> 从RGB到YCbCr图像数据的转换矩阵系数。| 8433| YCBCR_SUB_SAMPLING <sup>12+</sup> | "YCbCrSubSampling" | **读写能力：** 可读写<br> 色度分量与亮度分量的采样比率。| 8434| YCBCR_POSITIONING <sup>12+</sup> | "YCbCrPositioning" | **读写能力：** 可读写<br> 色度分量相对于亮度分量的位置。| 8435| REFERENCE_BLACK_WHITE <sup>12+</sup> | "ReferenceBlackWhite" | **读写能力：** 可读写<br> 参考黑点值和参考白点值。| 8436| COPYRIGHT <sup>12+</sup> | "Copyright" | **读写能力：** 可读写<br> 图像的版权信息。| 8437| EXPOSURE_TIME<sup>9+</sup> | "ExposureTime" | **读写能力：** 可读写<br> 曝光时间，例如1/33 sec。| 8438| F_NUMBER<sup>9+</sup> | "FNumber" | **读写能力：** 可读写<br> 光圈值，例如f/1.8。| 8439| EXPOSURE_PROGRAM <sup>12+</sup> | "ExposureProgram" | **读写能力：** 可读写<br> 拍照时相机用来设置曝光的程序的类别。| 8440| SPECTRAL_SENSITIVITY <sup>12+</sup> | "SpectralSensitivity" | **读写能力：** 可读写<br> 表示所用相机的每个通道的光谱灵敏度。| 8441| GPS_VERSION_ID <sup>12+</sup> | "GPSVersionID" | **读写能力：** 可读写<br> GPSInfoIFD的版本。| 8442| GPS_LATITUDE_REF | "GPSLatitudeRef" | **读写能力：** 可读写<br> 纬度引用，例如N或S。| 8443| GPS_LATITUDE | "GPSLatitude" | **读写能力：** 可读写<br> 图片纬度。修改时应按"度,分,秒"格式传入，如"39,54,7.542"| 8444| GPS_LONGITUDE_REF | "GPSLongitudeRef" | **读写能力：** 可读写<br> 经度引用，例如W或E。| 8445| GPS_LONGITUDE | "GPSLongitude" | **读写能力：** 可读写<br> 图片经度。修改时应按"度,分,秒"格式传入，如"116,19,42.16"| 8446| GPS_ALTITUDE_REF <sup>12+</sup> | "GPSAltitudeRef" | **读写能力：** 可读写<br> 用于GPS高度的参照高度。| 8447| GPS_ALTITUDE <sup>12+</sup> | "GPSAltitude" | **读写能力：** 可读写<br> 基于GPSAltitudeRef的高度。| 8448| GPS_TIME_STAMP<sup>10+</sup> | "GPSTimeStamp" | **读写能力：** 可读写<br> GPS时间戳。| 8449| GPS_SATELLITES <sup>12+</sup> | "GPSSatellites" | **读写能力：** 可读写<br> 用于测量的GPS卫星。| 8450| GPS_STATUS <sup>12+</sup> | "GPSStatus" | **读写能力：** 可读写<br> 录制图像时GPS接收器的状态。| 8451| GPS_MEASURE_MODE <sup>12+</sup> | "GPSMeasureMode" | **读写能力：** 可读写<br> GPS测量模式。| 8452| GPS_DOP <sup>12+</sup> | "GPSDOP" | **读写能力：** 可读写<br> GPS DOP（数据精度等级）。| 8453| GPS_SPEED_REF <sup>12+</sup> | "GPSSpeedRef" | **读写能力：** 可读写<br> 用来表示GPS接收器移动速度的单位。| 8454| GPS_SPEED <sup>12+</sup> | "GPSSpeed" | **读写能力：** 可读写<br> GPS接收器的移动速度。| 8455| GPS_TRACK_REF <sup>12+</sup> | "GPSTrackRef" | **读写能力：** 可读写<br> GPS接收机移动方向的参照。| 8456| GPS_TRACK <sup>12+</sup> | "GPSTrack" | **读写能力：** 可读写<br> GPS接收机的移动方向。| 8457| GPS_IMG_DIRECTION_REF <sup>12+</sup> | "GPSImgDirectionRef" | **读写能力：** 可读写<br> 图像方向的参照。| 8458| GPS_IMG_DIRECTION <sup>12+</sup> | "GPSImgDirection" | **读写能力：** 可读写<br> 拍摄时图像的方向。| 8459| GPS_MAP_DATUM <sup>12+</sup> | "GPSMapDatum" | **读写能力：** 可读写<br> GPS接收器使用的大地测量数据。| 8460| GPS_DEST_LATITUDE_REF <sup>12+</sup> | "GPSDestLatitudeRef" | **读写能力：** 可读写<br> 目的地点的纬度参照。| 8461| GPS_DEST_LATITUDE <sup>12+</sup> | "GPSDestLatitude" | **读写能力：** 可读写<br> 目的地点的纬度。| 8462| GPS_DEST_LONGITUDE_REF <sup>12+</sup> | "GPSDestLongitudeRef" | **读写能力：** 可读写<br> 目的地点的经度参照。| 8463| GPS_DEST_LONGITUDE <sup>12+</sup> | "GPSDestLongitude" | **读写能力：** 可读写<br> 目的地点的经度。| 8464| GPS_DEST_BEARING_REF <sup>12+</sup> | "GPSDestBearingRef" | **读写能力：** 可读写<br> 指向目的地点的方位参照。| 8465| GPS_DEST_BEARING <sup>12+</sup> | "GPSDestBearing" | **读写能力：** 可读写<br> 目的地方位。| 8466| GPS_DEST_DISTANCE_REF <sup>12+</sup> | "GPSDestDistanceRef" | **读写能力：** 可读写<br> 目标点距离的测量单位。| 8467| GPS_DEST_DISTANCE <sup>12+</sup> | "GPSDestDistance" | **读写能力：** 可读写<br> 到目的地点的距离。| 8468| GPS_PROCESSING_METHOD <sup>12+</sup> | "GPSProcessingMethod" | **读写能力：** 可读写<br> 记录定位方法名的字符字符串。| 8469| GPS_AREA_INFORMATION <sup>12+</sup> | "GPSAreaInformation" | **读写能力：** 可读写<br> 记录GPS区域名的字符字符串。| 8470| GPS_DATE_STAMP<sup>10+</sup> | "GPSDateStamp" | **读写能力：** 可读写<br> GPS日期戳。| 8471| GPS_DIFFERENTIAL <sup>12+</sup> | "GPSDifferential" | **读写能力：** 可读写<br> 此字段表示GPS数据是否应用了差分校正，对于精确的位置准确性至关重要。| 8472| GPS_H_POSITIONING_ERROR <sup>12+</sup> | "GPSHPositioningError" | **读写能力：** 可读写<br> 此标签指示水平定位误差，单位为米。| 8473| ISO_SPEED_RATINGS<sup>9+</sup> | "ISOSpeedRatings" | **读写能力：** 可读写<br> ISO感光度，例如400。| 8474| PHOTOGRAPHIC_SENSITIVITY <sup>12+</sup> | "PhotographicSensitivity" | **读写能力：** 可读写<br> 此标签指示拍摄图像时相机或输入设备的灵敏度。| 8475| OECF <sup>12+</sup> | "OECF" | **读写能力：** 可读写<br> 表示ISO 14524中规定的光电转换函数（OECF）。| 8476| SENSITIVITY_TYPE<sup>10+</sup> | "SensitivityType" | **读写能力：** 可读写<br> 灵敏度类型。| 8477| STANDARD_OUTPUT_SENSITIVITY<sup>10+</sup> | "StandardOutputSensitivity" | **读写能力：** 可读写<br> 标准输出灵敏度。| 8478| RECOMMENDED_EXPOSURE_INDEX<sup>10+</sup> | "RecommendedExposureIndex" | **读写能力：** 可读写<br> 推荐曝光指数。| 8479| ISO_SPEED<sup>10+</sup> | "ISOSpeedRatings" | **读写能力：** 可读写<br> ISO速度等级。| 8480| ISO_SPEED_LATITUDE_YYY <sup>12+</sup> | "ISOSpeedLatitudeyyy" | **读写能力：** 可读写<br> 该标签指示摄像机或输入设备的ISO速度纬度yyy值，该值在ISO 12232中定义。| 8481| ISO_SPEED_LATITUDE_ZZZ <sup>12+</sup> | "ISOSpeedLatitudezzz" | **读写能力：** 可读写<br> 该标签指示摄像机或输入设备的ISO速度纬度zzz值，该值在ISO 12232中定义。| 8482| EXIF_VERSION <sup>12+</sup> | "ExifVersion" | **读写能力：** 可读写<br> 支持的Exif标准版本。| 8483| DATE_TIME_ORIGINAL<sup>9+</sup> | "DateTimeOriginal" | **读写能力：** 可读写<br> 拍摄时间，例如2022:09:06 15:48:00。| 8484| DATE_TIME_DIGITIZED <sup>12+</sup> | "DateTimeDigitized" | **读写能力：** 可读写<br> 图像作为数字数据存储的日期和时间，格式为YYYY:MM:DD HH:MM:SS| 8485| OFFSET_TIME <sup>12+</sup> | "OffsetTime" | **读写能力：** 可读写<br> 在Exif中，OffsetTime字段表示与UTC（协调世界时）的时间偏移，格式为±HH:MM，用于确定照片拍摄的本地时间。| 8486| OFFSET_TIME_ORIGINAL <sup>12+</sup> | "OffsetTimeOriginal" | **读写能力：** 可读写<br> 此标签记录原始图像创建时的UTC偏移量，对于时间敏感的应用至关重要。| 8487| OFFSET_TIME_DIGITIZED <sup>12+</sup> | "OffsetTimeDigitized" | **读写能力：** 可读写<br> 此标签记录图像数字化时的UTC偏移量，有助于准确调整时间戳。| 8488| COMPONENTS_CONFIGURATION <sup>12+</sup> | "ComponentsConfiguration" | **读写能力：** 可读写<br> 压缩数据的特定信息。| 8489| COMPRESSED_BITS_PER_PIXEL <sup>12+</sup> | "CompressedBitsPerPixel" | **读写能力：** 可读写<br> 用于压缩图像的压缩模式，单位为每像素位数。| 8490| SHUTTER_SPEED <sup>12+</sup> | "ShutterSpeedValue" | **读写能力：** 可读写<br> 快门速度，以APEX（摄影曝光的加法系统）值表示。| 8491| APERTURE_VALUE<sup>10+</sup> | "ApertureValue" | **读写能力：** 可读写<br> 光圈值。格式如4/1。| 8492| BRIGHTNESS_VALUE <sup>12+</sup> | "BrightnessValue" | **读写能力：** 可读写<br> 图像的亮度值，以APEX单位表示。| 8493| EXPOSURE_BIAS_VALUE<sup>10+</sup> | "ExposureBiasValue" | **读写能力：** 可读写<br> 曝光偏差值。| 8494| MAX_APERTURE_VALUE <sup>12+</sup> | "MaxApertureValue" | **读写能力：** 可读写<br> 最小F数镜头。| 8495| SUBJECT_DISTANCE <sup>12+</sup> | "SubjectDistance" | **读写能力：** 可读写<br> 测量单位为米的主体距离。| 8496| METERING_MODE<sup>10+</sup> | "MeteringMode" | **读写能力：** 可读写<br> 测光模式。| 8497| LIGHT_SOURCE<sup>10+</sup> | "LightSource" | **读写能力：** 可读写<br> 光源。例如Fluorescent。| 8498| FLASH <sup>10+</sup> | "Flash" | **读写能力：** 可读写<br> 闪光灯,记录闪光灯状态。| 8499| FOCAL_LENGTH <sup>10+</sup> | "FocalLength" | **读写能力：** 可读写<br> 焦距。| 8500| SUBJECT_AREA <sup>12+</sup> | "SubjectArea" | **读写能力：** 可读写<br> 该标签指示整个场景中主要主体的位置和区域。| 8501| MAKER_NOTE <sup>12+</sup> | "MakerNote" | **读写能力：** 只读<br> Exif/DCF制造商使用的标签，用于记录任何所需信息。| 8502| SCENE_POINTER <sup>12+</sup> | "HwMnoteScenePointer" | **读写能力：** 只读<br> 场景指针。| 8503| SCENE_VERSION <sup>12+</sup> | "HwMnoteSceneVersion" | **读写能力：** 只读<br> 场景算法版本信息。| 8504| SCENE_FOOD_CONF<sup>11+</sup> | "HwMnoteSceneFoodConf" | **读写能力：** 只读<br> 拍照场景：食物。| 8505| SCENE_STAGE_CONF<sup>11+</sup> | "HwMnoteSceneStageConf" | **读写能力：** 只读<br> 拍照场景：舞台。| 8506| SCENE_BLUE_SKY_CONF<sup>11+</sup> | "HwMnoteSceneBlueSkyConf" | **读写能力：** 只读<br> 拍照场景：蓝天。| 8507| SCENE_GREEN_PLANT_CONF<sup>11+</sup> | "HwMnoteSceneGreenPlantConf" | **读写能力：** 只读<br> 拍照场景：绿植。| 8508| SCENE_BEACH_CONF<sup>11+</sup> | "HwMnoteSceneBeachConf" | **读写能力：** 只读<br> 拍照场景：沙滩。| 8509| SCENE_SNOW_CONF<sup>11+</sup> | "HwMnoteSceneSnowConf" | **读写能力：** 只读<br> 拍照场景：下雪。| 8510| SCENE_SUNSET_CONF<sup>11+</sup> | "HwMnoteSceneSunsetConf" | **读写能力：** 只读<br> 拍照场景：日落。| 8511| SCENE_FLOWERS_CONF<sup>11+</sup> | "HwMnoteSceneFlowersConf" | **读写能力：** 只读<br> 拍照场景：花。| 8512| SCENE_NIGHT_CONF<sup>11+</sup> | "HwMnoteSceneNightConf" | **读写能力：** 只读<br> 拍照场景：夜晚。| 8513| SCENE_TEXT_CONF<sup>11+</sup> | "HwMnoteSceneTextConf" | **读写能力：** 只读<br> 拍照场景：文本。| 8514| FACE_POINTER <sup>12+</sup> | "HwMnoteFacePointer" | **读写能力：** 只读<br> 脸部指针。| 8515| FACE_VERSION <sup>12+</sup> | "HwMnoteFaceVersion" | **读写能力：** 只读<br> 人脸算法版本信息。| 8516| FACE_COUNT<sup>11+</sup> | "HwMnoteFaceCount" | **读写能力：** 只读<br> 人脸数量。| 8517| FACE_CONF <sup>12+</sup> | "HwMnoteFaceConf" | **读写能力：** 只读<br> 人脸置信度。| 8518| FACE_SMILE_SCORE <sup>12+</sup> | "HwMnoteFaceSmileScore" | **读写能力：** 只读<br> FaceCount张人脸的笑脸分数。| 8519| FACE_RECT <sup>12+</sup> | "HwMnoteFaceRect" | **读写能力：** 只读<br> 脸部矩形。| 8520| FACE_LEYE_CENTER <sup>12+</sup> | "HwMnoteFaceLeyeCenter" | **读写能力：** 只读<br> 左眼中心。| 8521| FACE_REYE_CENTER <sup>12+</sup> | "HwMnoteFaceReyeCenter" | **读写能力：** 只读<br> 右眼中心。| 8522| FACE_MOUTH_CENTER <sup>12+</sup> | "HwMnoteFaceMouthCenter" | **读写能力：** 只读<br> 嘴中心。| 8523| CAPTURE_MODE <sup>10+</sup> | "HwMnoteCaptureMode" | **读写能力：** 可读写<br> 捕获模式。| 8524| BURST_NUMBER <sup>12+</sup> | "HwMnoteBurstNumber" | **读写能力：** 只读<br> 连拍次数。| 8525| FRONT_CAMERA <sup>12+</sup> | "HwMnoteFrontCamera" | **读写能力：** 只读<br> 是否是前置相机自拍。| 8526| ROLL_ANGLE <sup>11+</sup> | "HwMnoteRollAngle" | **读写能力：** 只读<br> 滚动角度。| 8527| PITCH_ANGLE<sup>11+</sup> | "HwMnotePitchAngle" | **读写能力：** 只读<br> 俯仰角度。| 8528| PHYSICAL_APERTURE <sup>10+</sup> | "HwMnotePhysicalAperture" | **读写能力：** 只读<br> 物理孔径，光圈大小。| 8529| FOCUS_MODE<sup>11+</sup> | "HwMnoteFocusMode" | **读写能力：** 只读<br> 对焦模式。| 8530| USER_COMMENT <sup>10+</sup> | "UserComment" | **读写能力：** 可读写<br> 用户注释。| 8531| SUBSEC_TIME <sup>12+</sup> | "SubsecTime" | **读写能力：** 可读写<br> 用于为DateTime标签记录秒的分数的标签。| 8532| SUBSEC_TIME_ORIGINAL <sup>12+</sup> | "SubsecTimeOriginal" | **读写能力：** 可读写<br> 用于为DateTimeOriginal标签记录秒的分数的标签。| 8533| SUBSEC_TIME_DIGITIZED <sup>12+</sup> | "SubsecTimeDigitized" | **读写能力：** 可读写<br> 用于为DateTimeDigitized标签记录秒的分数的标签。| 8534| FLASHPIX_VERSION <sup>12+</sup> | "FlashpixVersion" | **读写能力：** 可读写<br> 该标签表示FPXR文件支持的Flashpix格式版本，增强了设备兼容性。| 8535| COLOR_SPACE <sup>12+</sup> | "ColorSpace" | **读写能力：** 可读写<br> 色彩空间信息标签，通常记录为色彩空间指定符。| 8536| PIXEL_X_DIMENSION <sup>10+</sup> | "PixelXDimension" | **读写能力：** 可读写<br> 像素X尺寸。| 8537| PIXEL_Y_DIMENSION<sup>10+</sup> | "PixelYDimension" | **读写能力：** 可读写<br> 像素Y尺寸。| 8538| RELATED_SOUND_FILE <sup>12+</sup> | "RelatedSoundFile" | **读写能力：** 可读写<br> 与图像数据相关的音频文件的名称。| 8539| FLASH_ENERGY <sup>12+</sup> | "FlashEnergy" | **读写能力：** 可读写<br> 图像捕获时的闪光能量，以BCPS表示。| 8540| SPATIAL_FREQUENCY_RESPONSE <sup>12+</sup> | "SpatialFrequencyResponse" | **读写能力：** 可读写<br> 相机或输入设备的空间频率表。| 8541| FOCAL_PLANE_X_RESOLUTION <sup>12+</sup> | "FocalPlaneXResolution" | **读写能力：** 可读写<br> 图像宽度中每FocalPlaneResolutionUnit的像素。| 8542| FOCAL_PLANE_Y_RESOLUTION <sup>12+</sup> | "FocalPlaneYResolution" | **读写能力：** 可读写<br> 图像高度中每FocalPlaneResolutionUnit的像素。| 8543| FOCAL_PLANE_RESOLUTION_UNIT <sup>12+</sup> | "FocalPlaneResolutionUnit" | **读写能力：** 可读写<br> 测量FocalPlaneXResolution和FocalPlaneYResolution的单位。| 8544| SUBJECT_LOCATION <sup>12+</sup> | "SubjectLocation" | **读写能力：** 可读写<br> 主要对象相对于左边缘的位置。| 8545| EXPOSURE_INDEX <sup>12+</sup> | "ExposureIndex" | **读写能力：** 可读写<br> 捕获时选定的曝光指数。| 8546| SENSING_METHOD <sup>12+</sup> | "SensingMethod" | **读写能力：** 可读写<br> 相机上的图像传感器类型。| 8547| FILE_SOURCE <sup>12+</sup> | "FileSource" | **读写能力：** 可读写<br> 表明图像来源。| 8548| SCENE_TYPE<sup>9+</sup> | "SceneType" | **读写能力：** 可读写<br> 拍摄场景模式，例如人像、风光、运动、夜景等。| 8549| CFA_PATTERN <sup>12+</sup> | "CFAPattern" | **读写能力：** 可读写<br> 图像传感器的色彩滤光片（CFA）几何图案。| 8550| CUSTOM_RENDERED <sup>12+</sup> | "CustomRendered" | **读写能力：** 可读写<br> 指示图像数据上的特殊处理。| 8551| EXPOSURE_MODE <sup>12+</sup> | "ExposureMode" | **读写能力：** 可读写<br> 拍摄时设置的曝光模式。| 8552| WHITE_BALANCE <sup>10+</sup> | "WhiteBalance" | **读写能力：** 可读写<br> 白平衡。| 8553| DIGITAL_ZOOM_RATIO <sup>12+</sup> | "DigitalZoomRatio" | **读写能力：** 可读写<br> 捕获时的数字变焦比率。| 8554| FOCAL_LENGTH_IN_35_MM_FILM <sup>10+</sup> | "FocalLengthIn35mmFilm" | **读写能力：** 可读写<br> 焦距35毫米胶片。| 8555| SCENE_CAPTURE_TYPE <sup>12+</sup> | "SceneCaptureType" | **读写能力：** 可读写<br> 捕获的场景类型。| 8556| GAIN_CONTROL <sup>12+</sup> | "GainControl" | **读写能力：** 可读写<br> 整体图像增益调整的程度。| 8557| CONTRAST <sup>12+</sup> | "Contrast" | **读写能力：** 可读写<br> 相机应用的对比度处理方向。| 8558| SATURATION <sup>12+</sup> | "Saturation" | **读写能力：** 可读写<br> 相机应用的饱和度处理方向。| 8559| SHARPNESS <sup>12+</sup> | "Sharpness" | **读写能力：** 可读写<br> 相机应用的锐度处理方向。| 8560| DEVICE_SETTING_DESCRIPTION <sup>12+</sup> | "DeviceSettingDescription" | **读写能力：** 可读写<br> 特定相机模型的拍照条件信息。| 8561| SUBJECT_DISTANCE_RANGE <sup>12+</sup> | "SubjectDistanceRange" | **读写能力：** 可读写<br> 表示主体到相机的距离范围。| 8562| IMAGE_UNIQUE_ID <sup>12+</sup> | "ImageUniqueID" | **读写能力：** 可读写<br> 为每张图片唯一分配的标识符。| 8563| CAMERA_OWNER_NAME <sup>12+</sup> | "CameraOwnerName" | **读写能力：** 可读写<br> 相机所有者的姓名。| 8564| BODY_SERIAL_NUMBER <sup>12+</sup> | "BodySerialNumber" | **读写能力：** 可读写<br> 相机机身的序列号。| 8565| LENS_SPECIFICATION <sup>12+</sup> | "LensSpecification" | **读写能力：** 可读写<br> 使用的镜头规格。| 8566| LENS_MAKE <sup>12+</sup> | "LensMake" | **读写能力：** 可读写<br> 镜头的制造商。| 8567| LENS_MODEL <sup>12+</sup> | "LensModel" | **读写能力：** 可读写<br> 镜头的型号名称。| 8568| LENS_SERIAL_NUMBER <sup>12+</sup> | "LensSerialNumber" | **读写能力：** 可读写<br> 镜头的序列号。| 8569| COMPOSITE_IMAGE <sup>12+</sup> | "CompositeImage" | **读写能力：** 可读写<br> 表示图像是否为合成图像。| 8570| SOURCE_IMAGE_NUMBER_OF_COMPOSITE_IMAGE <sup>12+</sup> | "SourceImageNumberOfCompositeImage" | **读写能力：** 可读写<br> 用于合成图像的源图像数量。| 8571| SOURCE_EXPOSURE_TIMES_OF_COMPOSITE_IMAGE <sup>12+</sup> | "SourceExposureTimesOfCompositeImage" | **读写能力：** 可读写<br> 合成图像的源图像曝光时间。| 8572| GAMMA <sup>12+</sup> | "Gamma" | **读写能力：** 可读写<br> 表示系数伽马的值。| 8573| DNG_VERSION <sup>12+</sup> | "DNGVersion" | **读写能力：** 可读写<br> DNG版本标签编码了符合DNG规范的四级版本号。| 8574| DEFAULT_CROP_SIZE <sup>12+</sup> | "DefaultCropSize" | **读写能力：** 可读写<br> DefaultCropSize指定了原始坐标中的最终图像大小，考虑了额外的边缘像素。| 8575| GIF_LOOP_COUNT <sup>12+</sup> | "GIFLoopCount" | **读写能力：** 只读<br> GIF图片循环次数。0表示无限循环，其他值表示循环次数。| 8576| IS_XMAGE_SUPPORTED <sup>12+</sup> | "HwMnoteIsXmageSupported" | **读写能力：** 可读写<br>是否支持XMAGE。 | 8577| XMAGE_MODE <sup>12+</sup> | "HwMnoteXmageMode" | **读写能力：** 可读写<br>XMAGE水印模式。 | 8578| XMAGE_LEFT <sup>12+</sup> | "HwMnoteXmageLeft" | **读写能力：** 可读写<br>水印区域X1坐标。 | 8579| XMAGE_TOP <sup>12+</sup> | "HwMnoteXmageTop" | **读写能力：** 可读写<br>水印区域Y1坐标。 | 8580| XMAGE_RIGHT <sup>12+</sup> | "HwMnoteXmageRight" | **读写能力：** 可读写<br>水印区域X2坐标。 | 8581| XMAGE_BOTTOM <sup>12+</sup> | "HwMnoteXmageBottom" | **读写能力：** 可读写<br>水印区域Y2坐标。 | 8582| CLOUD_ENHANCEMENT_MODE <sup>12+</sup> | "HwMnoteCloudEnhancementMode" | **读写能力：** 可读写<br>云增强模式。 | 8583| WIND_SNAPSHOT_MODE <sup>12+</sup> | "HwMnoteWindSnapshotMode" | **读写能力：** 只读<br>运动快拍模式。 | 8584 8585## FragmentMapPropertyKey<sup>13+</sup> 8586 8587枚举，水印裁剪图图片信息。 8588 8589**系统能力：** SystemCapability.Multimedia.Image.Core 8590 8591| 名称 | 值 | 说明 | 8592| ------------- | --------------------- | ----------------------------------- | 8593| X_IN_ORIGINAL | "XInOriginal" | 水印裁剪图左上角在原始图中的X坐标。 | 8594| Y_IN_ORIGINAL | "YInOriginal" | 水印裁剪图左上角在原始图中的Y坐标。 | 8595| WIDTH | "FragmentImageWidth" | 水印裁剪图的宽。 | 8596| HEIGHT | "FragmentImageHeight" | 水印裁剪图的高。 | 8597 8598## ImageFormat<sup>9+</sup> 8599 8600枚举，图片格式。 8601 8602**系统能力：** SystemCapability.Multimedia.Image.Core 8603 8604| 名称 | 值 | 说明 | 8605| ------------ | ------ | -------------------- | 8606| YCBCR_422_SP | 1000 | YCBCR422半平面格式。 | 8607| JPEG | 2000 | JPEG编码格式。 | 8608 8609## ComponentType<sup>9+</sup> 8610 8611枚举，图像的组件类型。 8612 8613**系统能力：** SystemCapability.Multimedia.Image.ImageReceiver 8614 8615| 名称 | 值 | 说明 | 8616| ----- | ------ | ----------- | 8617| YUV_Y | 1 | 亮度信息。 | 8618| YUV_U | 2 | 色度信息。 | 8619| YUV_V | 3 | 色度信息。 | 8620| JPEG | 4 | JPEG 类型。 | 8621 8622## Component<sup>9+</sup> 8623 8624描述图像颜色分量。 8625 8626**系统能力：** SystemCapability.Multimedia.Image.Core 8627 8628| 名称 | 类型 | 只读 | 可选 | 说明 | 8629| ------------- | -------------------------------- | ---- | ---- | ------------ | 8630| componentType | [ComponentType](#componenttype9) | 是 | 否 | 组件类型。 | 8631| rowStride | number | 是 | 否 | 行距。读取相机预览流数据时，需要考虑按stride进行读取，具体用法见[ArkTS双路预览示例](../../media/camera/camera-dual-channel-preview.md)。 | 8632| pixelStride | number | 是 | 否 | 像素间距。 | 8633| byteBuffer | ArrayBuffer | 是 | 否 | 组件缓冲区。 | 8634 8635## DecodingDynamicRange<sup>12+</sup> 8636 8637描述解码时期望的图像动态范围。 8638 8639**系统能力：** SystemCapability.Multimedia.Image.Core 8640 8641| 名称 | 值 | 说明 | 8642| ------------- | ----------| ------------ | 8643| AUTO | 0 | 自适应，根据图片信息处理。即如果图片本身为HDR图片，则会按照HDR内容解码；反之按照SDR内容解码。通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource会解码为SDR内容。 | 8644| SDR | 1 | 按照标准动态范围处理图片。 | 8645| HDR | 2 | 按照高动态范围处理图片。通过[CreateIncrementalSource](#imagecreateincrementalsource9)创建的imagesource会解码为SDR内容。 | 8646 8647## PackingDynamicRange<sup>12+</sup> 8648 8649描述编码时期望的图像动态范围。 8650 8651**系统能力：** SystemCapability.Multimedia.Image.Core 8652 8653| 名称 | 值 | 说明 | 8654| ------------- | ----------| ------------ | 8655| AUTO | 0 | 自适应，根据[pixelmap](#pixelmap7)内容处理。即如果pixelmap本身为HDR，则会按照HDR内容进行编码；反之按照SDR内容编码。 | 8656| SDR | 1 | 按照标准动态范围处理图片。 | 8657 8658## CropAndScaleStrategy<sup>18+</sup> 8659 8660枚举，裁剪与缩放的先后策略。 8661 8662**系统能力：** SystemCapability.Multimedia.Image.Core 8663 8664| 名称 | 值 | 说明 | 8665| ------------- | ----------| ------------ | 8666| SCALE_FIRST | 1 | 解码参数如果同时设置desiredRegion与desiredSize，先根据desiredSize进行缩放，再根据desiredRegion进行区域裁剪。 | 8667| CROP_FIRST | 2 | 解码参数如果同时设置desiredRegion与desiredSize，先根据desiredRegion进行区域裁剪，再根据desiredSize进行缩放。 | 8668 8669 8670 8671## HdrMetadataKey<sup>12+</sup> 8672 8673枚举，[pixelmap](#pixelmap7)使用的HDR相关元数据信息的关键字。 8674 8675**系统能力：** SystemCapability.Multimedia.Image.Core 8676 8677| 名称 | 值 | 说明 | 8678| ------------- | ----------| ------------ | 8679| HDR_METADATA_TYPE | 0 | [pixelmap](#pixelmap7)使用的元数据类型。 | 8680| HDR_STATIC_METADATA | 1 | 静态元数据。 | 8681| HDR_DYNAMIC_METADATA | 2 | 动态元数据。 | 8682| HDR_GAINMAP_METADATA | 3 | Gainmap使用的元数据。 | 8683 8684## HdrMetadataType<sup>12+</sup> 8685 8686枚举，[HdrMetadataKey](#hdrmetadatakey12)中HDR_METADATA_TYPE关键字对应的值。 8687 8688**系统能力：** SystemCapability.Multimedia.Image.Core 8689 8690| 名称 | 值 | 说明 | 8691| ------------- | ----------| ------------ | 8692| NONE | 0 | 无元数据内容。 | 8693| BASE | 1 | 表示用于基础图的元数据。 | 8694| GAINMAP | 2 | 表示用于Gainmap图的元数据。 | 8695| ALTERNATE| 3 | 表示用于合成后HDR图的元数据。 | 8696 8697## HdrStaticMetadata<sup>12+</sup> 8698 8699静态元数据值，[HdrMetadataKey](#hdrmetadatakey12)中HDR_STATIC_METADATA关键字对应的值。 8700 8701**系统能力：** SystemCapability.Multimedia.Image.Core 8702 8703| 名称 | 类型 | 只读 | 可选 | 说明 | 8704| ------------- | ----------| -- | -- | ------------ | 8705| displayPrimariesX | Array\<number> | 否 | 否 | 归一化后显示设备三基色的X坐标，数组的长度为3，以0.00002为单位，范围[0.0, 1.0]。 | 8706| displayPrimariesY | Array\<number> | 否 | 否 | 归一化后显示设备三基色的Y坐标，数组的长度为3，以0.00002为单位，范围[0.0, 1.0]。 | 8707| whitePointX | number | 否 | 否 | 归一化后白点值的X坐标，以0.00002为单位，范围[0.0, 1.0]。 | 8708| whitePointY | number | 否 | 否 | 归一化后白点值的Y坐标，以0.00002为单位，范围[0.0, 1.0]。 | 8709| maxLuminance | number | 否 | 否 | 图像主监视器最大亮度。以1为单位，最大值为65535。 | 8710| minLuminance | number | 否 | 否 | 图像主监视器最小亮度。以0.0001为单位，最大值6.55535。 | 8711| maxContentLightLevel | number | 否 | 否 | 显示内容的最大亮度。以1为单位，最大值为65535。 | 8712| maxFrameAverageLightLevel | number | 否 | 否 | 显示内容的最大平均亮度，以1为单位，最大值为65535。 | 8713 8714## GainmapChannel<sup>12+</sup> 8715 8716Gainmap图单个通道的数据内容，参考ISO 21496-1。 8717 8718**系统能力：** SystemCapability.Multimedia.Image.Core 8719 8720| 名称 | 类型 | 只读 | 可选 | 说明 | 8721| ------------- | ----------| -- | -- | ------------ | 8722| gainmapMax | number | 否 | 否 | 增强图像的最大值，参考ISO 21496-1。 | 8723| gainmapMin | number | 否 | 否 | 增强图像的最小值，参考ISO 21496-1。 | 8724| gamma | number | 否 | 否 | gamma值，参考ISO 21496-1。 | 8725| baseOffset | number | 否 | 否 | 基础图的偏移，参考ISO 21496-1。 | 8726| alternateOffset | number | 否 | 否 | 提取的可选择图像偏移量，参考ISO 21496-1。 | 8727 8728## HdrGainmapMetadata<sup>12+</sup> 8729 8730Gainmap使用的元数据值，[HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的值，参考ISO 21496-1。 8731 8732**系统能力：** SystemCapability.Multimedia.Image.Core 8733 8734| 名称 | 类型 | 只读 | 可选 | 说明 | 8735| ------------- | ----------| -- | -- | ------------ | 8736| writerVersion | number | 否 | 否 | 元数据编写器使用的版本。 | 8737| miniVersion | number | 否 | 否 | 元数据解析需要理解的最小版本。 | 8738| gainmapChannelCount | number | 否 | 否 | Gainmap的颜色通道数，值为3时RGB通道的元数据值不同，值为1时各通道元数据值相同，参考ISO 21496-1。 | 8739| useBaseColorFlag | boolean | 否 | 否 | 是否使用基础图的色彩空间，参考ISO 21496-1。true表示是，false表示否。 | 8740| baseHeadroom | number | 否 | 否 | 基础图提亮比，参考ISO 21496-1。 | 8741| alternateHeadroom | number | 否 | 否 | 提取的可选择图像提亮比，参考ISO 21496-1。 | 8742| channels | Array<[GainmapChannel](#gainmapchannel12)> | 否 | 否 | 各通道的数据，长度为3，参考ISO 21496-1。 | 8743 8744## HdrMetadataValue<sup>12+</sup> 8745 8746type HdrMetadataValue = HdrMetadataType | HdrStaticMetadata | ArrayBuffer | HdrGainmapMetadata 8747 8748PixelMap使用的HDR元数据值类型，和[HdrMetadataKey](#hdrmetadatakey12)关键字相对应。 8749 8750**系统能力：** SystemCapability.Multimedia.Image.Core 8751 8752| 类型 | 说明 | 8753| ------------------- | ----------------------------------------------- | 8754| [HdrMetadataType](#hdrmetadatatype12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的元数据值类型。 | 8755| [HdrStaticMetadata](#hdrstaticmetadata12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_STATIC_METADATA关键字对应的元数据值类型。 | 8756| ArrayBuffer | [HdrMetadataKey](#hdrmetadatakey12)中HDR_DYNAMIC_METADATA关键字对应的元数据值类型。 | 8757| [HdrGainmapMetadata](#hdrgainmapmetadata12) | [HdrMetadataKey](#hdrmetadatakey12)中HDR_GAINMAP_METADATA关键字对应的元数据值类型。 | 8758 8759## AntiAliasingLevel<sup>12+</sup> 8760 8761缩放时的缩放算法。 8762 8763**原子化服务API**：从API version 14 开始，该接口支持在原子化服务中使用。 8764 8765**系统能力：** SystemCapability.Multimedia.Image.Core 8766 8767| 名称 | 值 | 说明 | 8768| ---------------------- | ------ | ----------------- | 8769| NONE | 0 | 最近邻插值算法。 | 8770| LOW | 1 | 双线性插值算法。 | 8771| MEDIUM | 2 | 双线性插值算法，同时开启Mipmap。缩小图片时建议使用。 | 8772| HIGH | 3 | 三次插值算法。 | 8773 8774## AllocatorType<sup>15+</sup> 8775 8776枚举，用于图像解码的内存类型。 8777 8778**系统能力：** SystemCapability.Multimedia.Image.Core 8779 8780| 名称 | 值 | 说明 | 8781| ------------ | ---- | ---------------------------------- | 8782| AUTO | 0 | 系统决定内存申请方式。 | 8783| DMA | 1 | 使用DMA内存申请方式。 | 8784| SHARE_MEMORY | 2 | 使用SHARE_MEMORY的内存申请方式。 | 8785 8786## 补充说明 8787 8788### SVG标签说明 8789 8790从API version 10开始支持SVG标签，使用版本为(SVG) 1.1，SVG标签需设置width，height。SVG文件可添加xml声明，应以“<?xml”开头，当前支持的标签列表有： 8791- a 8792- circla 8793- clipPath 8794- defs 8795- ellipse 8796- feBlend 8797- feColorMatrix 8798- feComposite 8799- feDiffuseLighting 8800- feDisplacementMap 8801- feDistantLight 8802- feFlood 8803- feGaussianBlur 8804- feImage 8805- feMorphology 8806- feOffset 8807- fePointLight 8808- feSpecularLighting 8809- feSpotLight 8810- feTurbulence 8811- filter 8812- g 8813- image 8814- line 8815- linearGradient 8816- mask 8817- path 8818- pattern 8819- polygon 8820- polyline 8821- radialGradient 8822- rect 8823- stop 8824- svg 8825- text 8826- textPath 8827- tspan 8828- use
