1# Interface (Image) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--Designer: @liyang_bryan--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Interface首批接口从API version 9开始支持。 13 14提供基本的图像操作，包括获取图像信息、读写图像数据。调用[readNextImage](arkts-apis-image-ImageReceiver.md#readnextimage9)和[readLatestImage](arkts-apis-image-ImageReceiver.md#readlatestimage9)接口时会返回image。 15 16## 导入模块 17 18```ts 19import { image } from '@kit.ImageKit'; 20``` 21 22## 属性 23 24**系统能力：** SystemCapability.Multimedia.Image.Core 25 26| 名称 | 类型 | 只读 | 可选 | 说明 | 27| -------- | ------------------ | ---- | ---- | -------------------------------------------------- | 28| clipRect<sup>9+</sup> | [Region](arkts-apis-image-i.md#region8) | 否 | 否 | 要裁剪的图像区域。 | 29| size<sup>9+</sup> | [Size](arkts-apis-image-i.md#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)。 | 30| format<sup>9+</sup> | number | 是 | 否 | 图像格式，参考[OH_NativeBuffer_Format](../apis-arkgraphics2d/capi-native-buffer-h.md#oh_nativebuffer_format)。 | 31| timestamp<sup>12+</sup> | number | 是 | 否 | 图像时间戳。时间戳以纳秒为单位，通常是单调递增的。时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。如果要获取某张照片的生成时间，可以通过[getImageProperty](arkts-apis-image-ImageSource.md#getimageproperty11)接口读取相关的EXIF信息。| 32 33## getComponent<sup>9+</sup> 34 35getComponent(componentType: ComponentType, callback: AsyncCallback\<Component>): void 36 37根据图像的组件类型从图像中获取组件缓存并使用callback返回结果。 38 39**系统能力：** SystemCapability.Multimedia.Image.Core 40 41**参数：** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| ------------- | --------------------------------------- | ---- | -------------------- | 45| componentType | [ComponentType](arkts-apis-image-e.md#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机） | 46| callback | AsyncCallback<[Component](arkts-apis-image-i.md#component9)> | 是 | 回调函数，当返回组件缓冲区成功，err为undefined，data为获取到的组件缓冲区；否则为错误对象。 | 47 48**示例：** 49 50```ts 51import { BusinessError } from '@kit.BasicServicesKit'; 52 53async function GetComponent(img : image.Image) { 54 img.getComponent(image.ComponentType.JPEG, (err: BusinessError, component: image.Component) => { 55 if (err) { 56 console.error(`Failed to get the component.code ${err.code},message is ${err.message}`); 57 } else { 58 console.info('Succeeded in getting component.'); 59 } 60 }) 61} 62``` 63 64## getComponent<sup>9+</sup> 65 66getComponent(componentType: ComponentType): Promise\<Component> 67 68根据图像的组件类型从图像中获取组件缓存并使用Promise方式返回结果。 69 70**系统能力：** SystemCapability.Multimedia.Image.Core 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| ------------- | -------------------------------- | ---- | ---------------- | 76| componentType | [ComponentType](arkts-apis-image-e.md#componenttype9) | 是 | 图像的组件类型。（目前仅支持 ComponentType:JPEG，实际返回格式由生产者决定，如相机）。 | 77 78**返回值：** 79 80| 类型 | 说明 | 81| --------------------------------- | --------------------------------- | 82| Promise<[Component](arkts-apis-image-i.md#component9)> | Promise对象，返回组件缓冲区。 | 83 84**示例：** 85 86```ts 87import { BusinessError } from '@kit.BasicServicesKit'; 88 89async function GetComponent(img : image.Image) { 90 img.getComponent(image.ComponentType.JPEG).then((component: image.Component) => { 91 console.info('Succeeded in getting component.'); 92 }).catch((error: BusinessError) => { 93 console.error(`Failed to get the component.code ${error.code},message is ${error.message}`); 94 }) 95} 96``` 97 98## release<sup>9+</sup> 99 100release(callback: AsyncCallback\<void>): void 101 102释放当前图像并使用callback返回结果。 103 104在接收另一个图像前必须先释放对应资源。 105 106ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 107 108**系统能力：** SystemCapability.Multimedia.Image.Core 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| -------- | -------------------- | ---- | -------------- | 114| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 115 116**示例：** 117 118```ts 119import { BusinessError } from '@kit.BasicServicesKit'; 120 121async function Release(img : image.Image) { 122 img.release((err: BusinessError) => { 123 if (err) { 124 console.error(`Failed to release the image instance.code ${err.code},message is ${err.message}`); 125 } else { 126 console.info('Succeeded in releasing the image instance.'); 127 } 128 }) 129} 130``` 131 132## release<sup>9+</sup> 133 134release(): Promise\<void> 135 136释放当前图像并使用Promise方式返回结果。 137 138在接收另一个图像前必须先释放对应资源。 139 140ArkTS有内存回收机制，Image对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 141 142**系统能力：** SystemCapability.Multimedia.Image.Core 143 144**返回值：** 145 146| 类型 | 说明 | 147| -------------- | --------------------- | 148| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 149 150**示例：** 151 152```ts 153import { BusinessError } from '@kit.BasicServicesKit'; 154 155async function Release(img : image.Image) { 156 img.release().then(() => { 157 console.info('Succeeded in releasing the image instance.'); 158 }).catch((error: BusinessError) => { 159 console.error(`Failed to release the image instance.code ${error.code},message is ${error.message}`); 160 }) 161} 162``` 163
