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