1# Image 2 3Image为图片组件，常用于在应用中显示图片。Image支持加载[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)、[ResourceStr](ts-types.md#resourcestr)和[DrawableDescriptor](#drawabledescriptor10)类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 使用快捷组合键对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，即可实现点击获焦。 10> 11> 图片格式支持SVG图源，SVG标签文档请参考[SVG标签说明](./ts-basic-svg.md)。 12> 13> 动图的播放依赖于Image节点的可见性变化，其默认行为是不播放的。当节点可见时，通过回调启动动画，当节点不可见时，停止动画。可见性状态的判断是通过[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)事件触发的，当可见阈值ratios大于0时，表明Image处于可见状态。 14> 15 16## 需要权限 17 18使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 19 20 21## 子组件 22 23无 24 25 26## 接口 27 28### Image 29 30Image(src: PixelMap | ResourceStr | DrawableDescriptor) 31 32通过图片数据源获取图片，用于后续渲染展示。 33 34Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。 35 36Image组件默认按照居中裁剪，例如组件宽高设置相同，原图长宽不等，此时按照中间区域进行裁剪。 37 38Image加载成功且组件不设置宽高时，其显示大小自适应父组件。 39 40**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 41 42**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 43 44**系统能力：** SystemCapability.ArkUI.ArkUI.Full 45 46**参数：** 47 48| 参数名 | 类型 | 必填 | 说明 | 49| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 50| src | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [ResourceStr](ts-types.md#resourcestr)\| [DrawableDescriptor](#drawabledescriptor10) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br>1. PixelMap格式为像素图，常用于图片编辑的场景。<br>2. ResourceStr包含Resource和string格式。<br>string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。<br>- 支持`Base64`字符串。<br>- 支持file://路径前缀的字符串，[应用沙箱URI](../../apis-core-file-kit/js-apis-file-fileuri.md#constructor10)：file://\<bundleName>/\<sandboxPath>。当访问的路径中包含特殊符号时，需要使用[fileUri.getUriFromPath(path)](../../apis-core-file-kit/js-apis-file-fileuri.md#fileurigeturifrompath)去做转换。同时需要保证目录包路径下的文件有可读权限。<br>Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。<br/>3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)类型可播放PixelMap数组动画。<br>**说明：**<br/>- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。<br/>- ArkTS卡片上不支持http:/\/等网络相关路径前缀和file:/\/路径前缀的字符串。 | 51 52>**说明：** 53> 54> Image直接传入URL可能会带来的潜在性能问题，例如：(1) 大图加载时无法提前下载，白块显示的时间较长；(2) 小图设置同步加载，在弱网环境下，可能会阻塞UI线程造成冻屏问题；(3) 在快速滑动的瀑布流中，无法提前对即将要显示的图片进行下载，导致滑动白块较多；不同场景下，性能问题会有不同的表现，建议将网络下载部分与Image的显示剥离，可提前下载或者异步下载。如果图片加载过程中出现白色块，请参考[Image白块问题解决方案](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-image-white-lump-solution)。如果图片加载时间过长，请参考按照步骤[优化应用预置图片资源加载耗时问题](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-texture-compression-improve-performance)。 55> 56> src由有效切换为无效时，图片保持不动。 57> 58> 当Image组件入参为[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)类型时，只有当PixelMap对象的引用发生变化（即指向一个新的PixelMap实例），Image组件才能感知到数据的变化。仅修改PixelMap对象的内容（如像素值）而不更换对象引用，无法触发数据变化的感知。 59 60### Image<sup>12+</sup> 61 62Image(src: PixelMap | ResourceStr | DrawableDescriptor | ImageContent) 63 64src新增[ImageContent](#imagecontent12)类型，可指定对应的图形内容。 65 66**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 67 68**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 76| src | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [ResourceStr](ts-types.md#resourcestr)\| [DrawableDescriptor](#drawabledescriptor10)\| [ImageContent](#imagecontent12) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br>PixelMap、ResourceStr和DrawableDescriptor的使用请参考[Image](#image-1)的scr参数说明。<br> 传入[ImageContent](#imagecontent12)类型，指定图像内容。<br>**说明：**<br/>- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。<br/>- ArkTS卡片上不支持http:/\/等网络相关路径前缀和file:/\/路径前缀的字符串。 | 77 78### Image<sup>12+</sup> 79 80Image(src: PixelMap | ResourceStr | DrawableDescriptor, imageAIOptions: ImageAIOptions) 81 82Image新增[imageAIOptions](ts-image-common.md#imageaioptions)参数，为组件设置AI分析选项。 83 84**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 85 86**系统能力：** SystemCapability.ArkUI.ArkUI.Full 87 88**参数：** 89 90| 参数名 | 类型 | 必填 | 说明 | 91| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 92| src | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [ResourceStr](ts-types.md#resourcestr)\| [DrawableDescriptor](#drawabledescriptor10) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br>PixelMap、ResourceStr和DrawableDescriptor的使用请参考[Image](#image-1)的scr参数说明。<br>**说明：**<br/>- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。<br/>- ArkTS卡片上不支持http:/\/等网络相关路径前缀和file:/\/路径前缀的字符串。 | 93| imageAIOptions | [ImageAIOptions](ts-image-common.md#imageaioptions) | 是 | 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。 | 94 95## 属性 96 97属性的详细使用指导请参考[添加属性](../../../ui/arkts-graphics-display.md#添加属性)。除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 98 99> **说明：** 100> 101> Image组件不支持设置通用属性[foregroundColor](./ts-universal-attributes-foreground-color.md#foregroundcolor)，可以通过Image组件的[fillColor](#fillcolor)属性设置填充颜色。 102 103### alt 104 105alt(value: string | Resource | PixelMap) 106 107设置图片加载时显示的占位图。 108 109占位图支持使用[objectFit](#objectfit)设置填充效果，与图片的填充效果一致。 110 111当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 112 113**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 114 115**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 116 117**系统能力：** SystemCapability.ArkUI.ArkUI.Full 118 119**参数：** 120 121| 参数名 | 类型 | 必填 | 说明 | 122| ------ | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 123| value | string \| [Resource](ts-types.md#resource) \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)<sup>12+</sup> | 是 | 加载时显示的占位图，支持本地图片（png、jpg、bmp、svg、gif和heif类型）,支持[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)类型图片，不支持网络图片。<br/>默认值：null | 124 125### objectFit 126 127objectFit(value: ImageFit) 128 129设置图片的填充效果。 130 131**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 132 133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| ------ | ----------------------------------------- | ---- | ------------------------------------------- | 141| value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 图片的填充效果。<br/>默认值：ImageFit.Cover | 142 143### imageMatrix<sup>15+</sup> 144 145imageMatrix(matrix: ImageMatrix) 146 147设置图片的变换矩阵。通过[ImageMatrix](#imagematrix15对象说明)对象使用平移、旋转、缩放等函数，实现宫格缩略图的最佳呈现。svg类型图源不支持该属性。 148 149设置resizable、objectRepeat属性时，该属性设置不生效。该属性只针对图源做处理，不会触发Image组件的回调事件。 150 151该属性与[objectFit](#objectfit)属性强关联，仅在[objectFit](#objectfit)属性设置为[ImageFit](ts-appendix-enums.md#imagefit).MATRIX时生效。 152 153**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 154 155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| ------ | --------------------------------------------------- | ---- | -------------- | 161| matrix | [ImageMatrix](#imagematrix15对象说明) | 是 | 图片的变换矩阵。| 162 163### objectRepeat 164 165objectRepeat(value: ImageRepeat) 166 167设置图片的重复样式，从中心点向两边重复，剩余空间不足放下一张图片时会截断。svg类型图源不支持该属性。 168 169当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 170 171**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 172 173**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 174 175**系统能力：** SystemCapability.ArkUI.ArkUI.Full 176 177**参数：** 178 179| 参数名 | 类型 | 必填 | 说明 | 180| ------ | ----------------------------------------------- | ---- | ------------------------------------------------- | 181| value | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 是 | 图片的重复样式。<br/>默认值：ImageRepeat.NoRepeat | 182 183### interpolation 184 185interpolation(value: ImageInterpolation) 186 187设置图片的插值效果，即缓解图片在缩放时的锯齿问题。svg类型图源不支持该属性。 188 189当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 190 191**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 192 193**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 194 195**系统能力：** SystemCapability.ArkUI.ArkUI.Full 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| ------ | ----------------------------------------- | ---- | --------------------------------------------------- | 201| value | [ImageInterpolation](#imageinterpolation) | 是 | 图片的插值效果。<br/>默认值：ImageInterpolation.Low | 202 203### renderMode 204 205renderMode(value: ImageRenderMode) 206 207设置图片的渲染模式。svg类型图源不支持该属性。 208 209设置 [ColorFilter](#colorfilter9) 时，该属性设置不生效。 210 211当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 212 213**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 214 215**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 216 217**系统能力：** SystemCapability.ArkUI.ArkUI.Full 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 223| value | [ImageRenderMode](#imagerendermode) | 是 | 图片的渲染模式为原色或黑白。<br/>默认值：ImageRenderMode.Original | 224 225### sourceSize 226 227sourceSize(value: ImageSourceSize) 228 229设置图片解码尺寸。仅在目标尺寸小于图源尺寸时生效。svg类型图源和PixelMap资源不支持该属性。 230 231当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 232 233**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 234 235**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 243| value | [ImageSourceSize](#imagesourcesize18对象说明) | 是 | 图片解码尺寸参数，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。 | 244 245### matchTextDirection 246 247matchTextDirection(value: boolean) 248 249设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。 250 251当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 252 253**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 254 255**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.ArkUI.ArkUI.Full 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| ------ | ------- | ---- | -------------------------------------------- | 263| value | boolean | 是 | 图片是否跟随系统语言方向。<br/>默认值：false，false表示图片不跟随系统语言方向，true表示图片跟随系统语言方向。 | 264 265### fitOriginalSize 266 267fitOriginalSize(value: boolean) 268 269设置图片的显示尺寸是否跟随图源尺寸。图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。 270 271当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 272 273**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 274 275**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 276 277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| ------ | ------- | ---- | ------------------------------------------------ | 283| value | boolean | 是 | 图片的显示尺寸是否跟随图源尺寸。<br/>默认值：false <br/>**说明：**<br/>当不设置fitOriginalSize或者设置fitOriginalSize为false时，组件显示大小不跟随图源大小。<br/> 当设置fitOriginalSize为true时，组件显示大小跟随图源大小。 | 284 285### fillColor 286 287fillColor(value: ResourceColor) 288 289设置填充颜色，设置后填充颜色会覆盖在图片上。仅对svg图源生效，设置后会替换svg图片中所有可绘制元素的填充颜色。如需对png图片进行修改颜色，可以使用[colorFilter](#colorfilter9)。 290 291当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 292 293**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 294 295**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 296 297**系统能力：** SystemCapability.ArkUI.ArkUI.Full 298 299**参数：** 300 301| 参数名 | 类型 | 必填 | 说明 | 302| ------ | ------------------------------------------ | ---- | -------------- | 303| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置填充颜色。 <br/>**说明：**<br/> 默认不对组件进行填充。当传入异常值时，系统将使用默认的主题色：浅色模式下为黑色，深色模式下为白色。| 304 305### fillColor<sup>15+</sup> 306 307fillColor(color: ResourceColor|ColorContent) 308 309设置填充颜色，设置后填充颜色会覆盖在图片上。仅对svg图源生效，设置后会替换svg图片中所有可绘制元素的填充颜色。如需对png图片进行修改颜色，可以使用[colorFilter](#colorfilter9)。如果想重置填充颜色可以传入[ColorContent](#colorcontent15)类型。 310 311当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 312 313**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 314 315**系统能力：** SystemCapability.ArkUI.ArkUI.Full 316 317**参数：** 318 319| 参数名 | 类型 | 必填 | 说明 | 320| ------ | ------------------------------------------ | ---- | -------------- | 321| color | [ResourceColor](ts-types.md#resourcecolor)\|[ColorContent](#colorcontent15) | 是 | 设置填充颜色。 <br/>**说明：**<br/> 默认不对组件进行填充。当传入异常值时，系统将使用默认的主题色：浅色模式下为黑色，深色模式下为白色。 | 322 323### autoResize 324 325autoResize(value: boolean) 326 327设置图片解码过程中是否对图源自动缩放。降采样解码时图片的部分信息丢失，因此可能会导致图片质量的下降（如：出现锯齿），这时可以选择把autoResize设为false，按原图尺寸解码，提升显示效果，但会增加内存占用。 328 329原图尺寸和显示尺寸不匹配时，图片都会出现些许的失真、模糊。最佳清晰度配置建议： 330 331图片缩小显示时：.autoResize(false) + .interpolation(.Medium) 332 333图片放大显示时：.interpolation(.High) 334 335当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)和svg时设置该属性不生效。 336 337**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 338 339**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 340 341**系统能力：** SystemCapability.ArkUI.ArkUI.Full 342 343**参数：** 344 345| 参数名 | 类型 | 必填 | 说明 | 346| ------ | ------- | ---- | ------------------------------------------------------------ | 347| value | boolean | 是 | 图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会降采样解码到200x200的尺寸，大幅度节省图片占用的内存。<br/>默认值：false，false表示关闭图源自动缩放，true表示开启图源自动缩放。 | 348 349### syncLoad<sup>8+</sup> 350 351syncLoad(value: boolean) 352 353设置是否同步加载图片。建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。 354 355当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 356 357**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 358 359**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 360 361**系统能力：** SystemCapability.ArkUI.ArkUI.Full 362 363**参数：** 364 365| 参数名 | 类型 | 必填 | 说明 | 366| ------ | ------- | ---- | ------------------------------------------------------------ | 367| value | boolean | 是 | 是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。<br/>默认值：false，fasle表示异步加载图片，true表示同步加载图片。 | 368 369### copyOption<sup>9+</sup> 370 371copyOption(value: CopyOptions) 372 373设置图片是否可复制。当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。svg图片不支持复制。 374 375当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 376 377**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 378 379**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 380 381**系统能力：** SystemCapability.ArkUI.ArkUI.Full 382 383**参数：** 384 385| 参数名 | 类型 | 必填 | 说明 | 386| ------ | ------------------------------------------------ | ---- | --------------------------------------------- | 387| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 是 | 图片是否可复制。<br/>默认值：CopyOptions.None | 388 389### colorFilter<sup>9+</sup> 390 391colorFilter(value: ColorFilter | DrawingColorFilter) 392 393为图像设置颜色滤镜效果。 394 395设置该属性时，[renderMode](#rendermode)属性设置不生效。 396 397**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 398 399**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 400 401**系统能力：** SystemCapability.ArkUI.ArkUI.Full 402 403**参数：** 404 405| 参数名 | 类型 | 必填 | 说明 | 406| ------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 407| value | [ColorFilter](ts-types.md#colorfilter9) \| [DrawingColorFilter](#drawingcolorfilter12) | 是 | 1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。<br/>矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。<br/>当矩阵对角线值为1，其余值为0时，保持图片原有色彩。<br/> **计算规则：**<br/>如果输入的滤镜矩阵如下（其中矩阵值的范围[0, 1]）：<br/> <br/>像素点为[R, G, B, A]，色值的范围[0, 255]<br/>则过滤后的颜色为 [R’, G’, B’, A’]<br/><br/>2. 从API Version12开始支持@ohos.graphics.drawing的ColorFilter类型作为入参。<br/>**说明：** <br/>API Version 11及之前，svg类型图源不支持该属性。<br/>从API version 12开始，该接口中的DrawingColorfilter类型支持在原子化服务中使用。其中，svg类型的图源只对stroke属性生效。| 408### draggable<sup>9+</sup> 409 410draggable(value: boolean) 411 412设置组件默认拖拽效果。不能和[onDragStart](ts-universal-events-drag-drop.md#ondragstart)事件同时使用。 413 414**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 415 416**系统能力：** SystemCapability.ArkUI.ArkUI.Full 417 418**参数：** 419 420| 参数名 | 类型 | 必填 | 说明 | 421| ------ | ------- | ---- | ------------------------------------------------------------ | 422| value | boolean | 是 | 组件默认拖拽效果，设置为true时，组件可拖拽，绑定的长按手势不生效。<br />API version 9及之前，默认值为false。API version 10及之后，默认值为true。<br /> 若用户需要设置自定义手势，则需要将draggable设置为false。 | 423 424### enableAnalyzer<sup>11+</sup> 425 426enableAnalyzer(enable: boolean) 427 428设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。<!--RP3--><!--RP3End--> 429 430不能和[overlay](ts-universal-attributes-overlay.md)属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。 431 432分析图像要求是静态非矢量图，即svg、gif等图像类型不支持分析，支持传入[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)进行分析，目前仅支持[RGBA_8888](../../apis-image-kit/js-apis-image.md#pixelmapformat7)类型，使用方式见[示例4](#示例4开启图像ai分析)。 433 434alt占位图不支持分析，objectRepeat属性仅在ImageRepeat.NoRepeat下支持分析，隐私遮罩属性[obscured](ts-universal-attributes-obscured.md)打开时不支持分析。 435 436基于完整原始图像进行分析，设置clip、margin、borderRadius、position和objectFit属性导致图像显示不完整，或使用renderMode设置蒙层，仍基于完整原始图像进行分析。 copyOption属性不影响AI分析功能。 437 438当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 439 440> **说明：** 441> 442> 需要配置权限：ohos.permission.INTERNET。 443 444**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 445 446**系统能力：** SystemCapability.ArkUI.ArkUI.Full 447 448**参数：** 449 450| 参数名 | 类型 | 必填 | 说明 | 451| ------ | ------- | ---- | ------------------------------------------------------------ | 452| enable | boolean | 是 | 组件支持AI分析，设置为true时，组件可进行AI分析。<br/>默认值：false，表示不开启AI分析。 | 453 454### resizable<sup>11+</sup> 455 456resizable(value: ResizableOptions) 457 458设置图像拉伸时可调整大小的图像选项。拉伸对拖拽缩略图以及占位图有效。 459 460设置合法的 [ResizableOptions](#resizableoptions11) 时，objectRepeat 属性设置不生效。 461 462当设置 top +bottom 大于原图的高或者 left + right 大于原图的宽时 [ResizableOptions](#resizableoptions11) 属性设置不生效。 463 464当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)和svg时设置该属性不生效。 465 466**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 467 468**系统能力：** SystemCapability.ArkUI.ArkUI.Full 469 470**参数：** 471 472| 参数名 | 类型 | 必填 | 说明 | 473| ------ | --------------------------------------- | ---- | -------------------------------- | 474| value | [ResizableOptions](#resizableoptions11) | 是 | 图像拉伸时可调整大小的图像选项。 | 475 476### privacySensitive<sup>12+</sup> 477 478privacySensitive(supported: boolean) 479 480设置是否支持卡片敏感隐私信息。 481 482**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 483 484**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 485 486**系统能力：** SystemCapability.ArkUI.ArkUI.Full 487 488**参数：** 489 490| 参数名 | 类型 | 必填 | 说明 | 491| --------- | ------- | ---- | ------------------------ | 492| supported | boolean | 是 | 是否支持卡片敏感隐私信息。<br/>默认值为false，当设置为true时，隐私模式下图片将显示为半透明底板样式。<br/>**说明：** <br/>设置null则不敏感。<br/>进入隐私模式需要[卡片框架支持](./ts-universal-attributes-obscured.md)。 | 493 494### dynamicRangeMode<sup>12+</sup> 495 496dynamicRangeMode(value: DynamicRangeMode) 497 498设置期望展示的图像动态范围。svg类型图源不支持该属性。 499 500<!--RP1--><!--RP1End--> 501 502**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 503 504**系统能力：** SystemCapability.ArkUI.ArkUI.Full 505 506**参数：** 507 508| 参数名 | 类型 | 必填 | 说明 | 509| ------ | --------------------------------------- | ---- | -------------------------------- | 510| value | [DynamicRangeMode](#dynamicrangemode12枚举说明) | 是 | 图像显示的动态范围。<br/>默认值：dynamicRangeMode.Standard | 511 512### orientation<sup>14+</sup> 513 514orientation(orientation: ImageRotateOrientation) 515 516设置图像内容的显示方向。 517 518**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 519 520**系统能力：** SystemCapability.ArkUI.ArkUI.Full 521 522**参数：** 523 524| 参数名 | 类型 | 必填 | 说明 | 525| ------ | --------------------------------------- | ---- | -------------------------------- | 526| orientation | [ImageRotateOrientation](#imagerotateorientation14) | 是 | 图像内容的显示方向。<br/>如果需要显示携带旋转角度信息的图片，建议使用ImageRotateOrientation.AUTO进行设置。<br/>默认值：ImageRotateOrientation.UP | 527 528## ImageContent<sup>12+</sup> 529 530指定图像内容。 531 532**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 533 534**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 535 536**系统能力：** SystemCapability.ArkUI.ArkUI.Full 537 538| 名称 | 值 | 说明 | 539| ------ | ----- | -------------------------- | 540| EMPTY | 0 | 空图像。 | 541 542## ImageInterpolation 543 544**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 545 546**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 547 548**系统能力：** SystemCapability.ArkUI.ArkUI.Full 549 550| 名称 | 说明 | 551| ------ | -------------------------- | 552| None | 最近邻插值。 | 553| High | Cubic插值，插值质量最高，可能会影响图片渲染的速度。 | 554| Medium | MipMap插值。 | 555| Low | 双线性插值。 | 556 557## ImageRenderMode 558 559**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 560 561**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 562 563**系统能力：** SystemCapability.ArkUI.ArkUI.Full 564 565| 名称 | 说明 | 566| -------- | -------------- | 567| Original | 原色渲染模式。 | 568| Template | 黑白渲染模式。 | 569 570## ResizableOptions<sup>11+</sup> 571 572图像拉伸时可调整大小的图像选项。 573 574**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 575 576**系统能力：** SystemCapability.ArkUI.ArkUI.Full 577 578| 名称 | 类型 | 必填 | 说明 | 579| --------- |-----------|-----------|-----------| 580| slice | [EdgeWidths](#edgewidths参数说明) | 否 | 边框宽度类型，用于描述组件边框不同方向的宽度。<br>**说明：**<br>只有当bottom和right同时大于0时，该属性生效。<br> 传入数字时默认单位为vp。| 581| lattice<sup>12+</sup> | [DrawingLattice](#drawinglattice12) | 否 | 矩形网格对象。<br>**说明：**<br> 通过@ohos.graphics.drawing的createImageLattice接口创建Lattice类型作为入参。将图像划分为矩形网格，同时处于偶数列和偶数行上的网格图像是固定的，不会被拉伸。<br>该参数对[backgroundImageResizable](ts-universal-attributes-background.md#backgroundimageresizable12)接口不生效。<br> 传入数字时默认单位为px。 | 582 583## EdgeWidths参数说明 584 585**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 586 587**系统能力：** SystemCapability.ArkUI.ArkUI.Full 588 589| 名称 | 类型 | 必填 | 说明 | 590| --------- |-----------|-----------|-----------| 591| top | [Length](ts-types.md#length) | 否 | 图片顶部拉伸时，图片的像素值保持不变。<br>默认值：0<br>单位：vp | 592| right | [Length](ts-types.md#length) | 否 | 图片右部拉伸时，图片的像素值保持不变。<br>默认值：0<br>单位：vp | 593| bottom | [Length](ts-types.md#length) | 否 | 图片底部拉伸时，图片的像素值保持不变。<br>默认值：0<br>单位：vp | 594| left | [Length](ts-types.md#length) | 否 | 图片左部拉伸时，图片的像素值保持不变。<br>默认值：0<br>单位：vp | 595 596 597 598## DynamicRangeMode<sup>12+</sup>枚举说明 599 600期望展示的图像动态范围。 601 602**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 603 604**系统能力：** SystemCapability.ArkUI.ArkUI.Full 605 606| 名称 | 值 | 说明 | 607| ------ | -------------------------- | -------------------------- | 608| HIGH | 0 | 不受限动态范围，最大限度进行图片提亮。 | 609| CONSTRAINT | 1 | 受限动态范围，受限进行图片提亮。 | 610| STANDARD | 2 | 标准动态范围，不进行图片提亮。 | 611 612## ImageRotateOrientation<sup>14+</sup> 613 614期望的图像内容显示方向。 615 616**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 617 618**系统能力：** SystemCapability.ArkUI.ArkUI.Full 619 620| 名称 | 值 | 说明 | 621| ------ | -------------------------- | -------------------------- | 622| AUTO | 0 | 读取图片携带的EXIF元数据作为显示方向。 | 623| UP | 1 | 默认按照当前图片进行显示，不做任何EXIF处理。 | 624| RIGHT | 2 | 将当前图片向右旋转90度后显示。 | 625| DOWN | 3| 将当前图片旋转180度后显示。 | 626| LEFT | 4 | 将当前图片向左旋转90度后显示。 | 627 628## ImageSourceSize<sup>18+</sup>对象说明 629 630**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 631 632**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 633 634**系统能力：** SystemCapability.ArkUI.ArkUI.Full 635 636| 名称 | 类型 | 必填 | 说明 | 637| ------ | --------- | ---- | ------------- | 638| width<sup>7+</sup> | number | 是 | 图片解码尺寸宽度。<br/>单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 639| height<sup>7+</sup> | number | 是 | 图片解码尺寸高度。<br/>单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 640 641## DrawableDescriptor<sup>10+<sup> 642 643type DrawableDescriptor = DrawableDescriptor 644 645作为Image组件的入参对象。 646 647**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 648 649**系统能力：** SystemCapability.ArkUI.ArkUI.Full 650 651| 类型 | 说明 | 652| ------ | ---------- | 653| [DrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | 返回一个DrawableDescriptor对象。 | 654 655## DrawingColorFilter<sup>12+<sup> 656 657type DrawingColorFilter = ColorFilter 658 659颜色滤波器对象。 660 661**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 662 663**系统能力：** SystemCapability.ArkUI.ArkUI.Full 664 665| 类型 | 说明 | 666| ------ | ---------- | 667| [ColorFilter](../../apis-arkgraphics2d/js-apis-graphics-drawing.md#colorfilter) | 返回一个颜色滤波器。 | 668 669## DrawingLattice<sup>12+<sup> 670 671type DrawingLattice = Lattice 672 673将图片按照矩形网格进行划分。 674 675**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 676 677**系统能力：** SystemCapability.ArkUI.ArkUI.Full 678 679| 类型 | 说明 | 680| ------ | ---------- | 681| [Lattice](../../apis-arkgraphics2d/js-apis-graphics-drawing.md#lattice12) | 返回一个矩阵网格对象。 | 682 683## ImageMatrix<sup>15+</sup>对象说明 684 685type ImageMatrix = Matrix4Transit 686 687当前的矩阵对象。 688 689**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 690 691**系统能力：** SystemCapability.ArkUI.ArkUI.Full 692 693| 类型 | 说明 | 694| ------ | ---------- | 695| [Matrix4Transit](../js-apis-matrix4.md#matrix4transit) | 返回当前的矩阵对象。 | 696 697## ColorContent<sup>15+</sup> 698 699指定颜色填充内容。 700 701**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 702 703**系统能力：** SystemCapability.ArkUI.ArkUI.Full 704 705| 名称 | 类型 | 必填 | 说明 | 706| ------ | --------- | --- | ------------- | 707| ORIGIN | ColorContent | 是 | 重置[fillColor](#fillcolor)接口，效果上与不设置[fillColor](#fillcolor)一致。 | 708 709## 事件 710 711除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 712 713### onComplete 714 715onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number }) => void) 716 717图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 718 719当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 720 721**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 722 723**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 724 725**系统能力：** SystemCapability.ArkUI.ArkUI.Full 726 727**参数：** 728 729| 参数名 | 类型 | 必填 | 说明 | 730| ---------------------------- | ------ | ---- | ------------------------------------------------------------ | 731| width | number | 是 | 图片的宽。<br/>单位：像素 | 732| height | number | 是 | 图片的高。<br/>单位：像素 | 733| componentWidth | number | 是 | 组件的宽。<br/>单位：像素 | 734| componentHeight | number | 是 | 组件的高。<br/>单位：像素 | 735| loadingStatus | number | 是 | 图片加载成功的状态值。<br/>**说明：**<br/>返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | 736| contentWidth<sup>10+</sup> | number | 是 | 图片实际绘制的宽度。<br/>单位：像素<br>**说明：**<br/>仅在loadingStatus返回1时有效。 | 737| contentHeight<sup>10+</sup> | number | 是 | 图片实际绘制的高度。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 738| contentOffsetX<sup>10+</sup> | number | 是 | 实际绘制内容相对于组件自身的x轴偏移。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 739| contentOffsetY<sup>10+</sup> | number | 是 | 实际绘制内容相对于组件自身的y轴偏移。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 740 741### onError<sup>9+</sup> 742 743onError(callback: ImageErrorCallback) 744 745图片加载异常时触发该回调。 746 747当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 748 749**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 750 751**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 752 753**系统能力：** SystemCapability.ArkUI.ArkUI.Full 754 755**参数：** 756 757| 参数名 | 类型 | 必填 | 说明 | 758| -------- | ------------------------------------------ | ---- | -------------------------- | 759| callback | [ImageErrorCallback](#imageerrorcallback9) | 是 | 图片加载异常时触发的回调。<br>**说明：**<br/>建议开发者使用此回调，可快速确认图片加载失败时的具体原因。 | 760 761### onFinish 762 763onFinish(event: () => void) 764 765当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。 766 767仅支持svg格式的图片。当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 768 769**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 770 771**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 772 773**系统能力：** SystemCapability.ArkUI.ArkUI.Full 774 775## ImageErrorCallback<sup>9+</sup> 776 777type ImageErrorCallback = (error: ImageError) => void 778 779图片加载异常时触发的回调。 780 781当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 782 783**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 784 785**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 786 787**系统能力：** SystemCapability.ArkUI.ArkUI.Full 788 789| 参数名 | 类型 | 必填 | 说明 | 790| ------ | -------------------------- | ---- | ---------------------------------- | 791| error | [ImageError](#imageerror9) | 是 | 图片加载异常时触发回调的返回对象。 | 792 793## ImageError<sup>9+</sup> 794 795图片加载异常时触发回调的返回对象。 796 797当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 798 799**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 800 801**系统能力：** SystemCapability.ArkUI.ArkUI.Full 802 803| 名称 | 类型 | 必填 | 说明 | 804| --------------- | ------ | ---- | ------------------------- | 805| componentWidth | number | 是 | 组件的宽。<br/>单位：像素<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 806| componentHeight | number | 是 | 组件的高。<br/>单位：像素<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 807| message<sup>10+</sup> | string | 是 | 报错信息。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 | 808 809## 示例 810 811### 示例1（加载基本类型图片） 812 813加载png、gif、svg和jpg等基本类型的图片。 814 815```ts 816@Entry 817@Component 818struct ImageExample1 { 819 build() { 820 Column() { 821 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 822 Row() { 823 // 加载png格式图片 824 Image($r('app.media.ic_camera_master_ai_leaf')) 825 .width(110).height(110).margin(15) 826 .overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 827 // 加载gif格式图片 828 Image($r('app.media.loading')) 829 .width(110).height(110).margin(15) 830 .overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 831 } 832 Row() { 833 // 加载svg格式图片 834 Image($r('app.media.ic_camera_master_ai_clouded')) 835 .width(110).height(110).margin(15) 836 .overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 837 // 加载jpg格式图片 838 Image($r('app.media.ic_public_favor_filled')) 839 .width(110).height(110).margin(15) 840 .overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 841 } 842 } 843 }.height(320).width(360).padding({ right: 10, top: 10 }) 844 } 845} 846``` 847 848 849 850### 示例2（下载与显示网络图片） 851 852加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。使用[HTTP](../../../network/http-request.md)工具包发送网络请求，接着将返回的数据解码为Image组件中的`PixelMap`，图片开发可参考[图片处理](../../../media/image/image-overview.md)。 853 854使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 855 856```ts 857import { http } from '@kit.NetworkKit'; 858import { BusinessError } from '@kit.BasicServicesKit'; 859import { image } from '@kit.ImageKit'; 860 861@Entry 862@Component 863struct ImageExample2 { 864 @State pixelMapImg: PixelMap | undefined = undefined; 865 866 aboutToAppear() { 867 this.requestImageUrl('https://www.example.com/xxx.png');// 请填写一个具体的网络图片地址 868 } 869 870 requestImageUrl(url: string) { 871 http.createHttp().request(url, (error: BusinessError, data: http.HttpResponse)=> { 872 if (error) { 873 console.error(`request image failed: url: ${url}, code: ${error.code}, message: ${error.message}`); 874 } else { 875 let imgData: ArrayBuffer = data.result as ArrayBuffer; 876 console.info(`request image success, size: ${imgData.byteLength}`); 877 let imgSource: image.ImageSource = image.createImageSource(imgData); 878 class sizeTmp { 879 height: number = 100 880 width: number = 100 881 } 882 let options: Record<string, number | boolean | sizeTmp> = { 883 'alphaType': 0, 884 'editable': false, 885 'pixelFormat': 3, 886 'scaleMode': 1, 887 'size': { height: 100, width: 100 } 888 } 889 imgSource.createPixelMap(options).then((pixelMap: PixelMap) => { 890 console.error('image createPixelMap success'); 891 this.pixelMapImg = pixelMap; 892 }) 893 imgSource.release() 894 } 895 }) 896 } 897 898 build() { 899 Column() { 900 Image(this.pixelMapImg) 901 .alt($r('app.media.img')) 902 .objectFit(ImageFit.None) 903 .width('100%') 904 .height('100%') 905 } 906 } 907} 908``` 909 910 911 912### 示例3（为图片添加事件） 913 914为图片添加onClick和onFinish事件。 915 916```ts 917@Entry 918@Component 919struct ImageExample3 { 920 private imageOne: Resource = $r('app.media.earth'); 921 private imageTwo: Resource = $r('app.media.star'); 922 private imageThree: Resource = $r('app.media.moveStar'); 923 @State src: Resource = this.imageOne 924 @State src2: Resource = this.imageThree 925 build(){ 926 Column(){ 927 // 为图片添加点击事件，点击完成后加载特定图片 928 Image(this.src) 929 .width(100) 930 .height(100) 931 .onClick(() => { 932 this.src = this.imageTwo 933 }) 934 935 // 当加载图片为SVG格式时 936 Image(this.src2) 937 .width(100) 938 .height(100) 939 .onFinish(() => { 940 // SVG动效播放完成时加载另一张图片 941 this.src2 = this.imageOne 942 }) 943 }.width('100%').height('100%') 944 } 945} 946``` 947 948 949 950### 示例4（开启图像AI分析） 951<!--RP2--> 952使用enableAnalyzer接口开启图像AI分析。 953 954```ts 955import { image } from '@kit.ImageKit' 956 957@Entry 958@Component 959struct ImageExample4 { 960 @State imagePixelMap: image.PixelMap | undefined = undefined 961 private aiController: ImageAnalyzerController = new ImageAnalyzerController() 962 private options: ImageAIOptions = { 963 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 964 aiController: this.aiController 965 } 966 967 async aboutToAppear() { 968 this.imagePixelMap = await this.getPixmapFromMedia($r('app.media.app_icon')) 969 } 970 971 build() { 972 Column() { 973 Image(this.imagePixelMap, this.options) 974 .enableAnalyzer(true) 975 .width(200) 976 .height(200) 977 .margin({bottom:10}) 978 Button('getTypes') 979 .width(80) 980 .height(80) 981 .onClick(() => { 982 this.aiController.getImageAnalyzerSupportTypes() 983 }) 984 } 985 } 986 private async getPixmapFromMedia(resource: Resource) { 987 let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent({ 988 bundleName: resource.bundleName, 989 moduleName: resource.moduleName, 990 id: resource.id 991 }) 992 let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength)) 993 let createPixelMap: image.PixelMap = await imageSource.createPixelMap({ 994 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 995 }) 996 await imageSource.release() 997 return createPixelMap 998 } 999} 1000``` 1001 1002 1003<!--RP2End--> 1004### 示例5（通过slice拉伸图片） 1005 1006调整不同方向对图片进行拉伸。 1007 1008```ts 1009@Entry 1010@Component 1011struct Index { 1012 @State top: number = 10 1013 @State bottom: number = 10 1014 @State left: number = 10 1015 @State right: number = 10 1016 1017 build() { 1018 Column({ space: 5 }) { 1019 // 原图效果 1020 Image($r("app.media.landscape")) 1021 .width(200).height(200) 1022 .border({ width: 2, color: Color.Pink }) 1023 .objectFit(ImageFit.Contain) 1024 1025 // 图像拉伸效果，设置resizable属性，对图片不同方向进行拉伸 1026 Image($r("app.media.landscape")) 1027 .resizable({ 1028 slice: { 1029 left: this.left, 1030 right: this.right, 1031 top: this.top, 1032 bottom: this.bottom 1033 } 1034 }) 1035 .width(200) 1036 .height(200) 1037 .border({ width: 2, color: Color.Pink }) 1038 .objectFit(ImageFit.Contain) 1039 1040 Row() { 1041 Button("add top to " + this.top).fontSize(10) 1042 .onClick(() => { 1043 this.top += 10 1044 }) 1045 Button("add bottom to " + this.bottom).fontSize(10) 1046 .onClick(() => { 1047 this.bottom += 10 1048 }) 1049 } 1050 1051 Row() { 1052 Button("add left to " + this.left).fontSize(10) 1053 .onClick(() => { 1054 this.left += 10 1055 }) 1056 Button("add right to " + this.right).fontSize(10) 1057 .onClick(() => { 1058 this.right += 10 1059 }) 1060 } 1061 1062 } 1063 .justifyContent(FlexAlign.Start).width('100%').height('100%') 1064 } 1065} 1066``` 1067 1068 1069 1070### 示例6（通过lattice拉伸图片） 1071 1072使用矩形网格对象对图片进行拉伸。 1073 1074```ts 1075import { drawing } from '@kit.ArkGraphics2D' 1076 1077@Entry 1078@Component 1079struct drawingLatticeTest { 1080 private xDivs: Array<number> = [1, 2, 200] 1081 private yDivs: Array<number> = [1, 2, 200] 1082 private fXCount: number = 3 1083 private fYCount: number = 3 1084 private DrawingLatticeFirst: DrawingLattice = 1085 drawing.Lattice.createImageLattice(this.xDivs, this.yDivs, this.fXCount, this.fYCount) 1086 1087 build() { 1088 Scroll() { 1089 Column({ space: 10 }) { 1090 Text('Original Image').fontSize(20).fontWeight(700) 1091 Column({ space: 10 }) { 1092 Image($r('app.media.mountain')) 1093 .width(260).height(260) 1094 }.width('100%') 1095 1096 Text('Resize by lattice').fontSize(20).fontWeight(700) 1097 Column({ space: 10 }) { 1098 Image($r('app.media.mountain')) 1099 .objectRepeat(ImageRepeat.X) 1100 .width(260) 1101 .height(260) 1102 .resizable({ 1103 lattice: this.DrawingLatticeFirst 1104 }) 1105 }.width('100%') 1106 }.width('100%') 1107 } 1108 } 1109} 1110``` 1111 1112 1113 1114### 示例7（播放PixelMap数组动画） 1115 1116该示例通过[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)播放PixelMap数组动画。 1117 1118```ts 1119import {AnimationOptions, AnimatedDrawableDescriptor} from '@kit.ArkUI' 1120import { image } from '@kit.ImageKit' 1121 1122@Entry 1123@Component 1124struct ImageExample { 1125 pixelmaps: Array<PixelMap> = []; 1126 options: AnimationOptions = { iterations: 1 }; 1127 @State animated: AnimatedDrawableDescriptor | undefined = undefined; 1128 1129 async aboutToAppear() { 1130 this.pixelmaps = await this.getPixelMaps(); 1131 this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options); 1132 } 1133 1134 build() { 1135 Column() { 1136 Row() { 1137 Image(this.animated) 1138 .width('500px').height('500px') 1139 .onFinish(() => { 1140 console.info("finish") 1141 }) 1142 }.height('50%') 1143 Row() { 1144 Button('once').width(100).padding(5).onClick(() => { 1145 this.options = { iterations: 1 }; 1146 this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options); 1147 }).margin(5) 1148 Button('infinite').width(100).padding(5).onClick(() => { 1149 this.options = { iterations: -1 }; 1150 this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options); 1151 }).margin(5) 1152 } 1153 }.width('50%') 1154 } 1155 1156 private async getPixmapListFromMedia(resource: Resource) { 1157 let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent({ 1158 bundleName: resource.bundleName, 1159 moduleName: resource.moduleName, 1160 id: resource.id 1161 }) 1162 let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength)) 1163 let createPixelMap: Array<image.PixelMap> = await imageSource.createPixelMapList({ 1164 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 1165 }) 1166 await imageSource.release() 1167 return createPixelMap 1168 } 1169 1170 private async getPixmapFromMedia(resource: Resource) { 1171 let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent({ 1172 bundleName: resource.bundleName, 1173 moduleName: resource.moduleName, 1174 id: resource.id 1175 }) 1176 let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength)) 1177 let createPixelMap: image.PixelMap = await imageSource.createPixelMap({ 1178 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 1179 }) 1180 await imageSource.release() 1181 return createPixelMap 1182 } 1183 1184 private async getPixelMaps() { 1185 let Mypixelmaps:Array<PixelMap> = await this.getPixmapListFromMedia($r('app.media.mountain'))//添加图片 1186 Mypixelmaps.push(await this.getPixmapFromMedia($r('app.media.sky'))) 1187 Mypixelmaps.push(await this.getPixmapFromMedia($r('app.media.clouds'))) 1188 Mypixelmaps.push(await this.getPixmapFromMedia($r('app.media.landscape'))) 1189 return Mypixelmaps; 1190 } 1191} 1192``` 1193 1194 1195 1196### 示例8（为图像设置颜色滤镜效果） 1197 1198该示例通过[colorFilter](#colorfilter9)实现了给图像设置颜色滤镜效果。 1199 1200```ts 1201import { drawing, common2D } from '@kit.ArkGraphics2D'; 1202 1203@Entry 1204@Component 1205struct ImageExample3 { 1206 private imageOne: Resource = $r('app.media.1'); 1207 private imageTwo: Resource = $r('app.media.2'); 1208 @State src: Resource = this.imageOne 1209 @State src2: Resource = this.imageTwo 1210 private ColorFilterMatrix: number[] = [1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0] 1211 private color: common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }; 1212 @State DrawingColorFilterFirst: ColorFilter | undefined = undefined 1213 @State DrawingColorFilterSecond: ColorFilter | undefined = undefined 1214 @State DrawingColorFilterThird: ColorFilter | undefined = undefined 1215 1216 build() { 1217 Column() { 1218 Image(this.src) 1219 .width(100) 1220 .height(100) 1221 .colorFilter(this.DrawingColorFilterFirst) 1222 .onClick(()=>{ 1223 this.DrawingColorFilterFirst = drawing.ColorFilter.createBlendModeColorFilter(this.color, drawing.BlendMode.SRC_IN); 1224 }) 1225 1226 Image(this.src2) 1227 .width(100) 1228 .height(100) 1229 .colorFilter(this.DrawingColorFilterSecond) 1230 .onClick(()=>{ 1231 this.DrawingColorFilterSecond = new ColorFilter(this.ColorFilterMatrix); 1232 }) 1233 1234 //当加载图片为SVG格式时 1235 Image($r('app.media.test_self')) 1236 .width(110).height(110).margin(15) 1237 .colorFilter(this.DrawingColorFilterThird) 1238 .onClick(()=>{ 1239 this.DrawingColorFilterThird = drawing.ColorFilter.createBlendModeColorFilter(this.color, drawing.BlendMode.SRC_IN); 1240 }) 1241 } 1242 } 1243} 1244``` 1245 1246 1247### 示例9（为图像设置填充效果） 1248 1249该示例通过[objectFit](#objectfit)为图像设置填充效果。 1250 1251```ts 1252@Entry 1253@Component 1254struct ImageExample{ 1255 build() { 1256 Column() { 1257 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 1258 Row() { 1259 // 加载png格式图片 1260 Image($r('app.media.sky')) 1261 .width(110).height(110).margin(15) 1262 .overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1263 .border({ width: 2, color: Color.Pink }) 1264 .objectFit(ImageFit.TOP_START) 1265 // 加载gif格式图片 1266 Image($r('app.media.loading')) 1267 .width(110).height(110).margin(15) 1268 .overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1269 .border({ width: 2, color: Color.Pink }) 1270 .objectFit(ImageFit.BOTTOM_START) 1271 } 1272 Row() { 1273 // 加载svg格式图片 1274 Image($r('app.media.svg')) 1275 .width(110).height(110).margin(15) 1276 .overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1277 .border({ width: 2, color: Color.Pink }) 1278 .objectFit(ImageFit.TOP_END) 1279 // 加载jpg格式图片 1280 Image($r('app.media.jpg')) 1281 .width(110).height(110).margin(15) 1282 .overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1283 .border({ width: 2, color: Color.Pink }) 1284 .objectFit(ImageFit.CENTER) 1285 } 1286 } 1287 }.height(320).width(360).padding({ right: 10, top: 10 }) 1288 } 1289} 1290``` 1291 1292 1293 1294### 示例10（切换显示不同类型图片） 1295 1296该示例展示了ResourceStr类型与ImageContent类型作为数据源的显示图片效果。 1297 1298```ts 1299@Entry 1300@Component 1301struct ImageContentExample { 1302 @State imageSrcIndex: number = 0; 1303 @State imageSrcList: (ResourceStr | ImageContent)[] = [$r('app.media.app_icon'), ImageContent.EMPTY] 1304 1305 build() { 1306 Column({ space: 10 }) { 1307 Image(this.imageSrcList[this.imageSrcIndex]) 1308 .width(100) 1309 .height(100) 1310 Button('点击切换Image的src') 1311 .padding(20) 1312 .onClick(() => { 1313 this.imageSrcIndex = (this.imageSrcIndex + 1) % this.imageSrcList.length 1314 }) 1315 }.width('100%') 1316 .padding(20) 1317 } 1318} 1319``` 1320 1321 1322 1323### 示例11（配置隐私隐藏） 1324 1325该示例通过[privacySensitive](#privacysensitive12)展示了如何配置隐私隐藏，效果展示需要卡片框架支持。 1326 1327```ts 1328@Entry 1329@Component 1330struct ImageExample { 1331 build() { 1332 Column({ space: 10 }) { 1333 Image($r("app.media.startIcon")) 1334 .width(50) 1335 .height(50) 1336 .margin({top :30}) 1337 .privacySensitive(true) 1338 } 1339 .alignItems(HorizontalAlign.Center) 1340 .width("100%") 1341 } 1342} 1343``` 1344 1345 1346 1347### 示例12（为图片设置扫光效果） 1348 1349该示例通过[linearGradient](./ts-basic-components-datapanel.md#lineargradient10)接口和[animateTo()](./ts-explicit-animation.md)实现了给图片设置扫光效果。 1350 1351```ts 1352import { curves } from '@kit.ArkUI'; 1353 1354@Entry 1355@Component 1356struct ImageExample11 { 1357 private curve = curves.cubicBezierCurve(0.33, 0, 0.67, 1); 1358 @State moveImg: string[] = ['imageScanEffect']; 1359 @State moveImgVisible: Visibility = Visibility.Visible; 1360 @State durationTime: number = 1500; 1361 @State iterationsTimes: number = -1; 1362 @State private opacityValue: number = 0.5; 1363 @State imageWidth: number = 450; 1364 @State visible: Visibility = Visibility.Hidden; 1365 @State stackBackgroundColor: string = '#E1E4E9'; 1366 @State linePositionX: number = 0 - this.imageWidth; 1367 @State linePositionY: number = 0; 1368 @State imgResource: Resource | undefined = undefined; 1369 1370 startupAnimate() { 1371 this.moveImg.pop(); 1372 this.moveImg.push('imageScanEffect'); 1373 setTimeout(() => { 1374 this.imgResource = $r('app.media.img'); 1375 }, 3000); 1376 this.getUIContext()?.animateTo({ 1377 duration: this.durationTime, 1378 curve: this.curve, 1379 tempo: 1, 1380 iterations: this.iterationsTimes, 1381 delay: 0 1382 }, () => { 1383 this.linePositionX = this.imageWidth; 1384 }) 1385 } 1386 1387 build() { 1388 Column() { 1389 Row() { 1390 Stack() { 1391 Image(this.imgResource) 1392 .width(this.imageWidth) 1393 .height(200) 1394 .objectFit(ImageFit.Contain) 1395 .visibility(this.visible) 1396 .onComplete(() => { 1397 this.visible = Visibility.Visible; 1398 this.moveImg.pop(); 1399 }) 1400 .onError(() =>{ 1401 setTimeout(() => { 1402 this.visible = Visibility.Visible; 1403 this.moveImg.pop(); 1404 }, 2600) 1405 }) 1406 ForEach(this.moveImg, (item: string) => { 1407 Row() 1408 .width(this.imageWidth) 1409 .height(200) 1410 .visibility(this.moveImgVisible) 1411 .position({ x: this.linePositionX, y: this.linePositionY }) 1412 .linearGradient({ 1413 direction: GradientDirection.Right, 1414 repeating: false, 1415 colors: [[0xE1E4E9, 0], [0xFFFFFF, 0.75], [0xE1E4E9, 1]] 1416 }) 1417 .opacity(this.opacityValue) 1418 }) 1419 } 1420 .backgroundColor(this.visible ? this.stackBackgroundColor : undefined) 1421 .margin({top: 20, left: 20, right: 20}) 1422 .borderRadius(20) 1423 .clip(true) 1424 .onAppear(() => { 1425 this.startupAnimate(); 1426 }) 1427 } 1428 } 1429 } 1430} 1431``` 1432 1433 1434 1435### 示例13（为图片添加变换效果） 1436 1437该示例通过[imageMatrix](#imagematrix15)和[objectFit](#objectfit)属性，为图片添加旋转和平移的效果。 1438 1439```ts 1440import { matrix4 } from '@kit.ArkUI' 1441 1442@Entry 1443@Component 1444struct Test { 1445 private matrix1 = matrix4.identity() 1446 .translate({ x: -400, y: -750 }) 1447 .scale({ x: 0.5, y: 0.5 }) 1448 .rotate({ 1449 x: 2, 1450 y: 0.5, 1451 z: 3, 1452 centerX: 10, 1453 centerY: 10, 1454 angle: -10 1455 }) 1456 1457 build() { 1458 Row() { 1459 Column({ space: 50 }) { 1460 Column({ space: 5 }) { 1461 Image($r("app.media.example")) 1462 .border({ width:2, color: Color.Black }) 1463 .objectFit(ImageFit.Contain) 1464 .width(150) 1465 .height(150) 1466 Text("图片无变换") 1467 .fontSize('25px') 1468 } 1469 Column({ space: 5 }) { 1470 Image($r("app.media.example")) 1471 .border({ width:2, color: Color.Black }) 1472 .objectFit(ImageFit.None) 1473 .translate({ x: 10, y: 10 }) 1474 .scale({ x: 0.5, y: 0.5 }) 1475 .width(100) 1476 .height(100) 1477 Text("Image直接变换，默认显示图源左上角。") 1478 .fontSize('25px') 1479 } 1480 Column({ space: 5 }) { 1481 Image($r("app.media.example")) 1482 .objectFit(ImageFit.MATRIX) 1483 .imageMatrix(this.matrix1) 1484 .border({ width:2, color: Color.Black }) 1485 .width(150) 1486 .height(150) 1487 Text("通过imageMatrix变换，调整图源位置，实现最佳呈现。") 1488 .fontSize('25px') 1489 } 1490 } 1491 .width('100%') 1492 } 1493 } 1494} 1495``` 1496 1497 1498 1499### 示例14（通过sourceSize设置图片解码尺寸） 1500 1501该示例通过[sourceSize](ts-basic-components-image.md#sourcesize)接口自定义图片的解码尺寸。 1502 1503```ts 1504@Entry 1505@Component 1506struct Index { 1507 @State borderRadiusValue: number = 10; 1508 build() { 1509 Column() { 1510 Image($r("app.media.sky")) 1511 .sourceSize({width:1393, height:1080}) 1512 .height(300) 1513 .width(300) 1514 .objectFit(ImageFit.Contain) 1515 .borderWidth(1) 1516 Image($r("app.media.sky")) 1517 .sourceSize({width:13, height:10}) 1518 .height(300) 1519 .width(300) 1520 .objectFit(ImageFit.Contain) 1521 .borderWidth(1) 1522 } 1523 .height('100%') 1524 .width('100%') 1525 } 1526} 1527``` 1528 1529 1530 1531### 示例15（通过renderMode设置图片的渲染模式） 1532 1533该示例通过[renderMode](ts-basic-components-image.md#rendermode)接口设置图片渲染模式为黑白模式。 1534 1535```ts 1536@Entry 1537@Component 1538struct Index { 1539 @State borderRadiusValue: number = 10; 1540 build() { 1541 Column() { 1542 Image($r("app.media.sky")) 1543 .renderMode(ImageRenderMode.Template) 1544 .height(300) 1545 .width(300) 1546 .objectFit(ImageFit.Contain) 1547 .borderWidth(1) 1548 } 1549 .height('100%') 1550 .width('100%') 1551 } 1552} 1553``` 1554 1555 1556 1557### 示例16（通过objectRepeat设置图片的重复样式） 1558 1559该示例通过[objectRepeat](ts-basic-components-image.md#objectrepeat)接口在竖直轴上重复绘制图片。 1560 1561```ts 1562@Entry 1563@Component 1564struct Index { 1565 @State borderRadiusValue: number = 10; 1566 build() { 1567 Column() { 1568 Image($r("app.media.sky")) 1569 .objectRepeat(ImageRepeat.Y) 1570 .height('90%') 1571 .width('90%') 1572 .objectFit(ImageFit.Contain) 1573 .borderWidth(1) 1574 } 1575 .height('100%') 1576 .width('100%') 1577 } 1578} 1579``` 1580 1581 1582 1583### 示例17（设置SVG图片的填充颜色） 1584 1585该示例通过[fillColor](#fillcolor15)为SVG图片设置不同颜色的填充效果。 1586 1587```ts 1588@Entry 1589@Component 1590struct Index { 1591 build() { 1592 Column() { 1593 Text("不设置fillColor") 1594 Image($r("app.media.svgExample")) 1595 .height(100) 1596 .width(100) 1597 .objectFit(ImageFit.Contain) 1598 .borderWidth(1) 1599 Text("fillColor传入ColorContent.ORIGIN") 1600 Image($r("app.media.svgExample")) 1601 .height(100) 1602 .width(100) 1603 .objectFit(ImageFit.Contain) 1604 .borderWidth(1) 1605 .fillColor(ColorContent.ORIGIN) 1606 Text("fillColor传入Color.Blue") 1607 Image($r("app.media.svgExample")) 1608 .height(100) 1609 .width(100) 1610 .objectFit(ImageFit.Contain) 1611 .borderWidth(1) 1612 .fillColor(Color.Blue) 1613 Text("fillColor传入undefined") 1614 Image($r("app.media.svgExample")) 1615 .height(100) 1616 .width(100) 1617 .objectFit(ImageFit.Contain) 1618 .borderWidth(1) 1619 .fillColor(undefined) 1620 } 1621 .height('100%') 1622 .width('100%') 1623 } 1624} 1625``` 1626 1627 1628
;//){kind=link}
