1# Image 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @liyujie43--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9Image为图片组件，常用于在应用中显示图片。Image支持加载[PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md)、[ResourceStr](ts-types.md#resourcestr)和[DrawableDescriptor](#drawabledescriptor10)类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式，不支持apng和svga格式。 10 11> **说明：** 12> 13> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 使用快捷组合键对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，即可实现点击获焦。 16> 17> 图片格式支持SVG图源，SVG标签文档请参考[SVG标签说明](./ts-basic-svg.md)。 18> 19> 动图的播放依赖于Image节点的可见性变化，其默认行为是不播放的。当节点可见时，通过回调启动动画，当节点不可见时，停止动画。可见性状态的判断是通过[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)事件触发的，当可见阈值ratios大于0时，表明Image处于可见状态。 20> 21>如果图片加载过程中出现白色块，请参考[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)。 22 23## 需要权限 24 25使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 26 27 28## 子组件 29 30无 31 32 33## 接口 34 35### Image 36 37Image(src: PixelMap | ResourceStr | DrawableDescriptor) 38 39通过图片数据源获取图片，用于后续渲染展示。 40 41Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。 42 43Image组件默认按照居中裁剪，例如组件宽高设置相同，原图长宽不等，此时按照中间区域进行裁剪。 44 45Image加载成功且组件不设置宽高时，其显示大小自适应父组件。 46 47**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 48 49**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 50 51**系统能力：** SystemCapability.ArkUI.ArkUI.Full 52 53**参数：** 54 55| 参数名 | 类型 | 必填 | 说明 | 56| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 57| src | [PixelMap](ts-image-common.md#pixelmap) \| [ResourceStr](ts-types.md#resourcestr)\| [DrawableDescriptor](#drawabledescriptor10) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br>1. PixelMap格式为像素图，常用于图片编辑的场景。<br>2. ResourceStr包含Resource和string格式。<br>string格式可用于加载网络图片和本地图片，常用于加载网络图片。当[使用相对路径引用本地图片](#示例25使用相对路径显示图片)时，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。<br>- 支持`Base64`字符串。<br>- 传入的字符串为https网络图片地址时，建议参考[示例2下载与显示静态网络图片](#示例2下载与显示静态网络图片)。<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)方法将路径转换为[应用沙箱URI](../../apis-core-file-kit/js-apis-file-fileuri.md#constructor10)，然后传入显示。同时需要保证目录包路径下的文件有可读权限。<br>Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式，具体示例参考[跨HAP/HSP包应用资源](../../../quick-start/resource-categories-and-access.md#跨haphsp包应用资源)。<br/>3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)类型可播放PixelMap数组动画。<br>**说明：**<br/>- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。<br/>- ArkTS卡片上不支持http:/\/等网络相关路径前缀和file:/\/路径前缀的字符串。 | 58 59>**说明：** 60> 61> 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)。 62> 63> src由有效值（可正常解析并加载的图片资源）切换为无效值（无法解析或加载的图片路径）时，组件应保持显示此前成功加载的图片内容，不进行清除或重置操作。 64> 65> 当Image组件入参为[PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md)类型时，只有当PixelMap对象的引用发生变化（即指向一个新的PixelMap实例），Image组件才能感知到数据的变化。仅修改PixelMap对象的内容（如像素值）而不更换对象引用，无法触发数据变化的感知。 66 67### Image<sup>12+</sup> 68 69Image(src: PixelMap | ResourceStr | DrawableDescriptor | ImageContent) 70 71src新增[ImageContent](#imagecontent12)类型，可指定对应的图形内容。 72 73**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 74 75**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 83| src | [PixelMap](ts-image-common.md#pixelmap) \| [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:/\/路径前缀的字符串。 | 84 85### Image<sup>12+</sup> 86 87Image(src: PixelMap | ResourceStr | DrawableDescriptor, imageAIOptions: ImageAIOptions) 88 89Image新增[imageAIOptions](ts-image-common.md#imageaioptions12)参数，为组件设置AI分析选项。 90 91**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ---- | ---------------------------------------- | ---- | ---------------------------------------- | 99| src | [PixelMap](ts-image-common.md#pixelmap) \| [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:/\/路径前缀的字符串。 | 100| imageAIOptions | [ImageAIOptions](ts-image-common.md#imageaioptions12) | 是 | 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。 | 101 102## 属性 103 104属性的详细使用指导请参考[添加属性](../../../ui/arkts-graphics-display.md#添加属性)。除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 105 106> **说明：** 107> 108> Image组件不支持设置通用属性[foregroundColor](./ts-universal-attributes-foreground-color.md#foregroundcolor)，可以通过Image组件的[fillColor](#fillcolor)属性设置填充颜色。 109 110### alt 111 112alt(value: string | Resource | PixelMap) 113 114设置图片加载过程中显示的占位图。 115 116占位图支持使用[objectFit](#objectfit)设置填充效果，与图片的填充效果一致。 117 118当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 119 120**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 130| value | string \| [Resource](ts-types.md#resource) \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md)<sup>12+</sup> | 是 | 设置图片加载过程中显示的占位图，支持本地图片（png、jpg、bmp、svg、gif和heif类型），支持[PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md)类型图片，不支持网络图片。<br/>默认值：null<br/>由有效值（可正常解析并加载的图片资源）切换为无效值（无法解析或加载的图片路径）时，组件保持显示此前成功加载的图片内容，不进行清除或重置操作。 | 131 132### objectFit 133 134objectFit(value: ImageFit) 135 136设置图片的填充效果。 137 138**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 139 140**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ----------------------------------------- | ---- | ------------------------------------------- | 148| value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 图片的填充效果。<br/>默认值：ImageFit.Cover | 149 150### imageMatrix<sup>15+</sup> 151 152imageMatrix(matrix: ImageMatrix) 153 154设置图片的变换矩阵。通过[ImageMatrix](#imagematrix15对象说明)对象使用平移、旋转、缩放等函数，实现宫格缩略图的最佳呈现。SVG类型图源不支持该属性。 155 156设置resizable、objectRepeat属性时，该属性设置不生效。该属性只针对图源做处理，不会触发Image组件的回调事件。 157 158该属性与[objectFit](#objectfit)属性强关联，仅在[objectFit](#objectfit)属性设置为[ImageFit](ts-appendix-enums.md#imagefit).MATRIX时生效。 159 160**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------ | --------------------------------------------------- | ---- | -------------- | 168| matrix | [ImageMatrix](#imagematrix15对象说明) | 是 | 图片的变换矩阵。| 169 170### objectRepeat 171 172objectRepeat(value: ImageRepeat) 173 174设置图片的重复样式，从中心点向两边重复，剩余空间不足放下一张图片时会截断。SVG类型图源不支持该属性。 175 176当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 177 178**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 179 180**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 181 182**系统能力：** SystemCapability.ArkUI.ArkUI.Full 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------ | ----------------------------------------------- | ---- | ------------------------------------------------- | 188| value | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 是 | 图片的重复样式。<br/>默认值：ImageRepeat.NoRepeat | 189 190### interpolation 191 192interpolation(value: ImageInterpolation) 193 194设置图片的插值效果，即缓解图片在缩放时的锯齿问题。SVG类型图源不支持该属性。 195 196当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 197 198**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 199 200**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 201 202**系统能力：** SystemCapability.ArkUI.ArkUI.Full 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| ------ | ----------------------------------------- | ---- | --------------------------------------------------- | 208| value | [ImageInterpolation](#imageinterpolation) | 是 | 图片的插值效果。<br/>默认值：ImageInterpolation.Low<br/>设置undefined时，取值为ImageInterpolation.None。 | 209 210### renderMode 211 212renderMode(value: ImageRenderMode) 213 214设置图片的渲染模式。SVG类型图源不支持该属性。 215 216设置 [ColorFilter](#colorfilter9) 时，该属性设置不生效。 217 218当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 219 220**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 221 222**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 223 224**系统能力：** SystemCapability.ArkUI.ArkUI.Full 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 230| value | [ImageRenderMode](#imagerendermode) | 是 | 图片的渲染模式为原色或黑白。<br/>默认值：ImageRenderMode.Original | 231 232### sourceSize 233 234sourceSize(value: ImageSourceSize) 235 236设置图片解码尺寸。仅在目标尺寸小于图源尺寸时生效。SVG类型图源和PixelMap资源不支持该属性。 237 238当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 239 240**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 241 242**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 243 244**系统能力：** SystemCapability.ArkUI.ArkUI.Full 245 246**参数：** 247 248| 参数名 | 类型 | 必填 | 说明 | 249| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 250| value | [ImageSourceSize](#imagesourcesize18对象说明) | 是 | 图片解码尺寸参数，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。 | 251 252### matchTextDirection 253 254matchTextDirection(value: boolean) 255 256设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。 257 258当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 259 260**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 261 262**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 263 264**系统能力：** SystemCapability.ArkUI.ArkUI.Full 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| ------ | ------- | ---- | -------------------------------------------- | 270| value | boolean | 是 | 图片是否跟随系统语言方向。<br/>默认值：false，false表示图片不跟随系统语言方向，true表示图片跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。 | 271 272### fitOriginalSize 273 274fitOriginalSize(value: boolean) 275 276设置图片的显示尺寸是否跟随图源尺寸。 277 278图片组件已设置width、height属性时，fitOriginalSize属性不生效。 279 280当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 281 282**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 283 284**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 285 286**系统能力：** SystemCapability.ArkUI.ArkUI.Full 287 288**参数：** 289 290| 参数名 | 类型 | 必填 | 说明 | 291| ------ | ------- | ---- | ------------------------------------------------ | 292| value | boolean | 是 | 图片的显示尺寸是否跟随图源尺寸。<br/>默认值：false <br/>**说明：**<br/>当不设置fitOriginalSize或者设置fitOriginalSize为false时，组件显示大小不跟随图源大小。<br/> 当设置fitOriginalSize为true时，组件显示大小跟随图源大小。 | 293 294### fillColor 295 296fillColor(value: ResourceColor) 297 298设置填充颜色。仅对SVG图源生效，设置后会替换SVG图片中所有可绘制元素的填充颜色。如需对png图片进行修改颜色，可以使用[colorFilter](#colorfilter9)。 299 300当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 301 302**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 303 304**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 305 306**系统能力：** SystemCapability.ArkUI.ArkUI.Full 307 308**参数：** 309 310| 参数名 | 类型 | 必填 | 说明 | 311| ------ | ------------------------------------------ | ---- | -------------- | 312| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置填充颜色。 <br/>**说明：**<br/> 默认不对组件进行填充。当传入异常值时，系统将使用默认的主题色：浅色模式下为黑色，深色模式下为白色。| 313 314### fillColor<sup>15+</sup> 315 316fillColor(color: ResourceColor|ColorContent) 317 318设置填充颜色。仅对SVG图源生效，设置后会替换SVG图片中所有可绘制元素的填充颜色。如需对png图片进行修改颜色，可以使用[colorFilter](#colorfilter9)。如果想重置填充颜色可以传入[ColorContent](#colorcontent15)类型。 319 320当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 321 322**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 323 324**系统能力：** SystemCapability.ArkUI.ArkUI.Full 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| ------ | ------------------------------------------ | ---- | -------------- | 330| color | [ResourceColor](ts-types.md#resourcecolor)\|[ColorContent](#colorcontent15) | 是 | 设置填充颜色。 <br/>**说明：**<br/> 默认不对组件进行填充。当传入异常值时，系统将使用默认的主题色：浅色模式下为黑色，深色模式下为白色。 | 331 332### fillColor<sup>20+</sup> 333 334fillColor(color: ResourceColor|ColorContent|ColorMetrics) 335 336设置填充颜色。仅对SVG图源生效，设置后会替换SVG图片中所有可绘制元素的填充颜色。如需对png图片进行修改颜色，可以使用[colorFilter](#colorfilter9)。如果想重置填充颜色可以传入[ColorContent](#colorcontent15)类型。支持通过传入[ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12)类型设置P3色域颜色值，可在支持高色域的设备上获得更丰富的色彩表现。 337 338当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 339 340**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 341 342**系统能力：** SystemCapability.ArkUI.ArkUI.Full 343 344**参数：** 345 346| 参数名 | 类型 | 必填 | 说明 | 347| ------ | ------------------------------------------ | ---- | -------------- | 348| color | [ResourceColor](ts-types.md#resourcecolor)\|[ColorContent](#colorcontent15)\|[ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12) | 是 | 设置填充颜色。 <br/>**说明：**<br/> 默认不对组件进行填充。当传入异常值时，系统将使用默认的主题色：浅色模式下为黑色，深色模式下为白色。 | 349 350### autoResize 351 352autoResize(value: boolean) 353 354设置图片解码过程中是否对图源自动缩放。降采样解码时图片的部分信息丢失，因此可能会导致图片质量的下降（如：出现锯齿），这时可以选择把autoResize设为false，按原图尺寸解码，提升显示效果，但会增加内存占用。 355 356原图尺寸和显示尺寸不匹配时，图片都会出现些许的失真、模糊。最佳清晰度配置建议： 357 358图片缩小显示时：.autoResize(false) + .interpolation(.Medium) 359 360图片放大显示时：.interpolation(.High) 361 362当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)和SVG时设置该属性不生效。 363 364**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 365 366**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 367 368**系统能力：** SystemCapability.ArkUI.ArkUI.Full 369 370**参数：** 371 372| 参数名 | 类型 | 必填 | 说明 | 373| ------ | ------- | ---- | ------------------------------------------------------------ | 374| value | boolean | 是 | 图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为800x1200，而显示区域大小为200x200，则图片会降采样解码到200x300的尺寸（实际计算过程中会依赖缩放和填充类型的配置，从而得到的计算结果会有差异），从而大幅度节省图片占用的内存。<br/>默认值：false，false表示关闭图源自动缩放，true表示开启图源自动缩放。 | 375 376### syncLoad<sup>8+</sup> 377 378syncLoad(value: boolean) 379 380设置是否同步加载图片。建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。 381 382当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 383 384如果加载图片时出现闪烁，设置syncLoad为true。详情请参见[并发优化](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-click-to-click-response-optimization#section715115119192)。 385 386**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 387 388**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 389 390**系统能力：** SystemCapability.ArkUI.ArkUI.Full 391 392**参数：** 393 394| 参数名 | 类型 | 必填 | 说明 | 395| ------ | ------- | ---- | ------------------------------------------------------------ | 396| value | boolean | 是 | 是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。<br/>默认值：false，false表示异步加载图片，true表示同步加载图片。 | 397 398### copyOption<sup>9+</sup> 399 400copyOption(value: CopyOptions) 401 402设置图片是否可复制。当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。SVG图片不支持复制。 403 404当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 405 406**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 407 408**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 409 410**系统能力：** SystemCapability.ArkUI.ArkUI.Full 411 412**参数：** 413 414| 参数名 | 类型 | 必填 | 说明 | 415| ------ | ------------------------------------------------ | ---- | --------------------------------------------- | 416| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 是 | 图片是否可复制。<br/>默认值：CopyOptions.None | 417 418### colorFilter<sup>9+</sup> 419 420colorFilter(value: ColorFilter | DrawingColorFilter) 421 422为图像设置颜色滤镜效果。 423 424设置该属性时，[renderMode](#rendermode)属性设置不生效。 425 426**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 427 428**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 429 430**系统能力：** SystemCapability.ArkUI.ArkUI.Full 431 432**参数：** 433 434| 参数名 | 类型 | 必填 | 说明 | 435| ------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 436| value | [ColorFilter](ts-types.md#colorfilter9) \| [DrawingColorFilter<sup>12+</sup>](#drawingcolorfilter12) | 是 | 1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。<br/>2. 从API version12开始支持@ohos.graphics.drawing的ColorFilter类型作为入参。<br/>**说明：** <br/>API version 11及之前，SVG类型图源不支持该属性。<br/>从API version 12开始，该接口中的DrawingColorfilter类型支持在原子化服务中使用。其中，SVG类型的图源只有设置了stroke属性（无论是否有值）才会生效。| 437 438颜色滤镜通过一个4x5的矩阵来设置图像的颜色滤镜，矩阵第一行表示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/> 439### draggable<sup>9+</sup> 440 441draggable(value: boolean) 442 443设置组件默认拖拽效果。 444 445**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 446 447**系统能力：** SystemCapability.ArkUI.ArkUI.Full 448 449**参数：** 450 451| 参数名 | 类型 | 必填 | 说明 | 452| ------ | ------- | ---- | ------------------------------------------------------------ | 453| value | boolean | 是 | 组件默认拖拽效果，设置为true时，组件可拖拽，绑定的长按手势不生效。<br />API version 9及之前，默认值为false。API version 10及之后，默认值为true。<br /> 若用户需要设置自定义手势，则需要将draggable设置为false。设置为false之后，拖拽类事件不再触发。 | 454 455### enableAnalyzer<sup>11+</sup> 456 457enableAnalyzer(enable: boolean) 458 459设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。<!--RP3--><!--RP3End--> 460 461不能和[overlay](ts-universal-attributes-overlay.md)属性同时使用，两者同时设置时overlay中[CustomBuilder](ts-types.md#custombuilder8)属性将失效。该特性依赖设备能力。 462 463分析图像要求是静态非矢量图，即svg、gif等图像类型不支持分析，支持传入[PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md)进行分析，目前仅支持[RGBA_8888](../../apis-image-kit/arkts-apis-image-e.md#pixelmapformat7)类型，使用方式见[示例5开启图像AI分析](#示例5开启图像ai分析)。 464 465[alt](#alt)占位图不支持分析，[objectRepeat](#objectrepeat)属性仅在[ImageRepeat](ts-appendix-enums.md#imagerepeat).NoRepeat下支持分析，隐私遮罩属性[obscured](ts-universal-attributes-obscured.md)打开时不支持分析。 466 467基于完整原始图像进行分析，设置[clip](ts-universal-attributes-sharp-clipping.md#clip12)、[margin](ts-universal-attributes-size.md#margin)、[borderRadius](ts-universal-attributes-border.md#borderradius)、[position](ts-universal-attributes-location.md#position)和[objectFit](#objectfit)属性导致图像显示不完整，或使用[renderMode](#rendermode)设置蒙层，仍基于完整原始图像进行分析。 [copyOption](#copyoption9)属性不影响AI分析功能。 468 469当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时设置该属性不生效。 470 471> **说明：** 472> 473> 需要配置权限：ohos.permission.INTERNET。 474 475**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 476 477**系统能力：** SystemCapability.ArkUI.ArkUI.Full 478 479**参数：** 480 481| 参数名 | 类型 | 必填 | 说明 | 482| ------ | ------- | ---- | ------------------------------------------------------------ | 483| enable | boolean | 是 | Image组件是否支持AI分析。<br/>设置为true时，Image组件支持AI分析。设置为false时，Image组件不支持AI分析。<br/>默认值：false | 484 485### resizable<sup>11+</sup> 486 487resizable(value: ResizableOptions) 488 489设置图像拉伸时可调整大小的图像选项。拉伸对拖拽缩略图以及占位图有效。 490 491设置合法的 [ResizableOptions](#resizableoptions11) 时，objectRepeat属性和orientation属性设置不生效。 492 493当设置 top +bottom 大于原图的高或者 left + right 大于原图的宽时 [ResizableOptions](#resizableoptions11) 属性设置不生效。 494 495当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)和SVG时设置该属性不生效。 496 497**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 498 499**系统能力：** SystemCapability.ArkUI.ArkUI.Full 500 501**参数：** 502 503| 参数名 | 类型 | 必填 | 说明 | 504| ------ | --------------------------------------- | ---- | -------------------------------- | 505| value | [ResizableOptions](#resizableoptions11) | 是 | 图像拉伸时可调整大小的图像选项。 | 506 507### privacySensitive<sup>12+</sup> 508 509privacySensitive(supported: boolean) 510 511设置是否支持卡片敏感隐私信息。 512 513**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 514 515**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 516 517**系统能力：** SystemCapability.ArkUI.ArkUI.Full 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| --------- | ------- | ---- | ------------------------ | 523| supported | boolean | 是 | 是否支持卡片敏感隐私信息。<br/>默认值为false，表示不支持卡片敏感隐私信息，当设置为true时，隐私模式下图片将显示为半透明底板样式。<br/>**说明：** <br/>设置null则不敏感。<br/>进入隐私模式需要卡片框架支持。 | 524 525### dynamicRangeMode<sup>12+</sup> 526 527dynamicRangeMode(value: DynamicRangeMode) 528 529设置期望展示的图像动态范围。SVG类型图源不支持该属性。 530 531**设备行为差异：** 该接口在手机、PC/2in1和Tablet设备中可正常生效，在其他设备类型中无效果。 532 533**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 534 535**系统能力：** SystemCapability.ArkUI.ArkUI.Full 536 537**参数：** 538 539| 参数名 | 类型 | 必填 | 说明 | 540| ------ | --------------------------------------- | ---- | -------------------------------- | 541| value | [DynamicRangeMode](#dynamicrangemode12枚举说明) | 是 | 图像显示的动态范围。<br/>默认值：DynamicRangeMode.STANDARD | 542 543### orientation<sup>14+</sup> 544 545orientation(orientation: ImageRotateOrientation) 546 547设置图像内容的显示方向。 548 549**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 550 551**系统能力：** SystemCapability.ArkUI.ArkUI.Full 552 553**参数：** 554 555| 参数名 | 类型 | 必填 | 说明 | 556| ------ | --------------------------------------- | ---- | -------------------------------- | 557| orientation | [ImageRotateOrientation](#imagerotateorientation14) | 是 | 图像内容的显示方向。<br/>不支持gif和svg类型的图片。<br/>如果需要显示携带旋转角度信息或翻转信息的图片，建议使用ImageRotateOrientation.AUTO进行设置。<br/>默认值：ImageRotateOrientation.UP<br/>设置为undefined或null时，取值为ImageRotateOrientation.AUTO。 | 558 559### hdrBrightness<sup>19+</sup> 560 561hdrBrightness(brightness: number) 562 563设置组件在显示HDR图片时的亮度。 564 565SVG类型图源不支持该属性。 566 567该属性与[dynamicRangeMode](#dynamicrangemode12)属性同时设置时，[dynamicRangeMode](#dynamicrangemode12)属性不生效。 568 569**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 570 571**系统能力：** SystemCapability.ArkUI.ArkUI.Full 572 573**参数：** 574 575| 参数名 | 类型 | 必填 | 说明 | 576| -------- | ------- | ---- | ---------------------- | 577| brightness | number | 是 | 用于调整组件展示HDR图片的亮度，该接口仅对HDR图源生效。<br/>默认值：1.0<br/>取值范围：[0.0，1.0]，小于0和大于1.0时取1。0表示图片按照SDR亮度显示，1表示图片按照当前允许的最高HDR亮度显示。 | 578 579## ImageContent<sup>12+</sup> 580 581指定图像内容。 582 583**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 584 585**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 586 587**系统能力：** SystemCapability.ArkUI.ArkUI.Full 588 589| 名称 | 值 | 说明 | 590| ------ | ----- | -------------------------- | 591| EMPTY | 0 | 空图像。 | 592 593## ImageInterpolation 594 595图片的插值效果。 596 597**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 598 599**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 600 601**系统能力：** SystemCapability.ArkUI.ArkUI.Full 602 603| 名称 | 值 | 说明 | 604| ------ | - | -------------------------- | 605| None | - | 最近邻插值。 | 606| Low | - | 双线性插值。 | 607| Medium | - | MipMap插值。 | 608| High | - | Cubic插值，插值质量最高，可能会影响图片渲染的速度。 | 609 610## ImageRenderMode 611 612图片的渲染模式。 613 614**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 615 616**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 617 618**系统能力：** SystemCapability.ArkUI.ArkUI.Full 619 620| 名称 | 值 | 说明 | 621| -------- | ---- | -------------- | 622| Original | - | 原色渲染模式。 | 623| Template | - | 黑白渲染模式。 | 624 625## ResizableOptions<sup>11+</sup> 626 627图像拉伸时可调整大小的图像选项。 628 629**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 630 631**系统能力：** SystemCapability.ArkUI.ArkUI.Full 632 633| 名称 | 类型 | 只读 | 可选 | 说明 | 634| --------- |-----------|-----------|-----------|-----------| 635| slice | [EdgeWidths](ts-types.md#edgewidths9) | 否 | 是 | 边框宽度类型，用于描述组件边框不同方向的宽度。<br>**说明：**<br>只有当bottom和right同时大于0时，该属性生效。<br>当设置了top时，图片顶部拉伸，图片的像素值保持不变。<br>当设置了right时，图片右部拉伸，图片的像素值保持不变。<br>当设置了bottom时，图片底部拉伸，图片的像素值保持不变。<br>当设置了left时，图片左部拉伸，图片的像素值保持不变。<br>每个方向的宽度默认值为0，传入数字时默认单位为vp。<br>设置了EdgeWidths后的效果如图1（设置EdgeWidths效果图）所示。| 636| lattice<sup>12+</sup> | [DrawingLattice](#drawinglattice12) | 否 | 是 | 矩形网格对象。<br>**说明：**<br> 通过@ohos.graphics.drawing的createImageLattice接口创建Lattice类型作为入参。将图像划分为矩形网格，同时处于偶数列和偶数行上的网格图像是固定的，不会被拉伸。<br>该参数对[backgroundImageResizable](ts-universal-attributes-background.md#backgroundimageresizable12)接口不生效。<br> 传入数字时默认单位为px。 | 637 638**图1** 设置EdgeWidths效果图 639 640 641## DynamicRangeMode<sup>12+</sup>枚举说明 642 643期望展示的图像动态范围。 644 645**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 646 647**系统能力：** SystemCapability.ArkUI.ArkUI.Full 648 649| 名称 | 值 | 说明 | 650| ------ | -------------------------- | -------------------------- | 651| HIGH | 0 | 不受限动态范围，最大限度进行图片提亮。 | 652| CONSTRAINT | 1 | 受限动态范围，受限进行图片提亮。 | 653| STANDARD | 2 | 标准动态范围，不进行图片提亮。 | 654 655## ImageRotateOrientation<sup>14+</sup> 656 657期望的图像内容显示方向。 658 659**系统能力：** SystemCapability.ArkUI.ArkUI.Full 660 661| 名称 | 值 | 说明 | 662| ------ | -------------------------- | -------------------------- | 663| AUTO | 0 | 读取图片携带的EXIF元数据作为显示方向，支持旋转和镜像。<br/>PixelMap和DrawableDescriptor类型的图片不包含头信息，调用该接口时图片显示效果不变化。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。<br/> | 664| UP | 1 | 默认按照当前图片的像素数据进行显示，不做任何处理。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 665| RIGHT | 2 | 将当前图片顺时针旋转90度后显示。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。<br/> | 666| DOWN | 3 | 将当前图片顺时针旋转180度后显示。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。<br/> | 667| LEFT | 4 | 将当前图片顺时针旋转270度后显示。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。<br/> | 668| UP_MIRRORED<sup>20+</sup> | 5 | 将当前图片水平翻转后显示。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。<br/> | 669| RIGHT_MIRRORED<sup>20+</sup> | 6 | 将当前图片水平翻转再顺时针旋转90度后显示。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。<br/> | 670| DOWN_MIRRORED<sup>20+</sup> | 7 | 将当前图片垂直翻转后显示。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。<br/> | 671| LEFT_MIRRORED<sup>20+</sup> | 8 | 将当前图片水平翻转再顺时针旋转270度后显示。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。<br/> | 672 673## ImageSourceSize<sup>18+</sup>对象说明 674 675图片解码尺寸。 676 677> **说明：** 678> 679> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 680 681**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 682 683**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 684 685**系统能力：** SystemCapability.ArkUI.ArkUI.Full 686 687| 名称 | 类型 | 只读 | 可选 | 说明 | 688| ------ | --------- | ---- | ------------- | ------------- | 689| width<sup>7+</sup> | number | 否 | 否 | 图片解码尺寸宽度。<br/>单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 690| height<sup>7+</sup> | number | 否 | 否 | 图片解码尺寸高度。<br/>单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 691 692## DrawableDescriptor<sup>10+</sup> 693 694type DrawableDescriptor = DrawableDescriptor 695 696作为Image组件的入参对象。 697 698**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 699 700**系统能力：** SystemCapability.ArkUI.ArkUI.Full 701 702| 类型 | 说明 | 703| ------ | ---------- | 704| [DrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | 返回一个DrawableDescriptor对象。 | 705 706## DrawingColorFilter<sup>12+</sup> 707 708type DrawingColorFilter = ColorFilter 709 710颜色滤波器对象。 711 712**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 713 714**系统能力：** SystemCapability.ArkUI.ArkUI.Full 715 716| 类型 | 说明 | 717| ------ | ---------- | 718| [ColorFilter](../../apis-arkgraphics2d/arkts-apis-graphics-drawing-ColorFilter.md) | 返回一个颜色滤波器。 | 719 720## DrawingLattice<sup>12+<sup> 721 722type DrawingLattice = Lattice 723 724将图片按照矩形网格进行划分。 725 726**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 727 728**系统能力：** SystemCapability.ArkUI.ArkUI.Full 729 730| 类型 | 说明 | 731| ------ | ---------- | 732| [Lattice](../../apis-arkgraphics2d/arkts-apis-graphics-drawing-Lattice.md) | 返回一个矩阵网格对象。 | 733 734## ImageMatrix<sup>15+</sup>对象说明 735 736type ImageMatrix = Matrix4Transit 737 738当前的矩阵对象。 739 740**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 741 742**系统能力：** SystemCapability.ArkUI.ArkUI.Full 743 744| 类型 | 说明 | 745| ------ | ---------- | 746| [Matrix4Transit](../js-apis-matrix4.md#matrix4transit) | 返回当前的矩阵对象。 | 747 748## ColorContent<sup>15+</sup> 749 750指定颜色填充内容。 751 752**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 753 754**系统能力：** SystemCapability.ArkUI.ArkUI.Full 755 756| 名称 | 类型 | 只读 | 可选 | 说明 | 757| ------ | --------- | --- | --- | ------------- | 758| ORIGIN | ColorContent | 是 | 否 | 重置[fillColor](#fillcolor)接口，效果上与不设置[fillColor](#fillcolor)一致。 | 759 760## 事件 761 762除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 763 764### onComplete 765 766onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number }) => void) 767 768图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 769 770当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 771 772**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 773 774**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 775 776**系统能力：** SystemCapability.ArkUI.ArkUI.Full 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| ---------------------------- | ------ | ---- | ------------------------------------------------------------ | 782| width | number | 是 | 图片的宽。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素 | 783| height | number | 是 | 图片的高。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素 | 784| componentWidth | number | 是 | 组件的宽。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素 | 785| componentHeight | number | 是 | 组件的高。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素 | 786| loadingStatus | number | 是 | 图片加载成功的状态值。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：**<br/>返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | 787| contentWidth<sup>10+</sup> | number | 是 | 图片实际绘制的宽度。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素<br>**说明：**<br/>仅在loadingStatus返回1时有效。 | 788| contentHeight<sup>10+</sup> | number | 是 | 图片实际绘制的高度。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 789| contentOffsetX<sup>10+</sup> | number | 是 | 实际绘制内容相对于组件自身的x轴偏移。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 790| contentOffsetY<sup>10+</sup> | number | 是 | 实际绘制内容相对于组件自身的y轴偏移。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 791 792### onError<sup>9+</sup> 793 794onError(callback: ImageErrorCallback) 795 796图片加载异常时触发该回调。 797 798当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 799 800**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 801 802**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 803 804**系统能力：** SystemCapability.ArkUI.ArkUI.Full 805 806**参数：** 807 808| 参数名 | 类型 | 必填 | 说明 | 809| -------- | ------------------------------------------ | ---- | -------------------------- | 810| callback | [ImageErrorCallback](#imageerrorcallback9) | 是 | 图片加载异常时触发的回调。<br>**说明：**<br/>建议开发者使用此回调，可快速确认图片加载失败时的具体原因，参见[ImageError](#imageerror9)的错误信息详细介绍。 | 811 812### onFinish 813 814onFinish(event: () => void) 815 816当加载的源文件为带动效的SVG格式图片时，SVG动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。 817 818仅支持SVG格式的图片。当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 819 820**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 821 822**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 823 824**系统能力：** SystemCapability.ArkUI.ArkUI.Full 825 826**参数：** 827 828| 参数名 | 类型 | 必填 | 说明 | 829| -------- | ------------------------------------------ | ---- | -------------------------- | 830| event | () => void | 是 | 当加载的源文件为带动效的SVG格式图片时，SVG动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。 | 831 832## ImageErrorCallback<sup>9+</sup> 833 834type ImageErrorCallback = (error: ImageError) => void 835 836图片加载异常时触发此回调。 837 838当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 839 840**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 841 842**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 843 844**系统能力：** SystemCapability.ArkUI.ArkUI.Full 845 846**参数：** 847 848| 参数名 | 类型 | 必填 | 说明 | 849| ------ | -------------------------- | ---- | ---------------------------------- | 850| error | [ImageError](#imageerror9) | 是 | 图片加载异常时触发回调的返回对象。 | 851 852## ImageError<sup>9+</sup> 853 854图片加载异常时触发回调的返回对象。 855 856当组件的参数类型为[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)时该事件不触发。 857 858**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 859 860**系统能力：** SystemCapability.ArkUI.ArkUI.Full 861 862| 名称 | 类型 | 只读 | 可选 | 说明 | 863| --------------- | ------ | ---- | ------------------------- | ------------------------- | 864| componentWidth | number | 否 | 否 | 组件的宽。<br/>单位：像素<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 865| componentHeight | number | 否 | 否 | 组件的高。<br/>单位：像素<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 866| message<sup>10+</sup> | string | 否 | 否 | 报错信息。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 867| error<sup>20+</sup> | [BusinessError\<void>](#businesserror20) | 否 | 是 | 图片加载异常返回的报错信息，其中code为错误码，message为错误信息。报错信息请参考以下错误信息的详细介绍。<br/>默认值：{ code : -1, message : "" }<br/>**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 868 869## BusinessError<sup>20+</sup> 870 871type BusinessError\<T> = BusinessError\<T> 872 873图片加载异常返回的错误信息。 874 875**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。 876 877**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 878 879**系统能力：** SystemCapability.ArkUI.ArkUI.Full 880 881| 类型 | 说明 | 882| ---- | ------ | 883| [BusinessError\<T>](../../apis-basic-services-kit/js-apis-base.md#businesserror) | 图片加载异常返回的错误信息。 | 884 885以下是错误信息的详细介绍：ImageError的error属性为错误信息对象，其中code为错误码，message为错误信息。 886 887| 错误码ID | 错误信息 | 错误信息发生阶段 | 图片加载类型 | 888| -------- | ---------------------------- | --------- | ------- | 889| 101000 | unknown source type. | 数据加载 | 未知类型 | 890| 102010 | sync http task of uri cancelled. | 数据加载 | 网络文件 | 891| 102011 | sync http task of uri failed. | 数据加载 | 网络文件 | 892| 102012 | async http task of uri cancelled. | 数据加载 | 网络文件 | 893| 102013 | async http task of uri failed. | 数据加载 | 网络文件 | 894| 102030 | wrong code format. | 数据加载 | base64字符串文件 | 895| 102031 | decode base64 image failed. | 数据加载 | base64字符串文件 | 896| 102050 | path is too long. | 数据加载 | 沙箱文件 | 897| 102051 | read data failed. | 数据加载 | 沙箱文件 | 898| 102070 | get image data by name failed. | 数据加载 | 资源文件 | 899| 102071 | get image data by id failed. | 数据加载 | 资源文件 | 900| 102072 | uri is invalid. | 数据加载 | 资源文件 | 901| 102090 | uri is invalid. | 数据加载 | 包内文件 | 902| 102091 | get asset failed. | 数据加载 | 包内文件 | 903| 102110 | open file failed. | 数据加载 | 媒体库文件 | 904| 102111 | get file stat failed. | 数据加载 | 媒体库文件 | 905| 102112 | read file failed. | 数据加载 | 媒体库文件 | 906| 102130 | decoded data is empty. | 数据加载 | 媒体库缩略图文件 | 907| 102131 | load shared memory image data timeout. | 数据加载 | 共享内存文件 | 908| 103100 | make svg dom failed. | 数据加载 | 矢量图文件 | 909| 103200 | image data size is invalid. | 数据加载 | 位图文件 | 910| 111000 | image source create failed. | 数据解码 | 位图文件 | 911| 111001 | pixelmap create failed. | 数据解码 | 位图文件 | 912 913## 示例 914 915### 示例1（加载基本类型图片） 916 917该示例通过传入[Resource](ts-types.md#resource)资源，加载png、gif、svg和jpg等基本类型的图片。 918 919```ts 920@Entry 921@Component 922struct ImageExample1 { 923 build() { 924 Column() { 925 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 926 Row() { 927 // 加载png格式图片 928 // $r('app.media.ic_camera_master_ai_leaf')需要替换为开发者所需的图像资源文件。 929 Image($r('app.media.ic_camera_master_ai_leaf')) 930 .width(110).height(110).margin(15) 931 .overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 932 // 加载gif格式图片 933 // $r('app.media.loading')需要替换为开发者所需的图像资源文件。 934 Image($r('app.media.loading')) 935 .width(110).height(110).margin(15) 936 .overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 937 } 938 Row() { 939 // 加载svg格式图片 940 // $r('app.media.ic_camera_master_ai_clouded')需要替换为开发者所需的图像资源文件。 941 Image($r('app.media.ic_camera_master_ai_clouded')) 942 .width(110).height(110).margin(15) 943 .overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 944 // 加载jpg格式图片 945 // $r('app.media.ic_public_favor_filled')需要替换为开发者所需的图像资源文件。 946 Image($r('app.media.ic_public_favor_filled')) 947 .width(110).height(110).margin(15) 948 .overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 949 } 950 } 951 }.height(320).width(360).padding({ right: 10, top: 10 }) 952 } 953} 954``` 955 956 957 958### 示例2（下载与显示静态网络图片） 959 960加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。使用[HTTP](../../../network/http-request.md)工具包发送网络请求，接着将返回的数据解码为Image组件中的`PixelMap`，加载gif到`PixelMap`时，gif显示为静态图。图片开发可参考[图片处理](../../../media/image/image-overview.md)。 961 962使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 963 964```ts 965import { http } from '@kit.NetworkKit'; 966import { BusinessError } from '@kit.BasicServicesKit'; 967import { image } from '@kit.ImageKit'; 968 969@Entry 970@Component 971struct ImageExample2 { 972 @State pixelMapImg: PixelMap | undefined = undefined; 973 974 aboutToAppear() { 975 this.requestImageUrl('https://www.example.com/xxx.png'); // 请填写一个具体的网络图片地址 976 } 977 978 requestImageUrl(url: string) { 979 http.createHttp().request(url, (error: BusinessError, data: http.HttpResponse) => { 980 if (error) { 981 console.error(`request image failed: url: ${url}, code: ${error.code}, message: ${error.message}`); 982 } else { 983 let imgData: ArrayBuffer = data.result as ArrayBuffer; 984 console.info(`request image success, size: ${imgData.byteLength}`); 985 let imgSource: image.ImageSource = image.createImageSource(imgData); 986 class sizeTmp { 987 height: number = 100; 988 width: number = 100; 989 } 990 let options: Record<string, number | boolean | sizeTmp> = { 991 'alphaType': 0, 992 'editable': false, 993 'pixelFormat': 3, 994 'scaleMode': 1, 995 'size': { height: 100, width: 100 } 996 } 997 imgSource.createPixelMap(options).then((pixelMap: PixelMap) => { 998 console.error('image createPixelMap success'); 999 this.pixelMapImg = pixelMap; 1000 imgSource.release(); 1001 }).catch(() => { 1002 imgSource.release(); 1003 }) 1004 } 1005 }) 1006 } 1007 1008 build() { 1009 Column() { 1010 Image(this.pixelMapImg) 1011 // $r('app.media.img')需要替换为开发者所需的图像资源文件。 1012 .alt($r('app.media.img')) 1013 .objectFit(ImageFit.None) 1014 .width('100%') 1015 .height('100%') 1016 } 1017 } 1018} 1019``` 1020 1021 1022 1023### 示例3（下载与显示网络gif图片） 1024 1025该示例使用[cacheDownload.download](../../apis-basic-services-kit/js-apis-request-cacheDownload.md#cachedownloaddownload)接口下载网络gif图片。 1026 1027使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](../../../security/AccessToken/declare-permissions.md)。 1028 1029```ts 1030import { cacheDownload } from '@kit.BasicServicesKit'; 1031 1032@Entry 1033@Component 1034struct Index { 1035 @State src: string = 'https://www.example.com/xxx.gif'; // 请填写一个具体的网络图片地址。 1036 1037 async aboutToAppear(): Promise<void> { 1038 // 提供缓存下载任务的配置选项。 1039 let options: cacheDownload.CacheDownloadOptions = {}; 1040 try { 1041 // 进行缓存下载，资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。 1042 cacheDownload.download(this.src, options); 1043 console.info(`success to download the resource. `); 1044 } catch (err) { 1045 console.error(`Failed to download the resource: code: ${err.code}, message: ${err.message}`); 1046 } 1047 } 1048 1049 build() { 1050 Column() { 1051 // 若src指定的是网络图片且已成功下载并缓存，则本次显示无需重复下载。 1052 Image(this.src) 1053 .width(100) 1054 .height(100) 1055 .objectFit(ImageFit.Cover) 1056 .borderWidth(1) 1057 } 1058 .height('100%') 1059 .width('100%') 1060 } 1061} 1062``` 1063 1064### 示例4（为图片添加事件） 1065 1066该示例为图片添加[onClick](ts-universal-events-click.md#onclick)和[onFinish](#onfinish)事件。 1067 1068```ts 1069@Entry 1070@Component 1071struct ImageExample3 { 1072 // $r('app.media.earth')需要替换为开发者所需的图像资源文件。 1073 private imageOne: Resource = $r('app.media.earth'); 1074 // $r('app.media.star')需要替换为开发者所需的图像资源文件。 1075 private imageTwo: Resource = $r('app.media.star'); 1076 // $r('app.media.moveStar')需要替换为开发者所需的图像资源文件。 1077 private imageThree: Resource = $r('app.media.moveStar'); 1078 @State src: Resource = this.imageOne; 1079 @State src2: Resource = this.imageThree; 1080 build(){ 1081 Column(){ 1082 // 为图片添加点击事件，点击完成后加载特定图片 1083 Image(this.src) 1084 .width(100) 1085 .height(100) 1086 .onClick(() => { 1087 this.src = this.imageTwo; 1088 }) 1089 1090 // 当加载图片为SVG格式时 1091 Image(this.src2) 1092 .width(100) 1093 .height(100) 1094 .onFinish(() => { 1095 // SVG动效播放完成时加载另一张图片 1096 this.src2 = this.imageOne; 1097 }) 1098 }.width('100%').height('100%') 1099 } 1100} 1101``` 1102 1103 1104 1105### 示例5（开启图像AI分析） 1106 1107该示例使用[enableAnalyzer](#enableanalyzer11)接口开启图像AI分析。 1108<!--RP2--> 1109 1110```ts 1111import { image } from '@kit.ImageKit'; 1112 1113@Entry 1114@Component 1115struct ImageExample4 { 1116 @State imagePixelMap: image.PixelMap | undefined = undefined; 1117 private aiController: ImageAnalyzerController = new ImageAnalyzerController(); 1118 private options: ImageAIOptions = { 1119 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 1120 aiController: this.aiController 1121 }; 1122 1123 async aboutToAppear() { 1124 // $r('app.media.app_icon')需要替换为开发者所需的图像资源文件。 1125 this.imagePixelMap = await this.getPixmapFromMedia($r('app.media.app_icon')); 1126 } 1127 1128 build() { 1129 Column() { 1130 Image(this.imagePixelMap, this.options) 1131 .enableAnalyzer(true) 1132 .width(200) 1133 .height(200) 1134 .margin({bottom:10}) 1135 Button('getTypes') 1136 .width(80) 1137 .height(80) 1138 .onClick(() => { 1139 this.aiController.getImageAnalyzerSupportTypes(); 1140 }) 1141 } 1142 } 1143 private async getPixmapFromMedia(resource: Resource) { 1144 let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id); 1145 let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength)); 1146 let createPixelMap: image.PixelMap = await imageSource.createPixelMap({ 1147 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 1148 }); 1149 await imageSource.release(); 1150 return createPixelMap; 1151 } 1152} 1153``` 1154 1155 1156<!--RP2End--> 1157### 示例6（通过slice拉伸图片） 1158 1159该示例通过[resizable](#resizable11)属性的slice选项，调整不同方向对图片进行拉伸。 1160 1161```ts 1162@Entry 1163@Component 1164struct Index { 1165 @State top: number = 10; 1166 @State bottom: number = 10; 1167 @State left: number = 10; 1168 @State right: number = 10; 1169 1170 build() { 1171 Column({ space: 5 }) { 1172 // 原图效果 1173 // $r('app.media.landscape')需要替换为开发者所需的图像资源文件。 1174 Image($r("app.media.landscape")) 1175 .width(200).height(200) 1176 .border({ width: 2, color: Color.Pink }) 1177 .objectFit(ImageFit.Contain) 1178 1179 // 图像拉伸效果，设置resizable属性，对图片不同方向进行拉伸 1180 // $r('app.media.landscape')需要替换为开发者所需的图像资源文件。 1181 Image($r("app.media.landscape")) 1182 .resizable({ 1183 slice: { 1184 //传入数字时默认为vp单位，但在不同设备上vp单位会被解析成不同大小的px单位，可以根据需要选择传入的单位 1185 left: `${this.left}px`, 1186 right: `${this.right}px`, 1187 top: `${this.top}px`, 1188 bottom: `${this.bottom}px` 1189 } 1190 }) 1191 .width(200) 1192 .height(200) 1193 .border({ width: 2, color: Color.Pink }) 1194 .objectFit(ImageFit.Contain) 1195 1196 Row() { 1197 Button("add top to " + this.top).fontSize(10) 1198 .onClick(() => { 1199 this.top += 10; 1200 }) 1201 Button("add bottom to " + this.bottom).fontSize(10) 1202 .onClick(() => { 1203 this.bottom += 10; 1204 }) 1205 } 1206 1207 Row() { 1208 Button("add left to " + this.left).fontSize(10) 1209 .onClick(() => { 1210 this.left += 10; 1211 }) 1212 Button("add right to " + this.right).fontSize(10) 1213 .onClick(() => { 1214 this.right += 10; 1215 }) 1216 } 1217 1218 } 1219 .justifyContent(FlexAlign.Start).width('100%').height('100%') 1220 } 1221} 1222``` 1223 1224 1225 1226### 示例7（通过lattice拉伸图片） 1227 1228该示例使用[resizable](#resizable11)属性的lattice选项，使用矩形网格对象对图片进行拉伸。 1229 1230```ts 1231import { drawing } from '@kit.ArkGraphics2D'; 1232 1233@Entry 1234@Component 1235struct drawingLatticeTest { 1236 private xDivs: Array<number> = [1, 2, 200]; 1237 private yDivs: Array<number> = [1, 2, 200]; 1238 private fXCount: number = 3; 1239 private fYCount: number = 3; 1240 private drawingLatticeFirst: DrawingLattice = 1241 drawing.Lattice.createImageLattice(this.xDivs, this.yDivs, this.fXCount, this.fYCount); 1242 1243 build() { 1244 Scroll() { 1245 Column({ space: 10 }) { 1246 Text('Original Image').fontSize(20).fontWeight(700) 1247 Column({ space: 10 }) { 1248 // $r('app.media.mountain')需要替换为开发者所需的图像资源文件。 1249 Image($r('app.media.mountain')) 1250 .width(260).height(260) 1251 }.width('100%') 1252 1253 Text('Resize by lattice').fontSize(20).fontWeight(700) 1254 Column({ space: 10 }) { 1255 // $r('app.media.mountain')需要替换为开发者所需的图像资源文件。 1256 Image($r('app.media.mountain')) 1257 .objectRepeat(ImageRepeat.X) 1258 .width(260) 1259 .height(260) 1260 .resizable({ 1261 lattice: this.drawingLatticeFirst 1262 }) 1263 }.width('100%') 1264 }.width('100%') 1265 } 1266 } 1267} 1268``` 1269 1270 1271 1272### 示例8（播放PixelMap数组动画） 1273 1274该示例通过[AnimatedDrawableDescriptor](../js-apis-arkui-drawableDescriptor.md#animateddrawabledescriptor12)对象播放PixelMap数组动画。 1275 1276```ts 1277import { AnimationOptions, AnimatedDrawableDescriptor } from '@kit.ArkUI'; 1278import { image } from '@kit.ImageKit'; 1279 1280@Entry 1281@Component 1282struct ImageExample { 1283 pixelMaps: PixelMap[] = []; 1284 @State options: AnimationOptions = { iterations: 1 }; 1285 @State animated: AnimatedDrawableDescriptor | undefined = undefined; 1286 1287 async aboutToAppear() { 1288 this.pixelMaps = await this.getPixelMaps(); 1289 this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options); 1290 } 1291 1292 build() { 1293 Column() { 1294 Row() { 1295 Image(this.animated) 1296 .width('500px').height('500px') 1297 .onFinish(() => { 1298 console.info('finish'); 1299 }) 1300 }.height('50%') 1301 1302 Row() { 1303 Button('once').width(100).padding(5).onClick(() => { 1304 this.options = { iterations: 1 }; 1305 this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options); 1306 }).margin(5) 1307 Button('infinite').width(100).padding(5).onClick(() => { 1308 this.options = { iterations: -1 }; 1309 this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options); 1310 }).margin(5) 1311 } 1312 }.width('50%') 1313 } 1314 1315 private async getPixmapListFromMedia(resource: Resource) { 1316 let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id); 1317 let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength)); 1318 let createPixelMap: image.PixelMap[] = await imageSource.createPixelMapList({ 1319 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 1320 }); 1321 await imageSource.release(); 1322 return createPixelMap; 1323 } 1324 1325 private async getPixmapFromMedia(resource: Resource) { 1326 let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id); 1327 let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength)); 1328 let createPixelMap: image.PixelMap = await imageSource.createPixelMap({ 1329 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 1330 }); 1331 await imageSource.release(); 1332 return createPixelMap; 1333 } 1334 1335 private async getPixelMaps() { 1336 // $r('app.media.mountain')需要替换为开发者所需的图像资源文件。 1337 let myPixelMaps: PixelMap[] = await this.getPixmapListFromMedia($r('app.media.mountain')); //添加图片 1338 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 1339 myPixelMaps.push(await this.getPixmapFromMedia($r('app.media.sky'))); 1340 // $r('app.media.clouds')需要替换为开发者所需的图像资源文件。 1341 myPixelMaps.push(await this.getPixmapFromMedia($r('app.media.clouds'))); 1342 // $r('app.media.landscape')需要替换为开发者所需的图像资源文件。 1343 myPixelMaps.push(await this.getPixmapFromMedia($r('app.media.landscape'))); 1344 return myPixelMaps; 1345 } 1346} 1347``` 1348 1349 1350 1351### 示例9（为图像设置颜色滤镜效果） 1352 1353该示例通过[colorFilter](#colorfilter9)属性实现了给图像设置颜色滤镜效果。 1354 1355```ts 1356import { drawing, common2D } from '@kit.ArkGraphics2D'; 1357 1358@Entry 1359@Component 1360struct ImageExample3 { 1361 // $r('app.media.1')需要替换为开发者所需的图像资源文件。 1362 private imageOne: Resource = $r('app.media.1'); 1363 // $r('app.media.2')需要替换为开发者所需的图像资源文件。 1364 private imageTwo: Resource = $r('app.media.2'); 1365 @State src: Resource = this.imageOne; 1366 @State src2: Resource = this.imageTwo; 1367 private colorFilterMatrix: number[] = [1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0]; 1368 private color: common2D.Color = { 1369 alpha: 255, 1370 red: 255, 1371 green: 0, 1372 blue: 0 1373 }; 1374 @State drawingColorFilterFirst: ColorFilter | undefined = undefined; 1375 @State drawingColorFilterSecond: ColorFilter | undefined = undefined; 1376 @State drawingColorFilterThird: ColorFilter | undefined = undefined; 1377 1378 build() { 1379 Column() { 1380 Image(this.src) 1381 .width(100) 1382 .height(100) 1383 .colorFilter(this.drawingColorFilterFirst) 1384 .onClick(()=>{ 1385 this.drawingColorFilterFirst = 1386 drawing.ColorFilter.createBlendModeColorFilter(this.color, drawing.BlendMode.SRC_IN); 1387 }) 1388 1389 Image(this.src2) 1390 .width(100) 1391 .height(100) 1392 .colorFilter(this.drawingColorFilterSecond) 1393 .onClick(()=>{ 1394 this.drawingColorFilterSecond = new ColorFilter(this.colorFilterMatrix); 1395 }) 1396 1397 //当加载图片为svg格式时 1398 // $r('app.media.test_self')需要替换为开发者所需的图像资源文件。 1399 Image($r('app.media.test_self')) 1400 .width(110) 1401 .height(110) 1402 .margin(15) 1403 .colorFilter(this.drawingColorFilterThird) 1404 .onClick(()=>{ 1405 this.drawingColorFilterThird = 1406 drawing.ColorFilter.createBlendModeColorFilter(this.color, drawing.BlendMode.SRC_IN); 1407 }) 1408 } 1409 } 1410} 1411``` 1412 1413 1414### 示例10（为图像设置填充效果） 1415 1416该示例通过[objectFit](#objectfit)属性为图像设置填充效果。 1417 1418```ts 1419@Entry 1420@Component 1421struct ImageExample{ 1422 build() { 1423 Column() { 1424 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 1425 Row() { 1426 // 加载png格式图片 1427 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 1428 Image($r('app.media.sky')) 1429 .width(110).height(110).margin(15) 1430 .overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1431 .border({ width: 2, color: Color.Pink }) 1432 .objectFit(ImageFit.TOP_START) 1433 // 加载gif格式图片 1434 // $r('app.media.loading')需要替换为开发者所需的图像资源文件。 1435 Image($r('app.media.loading')) 1436 .width(110).height(110).margin(15) 1437 .overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1438 .border({ width: 2, color: Color.Pink }) 1439 .objectFit(ImageFit.BOTTOM_START) 1440 } 1441 Row() { 1442 // 加载svg格式图片 1443 // $r('app.media.svg')需要替换为开发者所需的图像资源文件。 1444 Image($r('app.media.svg')) 1445 .width(110).height(110).margin(15) 1446 .overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1447 .border({ width: 2, color: Color.Pink }) 1448 .objectFit(ImageFit.TOP_END) 1449 // 加载jpg格式图片 1450 // $r('app.media.jpg')需要替换为开发者所需的图像资源文件。 1451 Image($r('app.media.jpg')) 1452 .width(110).height(110).margin(15) 1453 .overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) 1454 .border({ width: 2, color: Color.Pink }) 1455 .objectFit(ImageFit.CENTER) 1456 } 1457 } 1458 }.height(320).width(360).padding({ right: 10, top: 10 }) 1459 } 1460} 1461``` 1462 1463 1464 1465### 示例11（切换显示不同类型图片） 1466 1467该示例展示了[ResourceStr](ts-types.md#resourcestr)类型与[ImageContent](#imagecontent12)类型作为数据源的显示图片效果。 1468 1469```ts 1470@Entry 1471@Component 1472struct ImageContentExample { 1473 @State imageSrcIndex: number = 0; 1474 // $r('app.media.app_icon')需要替换为开发者所需的图像资源文件。 1475 @State imageSrcList: (ResourceStr | ImageContent)[] = [$r('app.media.app_icon'), ImageContent.EMPTY]; 1476 1477 build() { 1478 Column({ space: 10 }) { 1479 Image(this.imageSrcList[this.imageSrcIndex]) 1480 .width(100) 1481 .height(100) 1482 Button('点击切换Image的src') 1483 .padding(20) 1484 .onClick(() => { 1485 this.imageSrcIndex = (this.imageSrcIndex + 1) % this.imageSrcList.length; 1486 }) 1487 }.width('100%') 1488 .padding(20) 1489 } 1490} 1491``` 1492 1493 1494 1495### 示例12（配置隐私隐藏） 1496 1497该示例通过[privacySensitive](#privacysensitive12)属性展示了如何配置隐私隐藏，效果展示需要卡片框架支持。 1498 1499```ts 1500@Entry 1501@Component 1502struct ImageExample { 1503 build() { 1504 Column({ space: 10 }) { 1505 // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。 1506 Image($r('app.media.startIcon')) 1507 .width(50) 1508 .height(50) 1509 .margin({top :30}) 1510 .privacySensitive(true) 1511 } 1512 .alignItems(HorizontalAlign.Center) 1513 .width('100%') 1514 } 1515} 1516``` 1517 1518 1519 1520### 示例13（为图片设置扫光效果） 1521 1522该示例通过[linearGradient](./ts-basic-components-datapanel.md#lineargradient10)接口和[animateTo()](./ts-explicit-animation.md)接口实现了给图片设置扫光效果。 1523 1524```ts 1525import { curves } from '@kit.ArkUI'; 1526 1527@Entry 1528@Component 1529struct ImageExample11 { 1530 private curve = curves.cubicBezierCurve(0.33, 0, 0.67, 1); 1531 @State moveImg: string[] = ['imageScanEffect']; 1532 @State moveImgVisible: Visibility = Visibility.Visible; 1533 @State durationTime: number = 1500; 1534 @State iterationsTimes: number = -1; 1535 @State private opacityValue: number = 0.5; 1536 @State imageWidth: number = 450; 1537 @State visible: Visibility = Visibility.Hidden; 1538 @State stackBackgroundColor: string = '#E1E4E9'; 1539 @State linePositionX: number = 0 - this.imageWidth; 1540 @State linePositionY: number = 0; 1541 @State imgResource: Resource | undefined = undefined; 1542 1543 startupAnimate() { 1544 this.moveImg.pop(); 1545 this.moveImg.push('imageScanEffect'); 1546 setTimeout(() => { 1547 // $r('app.media.img')需要替换为开发者所需的图像资源文件。 1548 this.imgResource = $r('app.media.img'); 1549 }, 3000); 1550 this.getUIContext()?.animateTo({ 1551 duration: this.durationTime, 1552 curve: this.curve, 1553 tempo: 1, 1554 iterations: this.iterationsTimes, 1555 delay: 0 1556 }, () => { 1557 this.linePositionX = this.imageWidth; 1558 }) 1559 } 1560 1561 build() { 1562 Column() { 1563 Row() { 1564 Stack() { 1565 Image(this.imgResource) 1566 .width(this.imageWidth) 1567 .height(200) 1568 .objectFit(ImageFit.Contain) 1569 .visibility(this.visible) 1570 .onComplete(() => { 1571 this.visible = Visibility.Visible; 1572 this.moveImg.pop(); 1573 }) 1574 .onError(() =>{ 1575 setTimeout(() => { 1576 this.visible = Visibility.Visible; 1577 this.moveImg.pop(); 1578 }, 2600) 1579 }) 1580 ForEach(this.moveImg, (item: string) => { 1581 Row() 1582 .width(this.imageWidth) 1583 .height(200) 1584 .visibility(this.moveImgVisible) 1585 .position({ x: this.linePositionX, y: this.linePositionY }) 1586 .linearGradient({ 1587 direction: GradientDirection.Right, 1588 repeating: false, 1589 colors: [[0xE1E4E9, 0], [0xFFFFFF, 0.75], [0xE1E4E9, 1]] 1590 }) 1591 .opacity(this.opacityValue) 1592 }) 1593 } 1594 .backgroundColor(this.visible ? this.stackBackgroundColor : undefined) 1595 .margin({top: 20, left: 20, right: 20}) 1596 .borderRadius(20) 1597 .clip(true) 1598 .onAppear(() => { 1599 this.startupAnimate(); 1600 }) 1601 } 1602 } 1603 } 1604} 1605``` 1606 1607 1608 1609### 示例14（为图片添加变换效果） 1610 1611该示例通过[imageMatrix](#imagematrix15)和[objectFit](#objectfit)属性，为图片添加旋转和平移的效果。 1612 1613```ts 1614import { matrix4 } from '@kit.ArkUI'; 1615 1616@Entry 1617@Component 1618struct Test { 1619 private matrix1 = matrix4.identity() 1620 .translate({ x: -400, y: -750 }) 1621 .scale({ x: 0.5, y: 0.5 }) 1622 .rotate({ 1623 x: 2, 1624 y: 0.5, 1625 z: 3, 1626 centerX: 10, 1627 centerY: 10, 1628 angle: -10 1629 }) 1630 1631 build() { 1632 Row() { 1633 Column({ space: 50 }) { 1634 Column({ space: 5 }) { 1635 // $r('app.media.example')需要替换为开发者所需的图像资源文件。 1636 Image($r('app.media.example')) 1637 .border({ width:2, color: Color.Black }) 1638 .objectFit(ImageFit.Contain) 1639 .width(150) 1640 .height(150) 1641 Text('图片无变换') 1642 .fontSize('25px') 1643 } 1644 Column({ space: 5 }) { 1645 // $r('app.media.example')需要替换为开发者所需的图像资源文件。 1646 Image($r('app.media.example')) 1647 .border({ width:2, color: Color.Black }) 1648 .objectFit(ImageFit.None) 1649 .translate({ x: 10, y: 10 }) 1650 .scale({ x: 0.5, y: 0.5 }) 1651 .width(100) 1652 .height(100) 1653 Text('Image直接变换，默认显示图源左上角。') 1654 .fontSize('25px') 1655 } 1656 Column({ space: 5 }) { 1657 // $r('app.media.example')需要替换为开发者所需的图像资源文件。 1658 Image($r('app.media.example')) 1659 .objectFit(ImageFit.MATRIX) 1660 .imageMatrix(this.matrix1) 1661 .border({ width:2, color: Color.Black }) 1662 .width(150) 1663 .height(150) 1664 Text('通过imageMatrix变换，调整图源位置，实现最佳呈现。') 1665 .fontSize('25px') 1666 } 1667 } 1668 .width('100%') 1669 } 1670 } 1671} 1672``` 1673 1674 1675 1676### 示例15（通过sourceSize设置图片解码尺寸） 1677 1678该示例通过[sourceSize](ts-basic-components-image.md#sourcesize)接口自定义图片的解码尺寸。 1679 1680```ts 1681@Entry 1682@Component 1683struct Index { 1684 @State borderRadiusValue: number = 10; 1685 build() { 1686 Column() { 1687 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 1688 Image($r('app.media.sky')) 1689 .sourceSize({width:1393, height:1080}) 1690 .height(300) 1691 .width(300) 1692 .objectFit(ImageFit.Contain) 1693 .borderWidth(1) 1694 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 1695 Image($r('app.media.sky')) 1696 .sourceSize({width:13, height:10}) 1697 .height(300) 1698 .width(300) 1699 .objectFit(ImageFit.Contain) 1700 .borderWidth(1) 1701 } 1702 .height('100%') 1703 .width('100%') 1704 } 1705} 1706``` 1707 1708 1709 1710### 示例16（通过renderMode设置图片的渲染模式） 1711 1712该示例通过[renderMode](ts-basic-components-image.md#rendermode)接口设置图片渲染模式为黑白模式。 1713 1714```ts 1715@Entry 1716@Component 1717struct Index { 1718 @State borderRadiusValue: number = 10; 1719 build() { 1720 Column() { 1721 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 1722 Image($r('app.media.sky')) 1723 .renderMode(ImageRenderMode.Template) 1724 .height(300) 1725 .width(300) 1726 .objectFit(ImageFit.Contain) 1727 .borderWidth(1) 1728 } 1729 .height('100%') 1730 .width('100%') 1731 } 1732} 1733``` 1734 1735 1736 1737### 示例17（通过objectRepeat设置图片的重复样式） 1738 1739该示例通过[objectRepeat](ts-basic-components-image.md#objectrepeat)接口在竖直轴上重复绘制图片。 1740 1741```ts 1742@Entry 1743@Component 1744struct Index { 1745 @State borderRadiusValue: number = 10; 1746 build() { 1747 Column() { 1748 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 1749 Image($r('app.media.sky')) 1750 .objectRepeat(ImageRepeat.Y) 1751 .height('90%') 1752 .width('90%') 1753 .objectFit(ImageFit.Contain) 1754 .borderWidth(1) 1755 } 1756 .height('100%') 1757 .width('100%') 1758 } 1759} 1760``` 1761 1762 1763 1764### 示例18（设置SVG图片的填充颜色） 1765 1766该示例通过[fillColor](#fillcolor15)属性为SVG图片设置不同颜色的填充效果。 1767 1768```ts 1769@Entry 1770@Component 1771struct Index { 1772 build() { 1773 Column() { 1774 Text('不设置fillColor') 1775 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 1776 Image($r('app.media.svgExample')) 1777 .height(100) 1778 .width(100) 1779 .objectFit(ImageFit.Contain) 1780 .borderWidth(1) 1781 Text('fillColor传入ColorContent.ORIGIN') 1782 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 1783 Image($r('app.media.svgExample')) 1784 .height(100) 1785 .width(100) 1786 .objectFit(ImageFit.Contain) 1787 .borderWidth(1) 1788 .fillColor(ColorContent.ORIGIN) 1789 Text('fillColor传入Color.Blue') 1790 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 1791 Image($r('app.media.svgExample')) 1792 .height(100) 1793 .width(100) 1794 .objectFit(ImageFit.Contain) 1795 .borderWidth(1) 1796 .fillColor(Color.Blue) 1797 Text('fillColor传入undefined') 1798 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 1799 Image($r('app.media.svgExample')) 1800 .height(100) 1801 .width(100) 1802 .objectFit(ImageFit.Contain) 1803 .borderWidth(1) 1804 .fillColor(undefined) 1805 } 1806 .height('100%') 1807 .width('100%') 1808 } 1809} 1810``` 1811 1812 1813 1814### 示例19（设置HDR图源动态提亮） 1815 1816该示例通过[hdrBrightness](#hdrbrightness19)属性调整HDR图源的亮度，将hdrBrightness从0调整到1。 1817 1818```ts 1819import { image } from '@kit.ImageKit'; 1820 1821const TAG = 'AceImage'; 1822 1823@Entry 1824@Component 1825struct Index { 1826 // 'img_1'需要替换为开发者所需的图像资源文件。 1827 @State imgUrl: string = 'img_1'; 1828 @State bright: number = 0; // 默认亮度为0 1829 aboutToAppear(): void { 1830 // 获取资源管理器中的媒体资源 1831 let img = this.getUIContext().getHostContext()?.resourceManager.getMediaByNameSync(this.imgUrl); 1832 // 创建图片源并获取图片信息 1833 if (img && img.buffer) { 1834 let imageSource = image.createImageSource(img?.buffer.slice(0)); 1835 let imageInfo = imageSource.getImageInfoSync(); 1836 // 检查图片信息是否获取成功 1837 if (imageInfo == undefined) { 1838 console.error(TAG, 'Failed to obtain the image information.'); 1839 } else { 1840 // 成功获取到图片信息，打印HDR状态 1841 console.info(TAG, 'imageInfo.isHdr:' + imageInfo.isHdr); 1842 } 1843 } else { 1844 console.error(TAG, 'Failed to obtain the image buffer.'); 1845 } 1846 } 1847 1848 build() { 1849 Column() { 1850 // $r('app.media.img_1')需要替换为开发者所需的图像资源文件。 1851 Image($r('app.media.img_1')).width('50%') 1852 .height('auto') 1853 .margin({ top: 160 }) 1854 .hdrBrightness(this.bright) // 设置图片的HDR亮度，值由bright状态控制 1855 Button('图片动态提亮 0->1') 1856 .onClick(() => { 1857 // 动画过渡，切换亮度值 1858 this.getUIContext()?.animateTo({}, () => { 1859 this.bright = 1.0 - this.bright; 1860 }); 1861 }) 1862 } 1863 .height('100%') 1864 .width('100%') 1865 } 1866} 1867``` 1868 1869### 示例20（设置图片是否跟随系统语言方向） 1870 1871该示例通过[matchTextDirection](#matchtextdirection)接口，设置手机语言为维语时图片是否显示镜像翻转显示效果。 1872 1873```ts 1874@Entry 1875@Component 1876struct Index { 1877 build() { 1878 Column() { 1879 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 1880 Row() { 1881 // 图片不跟随系统语言方向 1882 // $r('app.media.ocean')需要替换为开发者所需的图像资源文件。 1883 Image($r('app.media.ocean')) 1884 .width(110).height(110).margin(15) 1885 .matchTextDirection(false) 1886 } 1887 Row() { 1888 // 图片跟随系统语言方向 1889 // $r('app.media.ocean')需要替换为开发者所需的图像资源文件。 1890 Image($r('app.media.ocean')) 1891 .width(110).height(110).margin(15) 1892 .matchTextDirection(true) 1893 } 1894 } 1895 }.height(320).width(360).padding({ right: 10, top: 10 }) 1896 } 1897} 1898``` 1899 1900 1901 1902### 示例21（设置图像内容的显示方向） 1903 1904该示例通过[orientation](#orientation14)属性，设置图像内容的显示方向。 1905 1906```ts 1907@Entry 1908@Component 1909struct OrientationExample { 1910 build() { 1911 Column() { 1912 Row({ space: 25 }) { 1913 Column() { 1914 Text('AUTO') 1915 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1916 Image($r('app.media.hello')) 1917 .width(125).height(125) 1918 .orientation(ImageRotateOrientation.AUTO) 1919 } 1920 1921 Column() { 1922 Text('UP') 1923 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1924 Image($r('app.media.hello')) 1925 .width(125).height(125) 1926 .orientation(ImageRotateOrientation.UP) 1927 } 1928 1929 Column() { 1930 Text('RIGHT') 1931 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1932 Image($r('app.media.hello')) 1933 .width(125).height(125) 1934 .orientation(ImageRotateOrientation.RIGHT) 1935 } 1936 } 1937 1938 Row({ space: 25 }) { 1939 Column() { 1940 Text('DOWN') 1941 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1942 Image($r('app.media.hello')) 1943 .width(125).height(125) 1944 .orientation(ImageRotateOrientation.DOWN) 1945 } 1946 1947 Column() { 1948 Text('LEFT') 1949 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1950 Image($r('app.media.hello')) 1951 .width(125).height(125) 1952 .orientation(ImageRotateOrientation.LEFT) 1953 } 1954 1955 Column() { 1956 Text('UP_MIRRORED') 1957 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1958 Image($r('app.media.hello')) 1959 .width(125).height(125) 1960 .orientation(ImageRotateOrientation.UP_MIRRORED) 1961 } 1962 } 1963 1964 Row({ space: 15 }) { 1965 Column() { 1966 Text('RIGHT_MIRRORED') 1967 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1968 Image($r('app.media.hello')) 1969 .width(125).height(125) 1970 .orientation(ImageRotateOrientation.RIGHT_MIRRORED) 1971 } 1972 1973 Column() { 1974 Text('DOWN_MIRRORED') 1975 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1976 Image($r('app.media.hello')) 1977 .width(125).height(125) 1978 .orientation(ImageRotateOrientation.DOWN_MIRRORED) 1979 } 1980 1981 Column() { 1982 Text('LEFT_MIRRORED') 1983 // $r('app.media.hello')需要替换为开发者所需的图像资源文件。 1984 Image($r('app.media.hello')) 1985 .width(125).height(125) 1986 .orientation(ImageRotateOrientation.LEFT_MIRRORED) 1987 } 1988 } 1989 } 1990 } 1991} 1992``` 1993 1994 1995 1996### 示例22（获取图片的exif信息并设置图像内容的显示方向） 1997 1998该示例通过[getImageProperty](../../apis-image-kit/arkts-apis-image-ImageSource.md#getimageproperty11)接口，获取图片的exif信息，再根据获取到的exif信息，通过[orientation](#orientation14)属性设置图像内容显示为正确方向。 1999 2000```ts 2001import { image } from '@kit.ImageKit'; 2002import { resourceManager } from '@kit.LocalizationKit'; 2003 2004@Entry 2005@Component 2006struct Example { 2007 @State rotateOrientation: ImageRotateOrientation = ImageRotateOrientation.UP; 2008 @State pixelMap: image.PixelMap | undefined = undefined; 2009 @State text1: string = 'The exif orientation is '; 2010 @State text2: string = 'Set orientation to '; 2011 2012 // 根据获取到的EXIF方向信息，转换ImageRotateOrientation，使图片显示为正确的方向。 2013 getOrientation(orientation: string): ImageRotateOrientation { 2014 if (orientation == 'Top-right') { 2015 this.text2 = this.text2 + 'UP_MIRRORED'; 2016 return ImageRotateOrientation.UP_MIRRORED; 2017 } else if (orientation == 'Bottom-right') { 2018 this.text2 = this.text2 + 'DOWN'; 2019 return ImageRotateOrientation.DOWN; 2020 } else if (orientation == 'Bottom-left') { 2021 this.text2 = this.text2 + 'DOWN_MIRRORED'; 2022 return ImageRotateOrientation.DOWN_MIRRORED; 2023 } else if (orientation == 'Left-top') { 2024 this.text2 = this.text2 + 'LEFT_MIRRORED'; 2025 return ImageRotateOrientation.LEFT_MIRRORED; 2026 } else if (orientation == 'Right-top') { 2027 this.text2 = this.text2 + 'RIGHT'; 2028 return ImageRotateOrientation.RIGHT; 2029 } else if (orientation == 'Right-bottom') { 2030 this.text2 = this.text2 + 'RIGHT_MIRRORED'; 2031 return ImageRotateOrientation.RIGHT_MIRRORED; 2032 } else if (orientation == 'Left-bottom') { 2033 this.text2 = this.text2 + 'LEFT'; 2034 return ImageRotateOrientation.LEFT; 2035 } else if (orientation == 'Top-left') { 2036 this.text2 = this.text2 + 'UP'; 2037 return ImageRotateOrientation.UP; 2038 } else { 2039 this.text2 = this.text2 + 'UP'; 2040 return ImageRotateOrientation.UP; 2041 } 2042 } 2043 2044 async getFileBuffer(context: Context): Promise<ArrayBuffer | undefined> { 2045 try { 2046 const resourceMgr: resourceManager.ResourceManager = context.resourceManager; 2047 // 传入带有EXIF信息的资源文件，获取资源文件内容，返回Uint8Array。 2048 // 'hello.jpg'需要替换为开发者所需的图像资源文件。 2049 const fileData: Uint8Array = await resourceMgr.getRawFileContent('hello.jpg'); 2050 console.info('Successfully get RawFileContent'); 2051 // 转为ArrayBuffer并返回。 2052 const buffer: ArrayBuffer = fileData.buffer.slice(0); 2053 return buffer; 2054 } catch (error) { 2055 console.error('Failed to get RawFileContent'); 2056 return undefined; 2057 } 2058 } 2059 2060 aboutToAppear() { 2061 let context = this.getUIContext().getHostContext(); 2062 if (!context) { 2063 return; 2064 } 2065 this.getFileBuffer(context).then((buf: ArrayBuffer | undefined) => { 2066 let imageSource = image.createImageSource(buf); 2067 if (!imageSource) { 2068 return; 2069 } 2070 // 从图像源中读取图片的EXIF方向信息。 2071 imageSource.getImageProperty(image.PropertyKey.ORIENTATION).then((orientation) => { 2072 this.rotateOrientation = this.getOrientation(orientation); 2073 this.text1 = this.text1 + orientation; 2074 let options: image.DecodingOptions = { 2075 'editable': true, 2076 'desiredPixelFormat': image.PixelMapFormat.RGBA_8888, 2077 } 2078 imageSource.createPixelMap(options).then((pixelMap: image.PixelMap) => { 2079 this.pixelMap = pixelMap; 2080 imageSource.release(); 2081 }); 2082 }).catch(() => { 2083 imageSource.release(); 2084 }); 2085 }) 2086 } 2087 2088 build() { 2089 Column({ space: 40 }) { 2090 Column({ space: 10 }) { 2091 Text('before').fontSize(20).fontWeight(700) 2092 // 'hello.jpg'需要替换为开发者所需的图像资源文件。 2093 Image($rawfile('hello.jpg')) 2094 .width(100) 2095 .height(100) 2096 Text(this.text1) 2097 } 2098 2099 Column({ space: 10 }) { 2100 Text('after').fontSize(20).fontWeight(700) 2101 Image(this.pixelMap) 2102 .width(100) 2103 .height(100) 2104 .orientation(this.rotateOrientation) 2105 Text(this.text2) 2106 } 2107 } 2108 .height('80%') 2109 .width('100%') 2110 } 2111} 2112``` 2113 2114 2115 2116### 示例23（动态切换SVG图片的填充颜色） 2117 2118通过按钮切换不同色域下的颜色值，动态改变SVG图片的填充颜色效果，以展示[ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12)类型的使用方式和显示差异。 2119 2120```ts 2121import { ColorMetrics } from '@kit.ArkUI'; 2122@Entry 2123@Component 2124struct fillColorMetricsDemo { 2125 @State p3Red: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0.631, 0.0392, 0.1294); 2126 @State sRGBRed: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.SRGB, 0.631, 0.0392, 0.1294); 2127 @State p3Green: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0.09, 0.662 ,0.552); 2128 @State sRGBGreen: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.SRGB, 0.09, 0.662 ,0.552); 2129 @State p3Blue: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0, 0.290 ,0.686); 2130 @State sRGBBlue: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.SRGB, 0, 0.290 ,0.686); 2131 @State colorArray: (Color|undefined|ColorMetrics|ColorContent)[] = [ 2132 this.p3Red, this.sRGBRed, this.p3Green, this.sRGBGreen, this.p3Blue, 2133 this.sRGBBlue, ColorContent.ORIGIN, Color.Gray, undefined 2134 ] 2135 @State colorArrayStr: string[] = [ 2136 "P3 Red", "SRGB Red", "P3 Green", "SRGB Green", 2137 "P3 Blue", "SRGB Blue", "ORIGIN", "Gray", "undefined" 2138 ] 2139 @State arrayIdx: number = 0 2140 build() { 2141 Column() { 2142 Text("FillColor is " + this.colorArrayStr[this.arrayIdx]) 2143 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 2144 Image($r('app.media.svgExample')) 2145 .width(110).height(110).margin(15) 2146 .fillColor(this.colorArray[this.arrayIdx]) 2147 Button("ChangeFillColor") 2148 .onClick(()=>{ 2149 this.arrayIdx = (this.arrayIdx + 1) % this.colorArray.length 2150 }) 2151 Blank().height(30).width('100%') 2152 Text("FillColor is SRGB Red") 2153 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 2154 Image($r('app.media.svgExample')) 2155 .width(110).height(110).margin(15) 2156 .fillColor(this.sRGBRed) 2157 Blank().height(30).width('100%') 2158 Text("FillColor is SRGB Green") 2159 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 2160 Image($r('app.media.svgExample')) 2161 .width(110).height(110).margin(15) 2162 .fillColor(this.sRGBGreen) 2163 Blank().height(30).width('100%') 2164 Text("FillColor is SRGB Blue") 2165 // $r('app.media.svgExample')需要替换为开发者所需的图像资源文件。 2166 Image($r('app.media.svgExample')) 2167 .width(110).height(110).margin(15) 2168 .fillColor(this.sRGBBlue) 2169 } 2170 } 2171} 2172``` 2173 2174 2175 2176 2177### 示例24（使用应用沙箱路径显示图片） 2178 2179在当前应用的`haps/entry/files`目录下预置一张名为`cloud.png`的图片，随后使用应用沙箱路径显示该图片。 2180 2181```ts 2182import { fileUri } from '@kit.CoreFileKit'; 2183 2184@Entry 2185@Component 2186struct Index { 2187 private getSandBoxUri(): string { 2188 let context = this.getUIContext().getHostContext(); 2189 if (!context) { 2190 return ''; 2191 } 2192 // /data/storage/el2/base/haps/entry/files/cloud.png 2193 // 从应用沙箱中的文件路径获取URI 2194 // '/cloud.png'需要替换为开发者所需的图像资源文件。 2195 return fileUri.getUriFromPath(context.filesDir + '/cloud.png'); 2196 } 2197 2198 build() { 2199 Column() { 2200 Image(this.getSandBoxUri()) 2201 .width(150) 2202 .height(150) 2203 } 2204 .height('100%') 2205 .width('100%') 2206 } 2207} 2208``` 2209 2210 2211 2212### 示例25（使用相对路径显示图片） 2213 2214在工程`pages`目录同级位置创建`common`目录，在`common`目录下预置一张名为`cloud1.png`的图片，随后使用相对路径显示该图片。 2215 2216```ts 2217@Entry 2218@Component 2219struct Index { 2220 build() { 2221 Column({ space: 10 }) { 2222 Image('common/cloud1.png') 2223 .width(100) 2224 .height(100) 2225 } 2226 .height('100%') 2227 .width('100%') 2228 } 2229} 2230``` 2231
;){kind=link}
