ArkUI学习之常用系统组件（一）

组件是构建页面的核心，每个组件通过对数据和方法的简单封装，实现独立的可视、可交互功能单元。组件之间相互独立，随取随用，也可以在需求相同的地方重复使用。

一、文本组件

1.Text定义介绍

Text 是显示文本的基础组件之一，它可以包含子组件 Span ，当包含 Span 时不生效，只显示 Span 的内容。接口如下：、

Text(content?: string | Resource)

说明：

🌾 string格式，直接填写文本内容

Text（"图片宽度"）

🌾 Resource格式，读取本地资源文件

Text($r('app.string.app_name'))

⚠️ 需要注意的是由于国际化的问题，读取本地资源文件的时候，需要分别base/element、en_US和zh_CN下的setting.json进行配置，先会根据语言在对应的zh_CN或者en_CN下读取，最后才会在base目录下加载

2.Text属性介绍

text除支持通用属性外，还支持以下属性参考网址 developer.harmonyos.com/cn/docs/doc…

🌾 textAlign

设置文本的对其方式，对齐参考系是 Text 组件本身，只有 Text 组件本身的宽度大于文本内容长度， textAlign 属性才起作用

TextAlign 定义了以下 3 种类型：

• Start（默认值）：根据文字书写相同的方向对齐，比如中文从左往右排版，那么文本则靠左对齐。
• Center：文本居中对齐。
• End：根据文字书写相反的方向对齐，比如中文从左往右排版，那么文本则靠右对齐。

案例如下：

🌾 maxLines、textOverflow

设置文本显示的最大行数和截取方式，默认折行显示不截取，如果设置了此参数，则文本最多显示到指定的行，如果有多余的文本，可以通过 textOverflow 来指定截取方式，有两种方式：

• Clip:超出maxLines展示行截断内容展示
• Ellipsis:超出maxLines展示行省略号

案例如下：

🌾 fontSize、fontColor、fontStyle、 fontWeight

分别表示设置文字的大小，颜色，样式以及粗细，我们可以组合起来设置文本的富样式，先看一个样例：

3. 案例练习

在屏幕输入图片宽度，让图片随着输入的宽度进行改变

⚠️注意：图像插值是指在图像处理中使用已知像素值来估计未知像素值的过程。高质量的插值通常意味着使用更复杂的算法来估计像素值，以获得更平滑、更真实的图像结果。这种设置通常会增加计算成本，但可以提高图像的视觉质量。

上面的图片由于放大，会出现锯齿状，采用图像插值就可以解决这个问题

二、按钮组件

Button 组件也是基础组件之一，和其它基础组件不同的是 Button 组件允许添加一个子组件来实现不同的展示样式。

1. Button定义

接口如下：

Button(label?: ResourceStr, options?: { type?: ButtonType, stateEffect?: boolean })

说明：

🌾 文字型按钮

Button('登录'）

🌾 自定义按钮，在Button内嵌套其它组件

2. 添加属性和事件

type：设置 Button 按钮的显示样式， ButtonType 定义了以下3种样式：

🌾 Capsule（默认值）

胶囊类型，圆角值默认为 Button 高度的一半，并且不允许修改，此时通过设置 borderRadius() 的方式设置圆角则无效。案例如下：

🌾 Normal：

矩形按钮，无圆角，可以通过 borderRadius() 设置圆角大小，不支持通过 border() 的方式设置圆角

🌾 Circle：

圆形按钮，当按钮类型为Circle时，borderRadius即为按钮半径，若未设置borderRadius按钮半径则为宽、高中较小值的一半

3. Button自定义样式

🌾 包含 Text 组件

上面给 Button 添加了一个 Text 子组件，通过设置 Text 的文本样式达到修改 Button 文字的效果。

🌾 包含Image组件

上面使用了 Image 组件，后续会详细讲解

🌾 包含复杂组件

上面使用 Row 作为子组件， Row 组件属于线性容器组件，可以添加多个子组件，后续章节详细会讲解。

三、图片组件

Image 用来加载并显示图片的基础组件，它支持从内存、本地和网络加载图片，支持png、jpg、bmp、svg和gif类型的图片格式。当从网络加载图片的时候，需要申请网络访问权限。

1. Image定义

接口如下：

Image(src: string | PixelMap | Resource)

说明如下：

🌾 string格式

通常用来加载网络图片，需要申请网络访问权限：ohos.permission.INTERNET

🌾 Pixel Map格式

可以加载像素图，常用在图片编辑中

Image(pixel Map Object)

🌾Resource格式

加载本地图片，推荐使用

Image($r('app.media.mate60'))
Image($rawfile('mate60.png'))

2. Image属性

🌾 alt

设置占位图，图片显示之前先显示占位图，比如在加载网络图片或者图片加载失败时的场景。

🌾 objectFit

设置图片的放缩类型，当 Image 组件大小和图片大小不同时指定图片的放缩类型， ImageFit 提供了以下5种匹配模式：

• Cover（默认值）：保持图片宽高比进行放缩显示，使得图片完全显示在显示边界外。
• Contain：保持图片宽高比进行放缩显示，使得图片完全显示在显示边界内。
• Fill：不保持图片宽高比显示，是图片完全充满显示边界。
• None：保持图片原有尺寸显示，通常配合 objectRepeat 属性一起使用。
• ScaleDown：保持图片宽高比显示，使图片缩小或者保持不变的显示出来。

🌾 renderMode

设置图片的渲染模式， ImageRenderMode 定义了以下2种渲染模式：

• Original（默认值）：按照原图进行渲染。
• Template：将图像渲染为模板图像，忽略图片的颜色信息。

🌾 sourceSize

设置图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。单位：px

3. Image加载方式

🌾 从本地加载

• 拷贝 Snip.png 图片到工程的 resources/main/base/media 目录下
• 加载图片，直接使用系统提供的资源访问符 $() 或者本地文件加载
• 加载图片，从本地的rawfile中加载图片通过$rawfile("scenery.png")方式加载

🌰 案例如下：

ImageInterpolation：图片插值：从API version 9开始，该接口支持在ArkTS卡片中使用。

名称	描述
None	不使用图片插值。
High	高图片插值，插值质量最高，可能会影响图片渲染的速度。
Medium	中图片插值。
Low	低图片插值。

🌾 从网络加载

• 限制与约束说明：

当加载网络图片时需要申请 ohos.permission.INTERNET 权限。具体申请方式请参考权限申请声明。

应用需要在工程配置文件中，对需要的权限逐个声明，未在配置文件中声明的权限，应用将无法获得授权。HarmonyOS提供了两种应用模型，分别为FA模型和Stage模型，更多信息可以参考应用模型解读。不同的应用模型的应用包结构不同，所使用的配置文件不同。

配置文件标签说明如下表所示。

标签	是否必填	说明
name	是	权限名称。
reason	否	描述申请权限的原因。> 说明：当申请的权限为user_grant权限时，此字段必填。
usedScene	否	描述权限使用的场景和时机。> 说明：当申请的权限为user_grant权限时，此字段必填。
abilities	否	标识需要使用到该权限的Ability，标签为数组形式。适用模型：Stage模型
ability	否	标识需要使用到该权限的Ability，标签为数组形式。适用模型：FA模型
when	否	标识权限使用的时机，值为inuse/always。- inuse：表示为仅允许前台使用。- always：表示前后台都可使用。

Stage模型

使用Stage模型的应用，需要在module.json5配置文件中声明权限。添加这一段即可

"requestPermissions": [
      {"name":  "ohos.permission.INTERNET"}
 ],

🌰 如下图所示

🌾 从内存加载

Image(pixel Map object)

四、输入框组件

ArkUI开发框架提供了 2 种类型的输入框：

• TextInput：只支持单行输入
• TextArea：支持多行输入

下面我们分别做下介绍

1.TextInput定义

接口如下：

TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})

value：输入框的提示样式设置， TextInputOptions 参数类型说明如下：

• text：设置输入框的初始显示文本，不设置时显示 placeholder 的内容。
• placeholder：占位提示文本，当不设置 text 时，则会显示该文本。
• controller：光标控制器，设置光标的下标位置。

🌰 案例如下：

2.TextInput属性介绍

TextInput 组件用于文本输入，它只能单行文本输入，若文本超出自身长度则使用 ... 在末尾替代。 TextInput 组件除了公共属性外，它还提供了很多常用的属性：

• type：表示输入框的类型，比如设置为 Number ，则表示输入框只能输入数字, password表示输入的密码，会使用遮挡符遮挡。

• enterKeyType：表示设置输入法回车键类型，主要用来控制回车键的显示样式。例如设置 enterKeyType 为 Search ， type 为 Number 时，结果如下图所示：

  

• maxLength：设置输入框允许输入多少字符。

• caretColor：设置光标的颜色。

🌰 案例如下：

3.TextInput事件介绍

TextInput 除了具有公共事件外，它还提供了自己独有的事件回调。

• onChange：当输入框的内容变化时，触发该回调并把输入框的值回调出来
• onSubmit：回车键或者软键盘回车键触发该回调，参数为当前软键盘回车键类型。
• onEditChanged：输入状态变化时，触发回调。

🌰 TextInput 的一个案例如下：

4.TextArea简单介绍

TextArea 和 TextInput 都属于输入框，只是 TextArea 允许多行输入，它们的属性也都大致是一样的，只是目前 TextArea 还不支持 maxLength 属性，这里就不再介绍 TextArea 的属性了

🌰案例说明：TextInput 和 TextArea 的使用，如下所示：

五、进度条组件

进度条也是UI开发最常用的组件之一，ArkUI开发框架提供了两种类型的进度条： Progress 和LoadingProgress ，前者可以精准指定进度，后者表示正在加载的状态，我们接下来对它们分别做下介绍。

1.Progress

🌾 Progress定义介绍

Progress 组件可以精确的设置当前进度条的进度，它主要用在有加载进度的场景。

Progress(options: {value: number, total?: number, type?: ProgressType})

创建进度组件，用于显示内容加载或操作处理进度。说明如下：

options：进度条参数配置项，ProgressOptions 参数说明如下：

• value：表示当前进度，取值范围[0, 100]，当超过 100 时无效。
• total：表示进度条总进度，默认值为100。
• type、style：设置进度条的样式， style 从 API 8 起使用 type 代替， ProgressType 定义了以下 2 种样式：
  

  Linear：进度条样式为条形进度条

  Eclipse：进度条样式为圆形进度条

  Ring：环形进度条

  ScaleRing：环形刻度进度条

  Capsule：胶囊样式进度条

 

🌰案例如下：

🌾 Progress属性介绍

value：设置当前进度值。

style：设置进度条的样式，样式说明如下：

• strokeWidth：设置进度条宽度。
• scaleCount：设置环形进度条总刻度数。
• scaleWidth：设置环形进度条刻度粗细。

color：设置进度条的颜色，默认为蓝色。

🌰样式设置案例如下：

2.LoadingProgress

LoadingProgress 和 Progress 的区别是不能精确指定进度条的进度，它是一个一直加载的动画，主要是向用户提示任务正在运行中。

🌾 LoadingProgress定义

LoadingProgress()

创建加载进展组件。LoadingProgress 没有定义任何参数。案例如下：

LoadingProgress().width(180).height(180)

预览后结果如下：

🌾 LoadingProgress属性介绍

只有一个属性：

名称	参数类型	描述
color	ResourceColor	设置加载进度条前景色。从API version 9开始，该接口支持在ArkTS卡片中使用。

🌰案例如下：

六、选择器组件

ArkUI开发框架提供了一系列比较常用的选择器，比如文本选择器 TextPicker 、时间选择器 TimePicker 以及日期选择器 DatePicker

1.TimePicker

TimePicker 是选择时间的滑动选择器组件，默认以 00:00 至 23:59 的时间区创建滑动选择器。

🌾 TimePicker定义

接口：默认以24小时的时间区间创建滑动选择器

TimePicker(options?: {selected?: Date})

options：创建时间选择器的可选配置参数， TimePickerOptions 说明如下：

• selected：设置选择器的默认选中时间。

参数：

参数名	参数类型	必填	参数描述
selected	Date	否	设置选中项的时间。默认值：当前系统时间

🌰案例如下所示：

🌾 TimePicker属性介绍

除支持通用属性外，还支持以下属性：

名称	参数类型	描述
useMilitaryTime	boolean	展示时间是否为24小时制，不支持动态修改。默认值：false

除支持通用事件外，还支持以下事件：

名称	功能描述
onChange(callback: (value: TimePickerResult ) => void)	选择时间时触发该事件。

🌰案例如下：

2.DatePicker

DatePicker 是选择日期的滑动选择器组件，默认以 1970-1-1 至 2100-12-31 的日期区间创建滑动选择器。

🌾 DatePicker定义

接口：

DatePicker(options?: {start?: Date, end?: Date, selected?: Date})

上面的接口可以根据指定范围的Date创建可以选择日期的滑动选择器，参数:

参数名	参数类型	必填	参数描述
start	Date	否	指定选择器的起始日期。默认值：Date('1970-1-1')
end	Date	否	指定选择器的结束日期。默认值：Date('2100-12-31')
selected	Date	否	设置选中项的日期。默认值：当前系统日期

🌰案例如下：

🌾 DatePicker属性介绍

除支持通用属性外，还支持以下属性：

名称	参数类型	描述
lunar	boolean	日期是否显示农历。- true：展示农历。- false：不展示农历。默认值：false

🌰案例如下所示：

🌾 DatePicker事件介绍

除支持通用事件外，还支持以下事件：

名称	功能描述
onChange(callback: (value: DatePickerResult) => void)	选择日期时触发该事件。

DatePickerResult对象说明：

名称	参数类型	描述
year	number	选中日期的年。
month	number	选中日期的月(0~11)，0表示1月，11表示12月。
day	number	选中日期的日

🌰案例如下：点击按钮可以切换农历和公历