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