
HarmonyOS API:基础组件
版本:v3.1 Beta
Image
更新时间: 2023-03-03 17:21
图片组件,支持本地图片和网络图片的渲染展示。
说明
该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
需要权限
使用网络图片时,需要申请权限ohos.permission.INTERNET。具体申请方式请参考权限申请声明。
子组件
无
接口
Image(src: string | PixelMap | Resource)
通过图片数据源获取图片,用于后续渲染展示。
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
src | string| PixelMap | Resource | 是 | 图片的数据源,支持本地图片和网络图片。 当使用相对路径引用图片资源时,例如Image("common/test.jpg"),不支持跨包/跨模块调用该Image组件,建议使用$r方式来管理需全局使用的图片资源。 - 支持的图片格式包括png、jpg、bmp、svg和gif。 - 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp];base64,[base64 data], 其中[base64 data]为Base64字符串数据。 - 支持datashare://路径前缀的字符串,用于访问通过data ability提供的图片路径。图片加载前需要申请媒体库功能相关权限。 - 支持file:///data/storage路径前缀的字符串,用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 |
属性
除支持通用属性外,还支持以下属性:
名称 | 参数类型 | 描述 |
alt | string | Resource | 加载时显示的占位图,支持本地图片。 |
objectFit | 设置图片的缩放类型。 默认值:ImageFit.Cover | |
objectRepeat | 设置图片的重复样式。 默认值:ImageRepeat.NoRepeat 说明: svg类型图源不支持该属性。 | |
interpolation | 设置图片的插值效果,即减轻低清晰度图片在放大显示的时候出现的锯齿问题,仅针对图片放大插值。 默认值:ImageInterpolation.None 说明: svg类型图源不支持该属性。 PixelMap资源不支持该属性。 | |
renderMode | 设置图片渲染的模式。 默认值:ImageRenderMode.Original 说明: svg类型图源不支持该属性。 | |
sourceSize | { width: number, height: number } | 设置图片裁剪尺寸,将原始图片解码成pixelMap,指定尺寸的图片,单位为px。 说明: PixelMap资源和SVG图片不支持该属性。 |
matchTextDirection | boolean | 设置图片是否跟随系统语言方向,在RTL语言环境下显示镜像翻转显示效果。 默认值:false |
fitOriginalSize | boolean | 图片组件尺寸未设置时,其显示尺寸是否跟随图源尺寸。 默认值:false |
fillColor | 填充颜色。设置的填充颜色会覆盖在图片上。仅对svg图源生效,设置后会替换svg图片的fill颜色。 | |
autoResize | boolean | 是否需要在图片解码过程中对图源做resize操作,该操作会根据显示区域的尺寸决定用于绘制的图源尺寸,有利于减少内存占用。 默认值:true |
syncLoad8+ | boolean | 设置是否同步加载图片,默认是异步加载。同步加载时阻塞UI线程,不会显示占位图。 默认值:false |
copyOption9+ | 设置图片是否可复制(SVG图片不支持复制)。 当copyOption设置为非CopyOptions.None时,支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。 默认值:CopyOptions.None | |
colorFilter9+ | 给图像设置颜色滤镜效果。 |
说明
使用快捷组合键对Image组件复制的前提是,该组件必须处于获焦状态。将Image组件的属性focusable设置为true,即可使用TAB键将焦点切换到Image组件上,再将Image组件的focusOnTouch属性设置为true,即可实现点击获焦。
图片设置svg图源时,支持的标签范围有限,目前支持的svg标签包括svg、rect、circle、ellipse、path、line、polyline、polygon、animate。
ImageInterpolation
名称 | 描述 |
None | 不使用插值图片数据。 |
High | 插值图片数据的使用率高,可能会影响图片渲染的速度。 |
Medium | 插值图片数据的使用率中。 |
Low | 插值图片数据的使用率低。 |
ImageRenderMode
名称 | 描述 |
Original | 按照原图进行渲染,包括颜色。 |
Template | 将图片渲染为模板图片,忽略图片的颜色信息。 |
事件
除支持通用事件外,还支持以下事件:
名称 | 功能描述 |
onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number }) => void) | 图片成功加载时触发该回调,返回成功加载的图片尺寸。 - width:图片的宽,单位为像素。 - height:图片的高,单位为像素。 - componentWidth:组件的宽,单位为像素。 - componentHeight:组件的高,单位为像素。 - loadingStatus:图片加载成功的状态。 |
onError(callback: (event?: { componentWidth: number, componentHeight: number , message9+: string }) => void) | 图片加载出现异常时触发该回调。 - componentWidth:组件的宽,单位为像素。 - componentHeight:组件的高,单位为像素。 |
onFinish(event: () => void) | 当加载的源文件为带动效的svg图片时,当svg动效播放完成时会触发这个回调,如果动效为无限循环动效,则不会触发这个回调。 |
示例
图片加载
加载显示不同类型的图片,并设置图片的缩放类型。
网络图片
加载网络图片时,默认网络超时是5分钟,建议使用alt配置加载时的占位图。如果需要更灵活的网络配置,可以使用SDK中提供的HTTP工具包发送网络请求,接着将返回的数据解码为Image组件中的PixelMap,图片开发可参考图片处理。代码如下。
说明:网络图片加载的请求方式、超时、额外请求参数等配置可以参考HTTP工具包中关于request()请求方法的细节。
设置属性
事件调用
