HarmonyOS（鸿蒙）ArkUI组件

方舟开发框架（简称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_1, r_2, r_3, r_4, r_5, g_1, g_2, g_3, g_4, g_5, b_1, b_2, b_3, b_4, b_5, a_1, a_2, a_3, a_4, a_5 ] 像素点为[R, G, B, A] 则过滤后的颜色为 [R’, G’, B’, A’] R’ = r_1R + r_2G + r_3B + r_4A + r_5 G’ = g_1R + g_2G + g_3B + g_4A + g_5 B’ = b_1R + b_2G + b_3B + b_4A + b_5 A’ = a_1R + a_2G + a_3B + a_4A + a_5 从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	报错信息。

参数名

类型

说明

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，长按文本，会弹出文本选择菜单，可选中文本并进行复制、全选操作