鸿蒙5.0开发进阶:UI框架-ArkTS组件(Image)

往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)


Image

Image为图片组件,常用于在应用中显示图片。Image支持加载PixelMapResourceStrDrawableDescriptor类型的数据源,支持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 | ResourceStrDrawableDescriptor

图片的数据源,支持本地图片和网络图片。

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 | ResourceStrDrawableDescriptorImageContent

图片的数据源,支持本地图片和网络图片。

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. 传入

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值