鸿蒙HarmonyOS NEXT开发：Image（基础组件）

Image

Image为图片组件，常用于在应用中显示图片。Image支持加载PixelMap、ResourceStr和DrawableDescriptor类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式。

说明：

该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

使用快捷组合键对Image组件复制时，Image组件必须处于获焦状态。Image组件默认不获焦，需将focusable属性设置为true，即可使用TAB键将焦点切换到组件上，再将focusOnTouch属性设置为true，即可实现点击获焦。

图片设置为svg图源时，当前支持的标签是svg、rect、circle、ellipse、path、line、polyline、polygon、feFlood、feBlend、feColorMatrix、feGaussianBlur、feComposite、filter、mask和use。

需要权限

使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考声明权限。

子组件

无

接口

Image(src: PixelMap | ResourceStr | DrawableDescriptor)

通过图片数据源获取图片，用于后续渲染展示。

Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。

Image组件默认按照居中裁剪，例如组件宽高设置相同，原图长宽不等，此时按照中间区域进行裁剪。

Image加载成功且组件不设置宽高时，其显示大小自适应父组件。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	参数类型	必填	参数描述
src	PixelMap | ResourceStr| DrawableDescriptor	是	图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。 1. PixelMap格式为像素图，常用于图片编辑的场景。 2. ResourceStr包含Resource和string格式。 string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image(“common/test.jpg”)，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。 - 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。 - 支持file://路径前缀的字符串，应用沙箱URI：file://<bundleName>/<sandboxPath>。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。 3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。 说明： - ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。 - ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。 - ArkTS卡片上不支持 PixelMap类型。 - 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。 - 网络图片必须支持RFC 9113标准，否则会导致加载失败。 - 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用HTTP工具提前预下载，提高图片加载性能，方便应用侧管理数据。 - 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。 - 如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。

属性

属性的详细使用指导请参考添加属性。除支持通用属性外，还支持以下属性：

alt

alt(value: string | Resource  | PixelMap)

设置图片加载时显示的占位图。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string | Resource | PixelMap12+	是	加载时显示的占位图，支持本地图片（png、jpg、bmp、svg、gif和heif类型）,支持PixelMap类型图片，不支持网络图片。 默认值：null

objectFit

objectFit(value: ImageFit)

设置图片的填充效果。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ImageFit	是	图片的填充效果。 默认值：ImageFit.Cover

objectRepeat

objectRepeat(value: ImageRepeat)

设置图片的重复样式，从中心点向两边重复，剩余空间不足放下一张图片时会截断。svg类型图源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ImageRepeat	是	图片的重复样式。 默认值：ImageRepeat.NoRepeat

interpolation

interpolation(value: ImageInterpolation)

设置图片的插值效果，即缓解图片在缩放时的锯齿问题。svg类型图源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ImageInterpolation	是	图片的插值效果。 默认值：ImageInterpolation.Low

renderMode

renderMode(value: ImageRenderMode)

设置图片的渲染模式。svg类型图源不支持该属性。<