往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)
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图源
动图在Image组件不可见时停止动画,通过onVisibleAreaChange事件实现组件的可见状态,可见阈值ratios大于0时,Image可见。
需要权限
使用网络图片时,需要申请权限ohos.permission.INTERNET。
子组件
无
接口
Image
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>。当访问的路径中包含特殊符号时,需要使用fileUri.getUriFromPath(path)去做转换。同时需要保证目录包路径下的文件有可读权限。 Resource格式可以跨包/跨模块访问资源文件,是访问本地图片的推荐方式。 3. 当传入资源id或name为普通图片时,生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。 说明: - ArkTS卡片上支持gif图片格式动效,但仅在显示时播放一次。 - ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。 - ArkTS卡片上不支持 PixelMap类型。 - 加载本地图片过程中,如果对图片进行修改或者替换,可能会引起应用崩溃。因此需要覆盖图片文件时,应该先删除该文件再重新创建一个同名文件。 - 网络图片必须支持RFC 9113标准,否则会导致加载失败。 - 如果下载的网络图片大于10MB或一次下载的网络图片数量较多,建议使用HTTP工具提前预下载,提高图片加载性能,方便应用侧管理数据。 - Image直接传入URL可能会带来的潜在性能问题,例如:(1) 大图加载时无法提前下载,白块显示的时间较长;(2) 小图设置同步加载,在弱网环境下,可能会阻塞UI线程造成冻屏问题;(3) 在快速滑动的瀑布流中,无法提前对即将要显示的图片进行下载,导致滑动白块较多;不同场景下,性能问题会有不同的表现,建议将网络下载部分与Image的显示剥离,可提前下载或者异步下载。 - 如果SVG图片没有原生大小,需要给Image组件设置宽高,否则不显示。 - 如果SVG图片通过image标签引用本地其他图片,被引用的图片不支持svg格式和gif格式。 - src由有效切换为无效时,图片保持不动。 - 当Image组件入参为PixelMap类型时,只有当PixelMap对象的引用发生变化(即指向一个新的PixelMap实例),Image组件才能感知到数据的变化。仅修改PixelMap对象的内容(如像素值)而不更换对象引用,无法触发数据变化的感知。 |
Image12+
Image(src: PixelMap | ResourceStr | DrawableDescriptor | ImageContent)
src新增ImageContent类型,可指定对应的图形内容。
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
src | PixelMap | ResourceStr| DrawableDescriptor| ImageContent | 是 | 图片的数据源,支持本地图片和网络图片。 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>。当访问的路径中包含特殊符号时,需要使用fileUri.getUriFromPath(path)去做转换。同时需要保证目录包路径下的文件有可读权限。 Resource格式可以跨包/跨模块访问资源文件,是访问本地图片的推荐方式。 3. 当传入资源id或name为普通图片时,生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。 4. 传入 |