方舟开发框架(简称ArkUI)为HarmonyOS应用的UI开发提供了完整的基础设施,包括简洁的UI语法、丰富的UI功能(组件、布局、动画以及交互事件),以及实时界面预览工具等,可以支持开发者进行可视化界面开发。
一:Image
Image(src: string | PixelMap | Resource)
图片的数据源,支持本地图片和网络图片
- string格式可用于加载网络图片和本地图片,常用于加载网络图片。当使用相对路径引用本地图片时,例如Image("common/test.jpg"),不支持跨包/跨模块调用该Image组件,建议使用Resource格式来管理需全局使用的图片资源。
- 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp];base64,[base64 data], 其中[base64 data]为Base64字符串数据。
- 支持file://路径前缀的字符串。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。
- PixelMap格式为像素图,常用于图片编辑的场景。
- Resource格式可以跨包/跨模块访问资源文件,是访问本地图片的推荐方式。
属性
名称 | 参数类型 | 描述 |
---|---|---|
alt | string | Resource | 加载时显示的占位图,支持本地图片(png、jpg、bmp、svg和gif类型),不支持网络图片。 默认值:null 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
objectFit | ImageFit | 设置图片的填充效果。 默认值:ImageFit.Cover 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
objectRepeat | ImageRepeat | 设置图片的重复样式。从中心点向两边重复,剩余空间不足放下一张图片时会截断。 默认值:ImageRepeat.NoRepeat 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: svg类型图源不支持该属性。 |
interpolation | ImageInterpolation | 设置图片的插值效果,即减轻低清晰度图片在放大显示时出现的锯齿问题。 默认值:ImageInterpolation.None 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: svg类型图源不支持该属性。 PixelMap资源不支持该属性。 |
renderMode | ImageRenderMode | 设置图片的渲染模式为原色或黑白。 默认值:ImageRenderMode.Original 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: svg类型图源不支持该属性。 |
sourceSize | { width: number, height: number } | 设置图片解码尺寸,降低图片的分辨率,常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。 单位:px 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 仅在目标尺寸小于图源尺寸时生效。 svg类型图源不支持该属性。 PixelMap资源不支持该属性。 |
matchTextDirection | boolean | 设置图片是否跟随系统语言方向,在RTL语言环境下显示镜像翻转显示效果。 默认值:false 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
fitOriginalSize | boolean | 图片组件尺寸未设置时,显示尺寸是否跟随图源尺寸。 组件不设置宽高或仅设置宽/高时,该属性不生效。 默认值:false 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
fillColor | ResourceColor | 设置填充颜色,设置后填充颜色会覆盖在图片上。 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 仅对svg图源生效,设置后会替换svg图片的填充颜色。 |
autoResize | boolean | 设置图片解码过程中是否对图源自动缩放。设置为true时,组件会根据显示区域的尺寸决定用于绘制的图源尺寸,有利于减少内存占用。如原图大小为1920x1080,而显示区域大小为200x200,则图片会自动解码到200x200的尺寸,大幅度节省图片占用的内存。 默认值:true 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
syncLoad8+ | boolean | 设置是否同步加载图片,默认是异步加载。同步加载时阻塞UI线程,不会显示占位图。 默认值:false 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 建议加载尺寸较小的本地图片时将syncLoad设为true,因为耗时较短,在主线程上执行即可。 |
copyOption9+ | CopyOptions | 设置图片是否可复制。 当copyOption设置为非CopyOptions.None时,支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。 默认值:CopyOptions.None 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: svg图片不支持复制。 |
colorFilter9+ | ColorFilter | 给图像设置颜色滤镜效果,入参为一个的4x5的RGBA转换矩阵。 矩阵第一行表示R(红色)的向量值,第二行表示G(绿色)的向量值,第三行表示B(蓝色)的向量值,第四行表示A(透明度)的向量值,4行分别代表不同的RGBA的向量值。 RGBA值分别是0和1之间的浮点数字,当矩阵对角线值为1时,保持图片原有色彩。 计算规则: 如果输入的滤镜矩阵为:
像素点为[R, G, B, A] 则过滤后的颜色为 [R’, G’, B’, A’]
从API version 9开始,该接口支持在ArkTS卡片中使用。 |
draggable9+ | boolean | 设置组件默认拖拽效果,设置为true时,组件可拖拽。 不能和拖拽事件事件同时使用。 默认值:false |
ImageInterpolation
从API version 9开始,该接口支持在ArkTS卡片中使用。
名称 | 描述 |
---|---|
None | 不使用图片插值。 |
High | 高图片插值,插值质量最高,可能会影响图片渲染的速度。 |
Medium | 中图片插值。 |
Low | 低图片插值。 |
ImageRenderMode
从API version 9开始,该接口支持在ArkTS卡片中使用。
名称 | 描述 |
---|---|
Original | 原色渲染模式。 |
Template | 黑白渲染模式。 |
事件
onComplete
onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number }) => void)
图片数据加载成功和解码成功时均触发该回调,返回成功加载的图片尺寸。
从API version 9开始,该接口支持在ArkTS卡片中使用。
参数名 | 类型 | 说明 |
---|---|---|
width | number | 图片的宽。 单位:像素 |
height | number | 图片的高。 单位:像素 |
componentWidth | number | 组件的宽。 单位:像素 |
componentHeight | number | 组件的高。 单位:像素 |
loadingStatus | number | 图片加载成功的状态值。 说明: 返回的状态值为0时,表示图片数据加载成功。返回的状态值为1时,表示图片解码成功。 |
onError
onError(callback: (event?: { componentWidth: number, componentHeight: number , message: string }) => void)
图片加载异常时触发该回调。
从API version 9开始,该接口支持在ArkTS卡片中使用。
参数:
参数名 | 类型 | 说明 |
---|---|---|
componentWidth | number | 组件的宽。 单位:像素 |
componentHeight | number | 组件的高。 单位:像素 |
message9+ | string | 报错信息。 |
onFinish
onFinish(event: () => void)
当加载的源文件为带动效的svg格式图片时,svg动效播放完成时会触发这个回调。如果动效为无限循环动效,则不会触发这个回调。
仅支持svg格式的图片。
从API version 9开始,该接口支持在ArkTS卡片中使用。
例子:
@Entry
@Component
struct Index {@State message: string = 'Hello World'build() {Row() {Column() {Text(this.message).fontSize(50).fontWeight(FontWeight.Bold)Image($r('app.media.app_icon')).width(100).height(100).interpolation(ImageInterpolation.Medium)Image("https://static001.geekbang.org/infoq/d5/d5a0f852258b301702246692310cd920.png").alt($r('app.media.icon')).width(100).height(100).interpolation(ImageInterpolation.Medium)}.width('100%')}.height('100%')}
}
注意 加载网络图片需要权限:权限的配置如下:
二:Text文本组件
declare const Text: TextInterface;
interface TextInterface {/*** Called when writing text.* @since 7*//*** Called when writing text.* @form* @since 9*/(content?: string | Resource): TextAttribute;
}
使用方式
1.硬编码字符串
2.引用资源文件字符串
@Entry
@Component
struct TextPage {@State message: string = 'Text'build() {Row() {Column() {Text($r('app.string.app_name')).fontColor(Color.Blue).fontSize(20).fontWeight(FontWeight.Bold)Text($r('app.string.testStr')).fontColor(Color.Red).fontSize(20).fontWeight(FontWeight.Lighter)}.width('100%')}.height('100%')}
}
常见属性
名称 | 参数类型 | 描述 |
---|---|---|
textAlign | TextAlign | 设置文本段落在水平方向的对齐方式 默认值:TextAlign.Start 说明: 文本段落宽度占满Text组件宽度。 可通过align属性控制文本段落在垂直方向上的位置,此组件中不可通过align属性控制文本段落在水平方向上的位置,即align属性中Alignment.TopStart、Alignment.Top、Alignment.TopEnd效果相同,控制内容在顶部。Alignment.Start、Alignment.Center、Alignment.End效果相同,控制内容垂直居中。Alignment.BottomStart、Alignment.Bottom、Alignment.BottomEnd效果相同,控制内容在底部。结合TextAlign属性可控制内容在水平方向的位置。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
textOverflow | {overflow: TextOverflow} | 设置文本超长时的显示方式。 默认值:{overflow: TextOverflow.Clip} 说明: 文本截断是按字截断。例如,英文以单词为最小单位进行截断,若需要以字母为单位进行截断,可在字母间添加零宽空格:\u200B。 需配合maxLines使用,单独设置不生效。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
maxLines | number | 设置文本的最大行数。 说明: 默认情况下,文本是自动折行的,如果指定此参数,则文本最多不会超过指定的行。如果有多余的文本,可以通过 textOverflow来指定截断方式。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
lineHeight | string | number | Resource | 设置文本的文本行高,设置值不大于0时,不限制文本行高,自适应字体大小,Length为number类型时单位为fp。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
decoration | { type: TextDecorationType, color?: ResourceColor } | 设置文本装饰线样式及其颜色。 默认值:{ type: TextDecorationType.None, color:Color.Black } 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
baselineOffset | number | string | 设置文本基线的偏移量,默认值0。 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 设置该值为百分比时,按默认值显示。 |
letterSpacing | number | string | 设置文本字符间距。 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 设置该值为百分比时,按默认值显示。 |
minFontSize | number | string | Resource | 设置文本最小显示字号。 需配合maxFontSize以及maxline或布局大小限制使用,单独设置不生效。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
maxFontSize | number | string | Resource | 设置文本最大显示字号。 需配合minFontSize以及maxline或布局大小限制使用,单独设置不生效。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
textCase | TextCase | 设置文本大小写。 默认值:TextCase.Normal 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
copyOption9+ | CopyOptions | 组件支持设置文本是否可复制粘贴。 默认值:CopyOptions.None 该接口支持在ArkTS卡片中使用。 说明: 设置copyOptions为CopyOptions.InApp或者CopyOptions.LocalDevice,长按文本,会弹出文本选择菜单,可选中文本并进行复制、全选操作 |