1# Image 2 3Image为图片组件，常用于在应用中显示图片。Image支持加载[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)、[ResourceStr](ts-types.md#resourcestr)和[DrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#drawabledescriptor)类型的数据源，支持png、jpg、jpeg、bmp、svg、webp和gif类型的图片格式。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 需要权限 11 12使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 13 14 15## 子组件 16 17无 18 19 20## 接口 21 22Image(src: PixelMap | ResourceStr | DrawableDescriptor) 23 24通过图片数据源获取图片，用于后续渲染展示。 25 26Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。 27 28从API version 9开始，该接口支持在ArkTS卡片中使用。 29 30**参数：** 31 32| 参数名 | 参数类型 | 必填 | 参数描述 | 33| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 34| src | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [ResourceStr](ts-types.md#resourcestr)\| [DrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br>1. PixelMap格式为像素图，常用于图片编辑的场景。<br>2. ResourceStr包含Resource和string格式。<br>string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。<br>- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, 其中`[base64 data]`为`Base64`字符串数据。<br>- 支持file://路径前缀的字符串，[应用沙箱URI](../../apis-core-file-kit/js-apis-file-fileuri.md#constructor10)：file://\<bundleName>/\<sandboxPath>。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。<br>Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。<br/>3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。<br>**说明：**<br/>- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。<br/>- ArkTS卡片上不支持http:/\/等网络相关路径前缀和file:/\/路径前缀的字符串。<br/>- ArkTS卡片上不支持 [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)类型。 <br/>- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。<br/>- 网络图片必须支持RFC 9113标准，否则会导致加载失败。<br/>- 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。 | 35 36## 属性 37 38属性的详细使用指导请参考[添加属性](../../../ui/arkts-graphics-display.md#添加属性)。除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 39 40| 名称 | 参数类型 | 描述 | 41| ---------------------------- | ---------------------------------------- | ---------------------------------------- | 42| alt | string \| [Resource](ts-types.md#resource类型) | 加载时显示的占位图，支持本地图片（png、jpg、bmp、svg和gif类型），不支持网络图片。<br>默认值：null<br>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 43| objectFit | [ImageFit](ts-appendix-enums.md#imagefit) | 设置图片的填充效果。<br/>默认值：ImageFit.Cover<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 44| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 设置图片的重复样式。从中心点向两边重复，剩余空间不足放下一张图片时会截断。<br/>默认值：ImageRepeat.NoRepeat<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：**<br/>svg类型图源不支持该属性。 | 45| interpolation | [ImageInterpolation](#imageinterpolation) | 设置图片的插值效果，即缓解图片在缩放时的锯齿问题。<br/>默认值：ImageInterpolation.Low<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：**<br/>svg类型图源不支持该属性。 | 46| renderMode | [ImageRenderMode](#imagerendermode) | 设置图片的渲染模式为原色或黑白。<br/>默认值：ImageRenderMode.Original<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：** <br/>svg类型图源不支持该属性。 | 47| sourceSize | {<br/>width: number,<br/>height: number<br/>} | 设置图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。<br/>单位：vp<br>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：**<br/>仅在目标尺寸小于图源尺寸时生效。<br>svg类型图源不支持该属性。<br>PixelMap资源不支持该属性。 | 48| matchTextDirection | boolean | 设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。<br/>默认值：false<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 49| fitOriginalSize | boolean | 图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。<br/>默认值：false<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 50| fillColor | [ResourceColor](ts-types.md#resourcecolor) | 设置填充颜色，设置后填充颜色会覆盖在图片上。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**说明：** <br>仅对svg图源生效，设置后会替换svg图片的填充颜色。 | 51| autoResize | boolean | 设置图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会降采样解码到200x200的尺寸，大幅度节省图片占用的内存。<br/>默认值：false<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 <br>**说明：** <br>降采样解码时图片的部分信息丢失，因此可能会导致图片质量的下降（如：出现锯齿），这时可以选择把autoResize设为false，按原图尺寸解码，提升显示效果，但会增加内存占用。<br>原图尺寸和显示尺寸不匹配时，图片都会出现些许的失真、模糊。最佳清晰度配置建议：<br>图片缩小显示时：.autoResize(false) + .interpolation(.Medium)<br>图片放大显示时：.interpolation(.High) | 52| syncLoad<sup>8+</sup> | boolean | 设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。<br/>默认值：false<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**说明：**<br>建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。 | 53| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 设置图片是否可复制。<br>当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。<br>默认值：CopyOptions.None<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**说明：**<br>svg图片不支持复制。 | 54| colorFilter<sup>9+</sup> | [ColorFilter](ts-types.md#colorfilter9) | 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。<br/>矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。<br>当矩阵对角线值为1，其余值为0时，保持图片原有色彩。<br> **计算规则：**<br>如果输入的滤镜矩阵为：<br><br>像素点为[R, G, B, A]<br>则过滤后的颜色为 [R’, G’, B’, A’]<br><br>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：** <br/>svg类型图源不支持该属性。 | 55| draggable<sup>9+</sup> | boolean | 设置组件默认拖拽效果，设置为true时，组件可拖拽。<br>不能和[onDragStart](ts-universal-events-drag-drop.md#ondragstart)事件同时使用。<br/>默认值：false<br>**说明：**<br />API version 9的默认值为false，API version 10的默认值为true。 | 56| enableAnalyzer<sup>11+</sup> | boolean | 设置组件支持AI分析，设置为true时，组件可进行AI分析。<br>不能和[overlay](ts-universal-attributes-overlay.md)属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。<br/>默认值：false<br>**说明：**<br/> 该特性依赖设备能力。 <br/> 分析图像要求是静态非矢量图，即svg、gif等图像类型不支持分析，支持传入[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)进行分析，目前仅支持[RGBA_8888](../../apis-image-kit/js-apis-image.md#pixelmapformat7)类型，使用方式见[示例](#使用pixelmap开启图像分析)。 <br/> alt占位图不支持分析，objectRepeat属性仅在ImageRepeat.NoRepeat下支持分析，隐私遮罩属性[obscured](ts-universal-attributes-obscured.md)打开时不支持分析。<br/> 基于完整原始图像进行分析，设置clip、margin、borderRadius、position和objectFit属性导致图像显示不完整，或使用renderMode设置蒙层，仍基于完整原始图像进行分析。<br/> copyOption属性不影响AI分析功能。 | 57| resizable<sup>11+</sup> | [ResizableOptions](#resizableoptions11) | 设置图像拉伸时可调整大小的图像选项。<br> **说明：**<br /> 1. 拉伸对拖拽缩略图以及占位图有效。<br>2. 设置合法的 [ResizableOptions](#resizableoptions11) 时，objectRepeat 属性设置不生效。<br>3. 当设置 top +bottom 大于原图的高或者 left + right 大于原图的宽时 [ResizableOptions](#resizableoptions11) 属性设置不生效。<br/> | 58 59> **说明：** 60> 61> - 使用快捷组合键对Image组件复制时，Image组件必须处于[获焦状态](../../../ui/arkts-common-events-focus-event.md#设置组件是否获焦)。Image组件默认不获焦，需将[focusable](ts-universal-attributes-focus.md#focusable)属性设置为true，即可使用TAB键将焦点切换到组件上，再将[focusOnTouch](ts-universal-attributes-focus.md#focusontouch9)属性设置为true，即可实现点击获焦。 62> - 图片设置为svg图源时，当前支持的标签是svg、rect、circle、ellipse、path、line、polyline和polygon。 63 64## ImageInterpolation 65 66从API version 9开始，该接口支持在ArkTS卡片中使用。 67 68| 名称 | 描述 | 69| ------ | -------------------------- | 70| None | 不使用图片插值。 | 71| High | 高图片插值，插值质量最高，可能会影响图片渲染的速度。 | 72| Medium | 中图片插值。 | 73| Low | 低图片插值。 | 74 75## ImageRenderMode 76 77从API version 9开始，该接口支持在ArkTS卡片中使用。 78 79| 名称 | 描述 | 80| -------- | ------- | 81| Original | 原色渲染模式。 | 82| Template | 黑白渲染模式。 | 83 84## ResizableOptions<sup>11+</sup> 85 86图像拉伸时可调整大小的图像选项。 87 88| 参数名 | 类型 | 说明 | 89| ----- | ------------------------------------- | ---------------------------------------- | 90| slice | [EdgeWidths](#edgewidths参数说明) | 边框宽度类型，用于描述组件边框不同方向的宽度。<br>**说明：**<br>只有当bottom和right同时大于0时，该属性生效。 | 91 92## EdgeWidths参数说明 93 94| 名称 | 类型 | 必填 | 说明 | 95| --------- |-----------|-----------|-----------| 96| top | number | 否 | 图片顶部拉伸时保持不变距离。<br>默认值：0<br>单位：vp | 97| right | number | 否 | 图片右部拉伸时保持不变距离。<br>默认值：0<br>单位：vp | 98| bottom | number | 否 | 图片底部拉伸时保持不变距离。<br>默认值：0<br>单位：vp | 99| left | number | 否 | 图片左部拉伸时保持不变距离。<br>默认值：0<br>单位：vp | 100 101 102 103## 事件 104 105除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 106 107### onComplete 108 109onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number}) => void) }) => void) 110 111图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 112 113从API version 9开始，该接口支持在ArkTS卡片中使用。 114 115**参数：** 116 117| 参数名 | 类型 | 说明 | 118| ---------------------------- | ------ | ---------------------------------------- | 119| width | number | 图片的宽。<br/>单位：像素 | 120| height | number | 图片的高。<br/>单位：像素 | 121| componentWidth | number | 组件的宽。<br/>单位：像素 | 122| componentHeight | number | 组件的高。<br/>单位：像素 | 123| loadingStatus | number | 图片加载成功的状态值。<br/>**说明：**<br/>返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | 124| contentWidth<sup>10+</sup> | number | 图片实际绘制的宽度。<br/>单位：像素<br>**说明：**<br/>仅在loadingStatus返回1时有效。 | 125| contentHeight<sup>10+</sup> | number | 图片实际绘制的高度。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 126| contentOffsetX<sup>10+</sup> | number | 实际绘制内容相对于组件自身的x轴偏移。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 127| contentOffsetY<sup>10+</sup> | number | 实际绘制内容相对于组件自身的y轴偏移。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 128 129 130### onError<sup>9+</sup> 131 132onError(callback: [ImageErrorCallback](#imageerrorcallback9)) 133 134图片加载异常时触发该回调。 135 136从API version 9开始，该接口支持在ArkTS卡片中使用。 137 138**参数：** 139 140| 参数名 | 类型 | 说明 | 141| -------- | ---------------------------------------- | ------------- | 142| callback | [ImageErrorCallback](#imageerrorcallback9) | 图片加载异常时触发的回调。 | 143 144### onFinish 145 146onFinish(event: () => void) 147 148当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。 149 150仅支持svg格式的图片。 151 152从API version 9开始，该接口支持在ArkTS卡片中使用。 153 154## ImageErrorCallback<sup>9+</sup> 155 156type ImageErrorCallback = (error: [ImageError](#imageerror9)) => void 157 158图片加载异常时触发的回调。 159 160| 参数名 | 类型 | 说明 | 161| ----- | -------------------------- | ----------------- | 162| error | [ImageError](#imageerror9) | 图片加载异常时触发回调的返回对象。 | 163 164## ImageError<sup>9+</sup> 165 166图片加载异常时触发回调的返回对象。 167 168| 参数名 | 类型 | 说明 | 169| --------------- | ------ | --------------- | 170| componentWidth | number | 组件的宽。<br/>单位：像素 | 171| componentHeight | number | 组件的高。<br/>单位：像素 | 172| message | string | 报错信息。 | 173 174## 示例 175 176### 加载基本类型图片 177 178```ts 179@Entry 180@Component 181struct ImageExample1 { 182 build() { 183 Column() { 184 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 185 Row() { 186 // 加载png格式图片 187 Image($r('app.media.ic_camera_master_ai_leaf')) 188 .width(110).height(110).margin(15) 189 .overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 190 // 加载gif格式图片 191 Image($r('app.media.loading')) 192 .width(110).height(110).margin(15) 193 .overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 194 } 195 Row() { 196 // 加载svg格式图片 197 Image($r('app.media.ic_camera_master_ai_clouded')) 198 .width(110).height(110).margin(15) 199 .overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 200 // 加载jpg格式图片 201 Image($r('app.media.ic_public_favor_filled')) 202 .width(110).height(110).margin(15) 203 .overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 204 } 205 } 206 }.height(320).width(360).padding({ right: 10, top: 10 }) 207 } 208} 209``` 210 211 212 213### 加载网络图片 214 215加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。如果需要更灵活的网络配置，可以使用[HTTP](../../../network/http-request.md)工具包发送网络请求，接着将返回的数据解码为Image组件中的`PixelMap`，图片开发可参考[图片处理](../../../media/image/image-overview.md)。 216 217使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 218 219```ts 220@Entry 221@Component 222struct ImageExample2 { 223 build() { 224 Column({ space: 10 }) { 225 Image("https://www.example.com/xxx.png")// 直接加载网络地址，请填写一个具体的网络图片地址 226 .alt($r('app.media.icon'))// 使用alt，在网络图片加载成功前使用占位图 227 .width(100) 228 .height(100) 229 } 230 } 231} 232``` 233 234 235### 为图片添加事件 236 237 238```ts 239@Entry 240@Component 241struct ImageExample3 { 242 private imageOne: Resource = $r('app.media.earth'); 243 private imageTwo: Resource = $r('app.media.star'); 244 private imageThree: Resource = $r('app.media.moveStar'); 245 @State src: Resource = this.imageOne 246 @State src2: Resource = this.imageThree 247 build(){ 248 Column(){ 249 //为图片添加点击事件，点击完成后加载特定图片 250 Image(this.src) 251 .width(100) 252 .height(100) 253 .onClick(() => { 254 this.src = this.imageTwo 255 }) 256 257 //当加载图片为SVG格式时 258 Image(this.src2) 259 .width(100) 260 .height(100) 261 .onClick(() => { 262 //SVG动效播放完成时加载另一张图片 263 this.src2 = this.imageOne 264 }) 265 }.width('100%').height('100%') 266 } 267} 268``` 269 270 271 272### 使用PixelMap开启图像分析 273 274```ts 275import image from '@ohos.multimedia.image' 276@Entry 277@Component 278struct ImageExample4 { 279 @State imagePixelMap: image.PixelMap | undefined = undefined 280 281 async aboutToAppear() { 282 this.imagePixelMap = await this.getPixmapFromMedia($r('app.media.app_icon')) 283 } 284 285 build() { 286 Column() { 287 Image(this.imagePixelMap) 288 .enableAnalyzer(true) 289 .width(200) 290 .height(200) 291 } 292 } 293 private async getPixmapFromMedia(resource: Resource) { 294 let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({ 295 bundleName: resource.bundleName, 296 moduleName: resource.moduleName, 297 id: resource.id 298 }) 299 let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength)) 300 let createPixelMap: image.PixelMap = await imageSource.createPixelMap({ 301 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 302 }) 303 await imageSource.release() 304 return createPixelMap 305 } 306} 307```
