ArkUI：UI组件

基础组件、容器组件、媒体组件、绘制组件、画布组件

type
status
date
slug
summary
tags
category
icon
password

概述

组件（Component）是界面搭建与显示的最小单位，HarmonyOS ArkUI声明式开发范式提供了丰富多样的UI组件，我们可以使用这些组件轻松的编写出更加丰富、漂亮的界面。组件根据功能可以分为以下五大类：
  1. 基础组件
  1. 容器组件
  1. 媒体组件
  1. 绘制组件
  1. 画布组件

一、基础组件

基础组件是视图层的基本组成单元，包括Text、Image、TextInput、Button、LoadingProgress等，例如下面这个常用的登录界面就是由这些基础组件组合而成。

1.1 Text

Text组件用于在界面上展示一段文本信息，可以包含Span和ImageSpan子组件。
文本样式
针对包含文本元素的组件，例如Text、Span、Button、TextInput等，可使用fontColor、fontSize、fontStyle、 fontWeight、fontFamily这些文本样式，分别设置文本的颜色、大小、样式、粗细以及字体

1.2 Image

Image组件用来渲染展示图片，它可以让界面变得更加丰富多彩。给Image组件设置图片地址、宽和高，图片就能加载出来，示例如下：
效果图如下：
设置缩放类型
为了使图片在页面中有更好的显示效果，有时候需要对图片进行缩放处理。您可以使用objectFit属性设置图片的缩放类型，objectFit的参数类型为ImageFit。

1.3 TextInput

TextInput组件用于输入单行文本，响应输入事件。TextInput的使用也非常广泛，例如应用登录账号密码、发送消息等。和Text组件一样，TextInput组件也支持文本样式设置，下面的示例代码实现了一个简单的输入框：

1.4 Button

Button组件主要用来响应点击操作，可以包含子组件。下面的示例代码实现了一个“登录按钮”：
设置按钮样式
type用于定义按钮样式，示例代码中ButtonType.Capsule表示胶囊形按钮；stateEffect用于设置按钮按下时是否开启切换效果，当状态置为false时，点击效果关闭，默认值为true。
我们可以设置多种样式的Button，除了Capsule可以以设置Normal和Circle：
  • Capsule： [ˈkæpsl]胶囊型按钮（圆角默认为高度的一半）。
  • Circle：圆形按钮。
  • Normal：普通按钮（默认不带圆角）。
包含子组件
Button组件可以包含子组件，让您可以开发出更丰富多样的Button，下面的示例代码中Button组件包含了一个回收站Image按钮组件：
 

1.5 LoadingProgress

LoadingProgress组件用于显示加载进展，比如应用的登录界面，当我们点击登录的时候，显示的“正在登录”的进度条状态。LoadingProgress的使用非常简单，只需要设置颜色和宽高就可以了。
 

二、容器组件

容器组件是一种比较特殊的组件，它可以包含其他的组件，而且按照一定的规律布局。容器组件除了放置基础组件外，也可以放置容器组件，通过多层布局的嵌套，可以布局出更丰富的页面。

2.1 线性组件

ArkTS提供了Column和Row容器来实现线性布局。
  • Column表示沿垂直方向布局的容器。
  • Row表示沿水平方向布局的容器。
2.1.1 主轴和交叉轴概念
  • 主轴：在Column容器中的子组件是按照从上到下的垂直方向布局的，其主轴的方向是垂直方向；在Row容器中的组件是按照从左到右的水平方向布局的，其主轴的方向是水平方向。
      • 图2-1 Column容器&Row容器主轴
      notion image
  • 交叉轴：与主轴垂直相交的轴线，如果主轴是垂直方向，则交叉轴就是水平方向；如果主轴是水平方向，则交叉轴是垂直方向。
      • 图2-2 Column容器&Row容器交叉轴
      notion image
属性介绍
了解布局容器的主轴和交叉轴，主要是为了让大家更好地理解子组件在主轴和交叉轴的排列方式。
接下来，我们将详细讲解Column和Row容器的两个属性justifyContent和alignItems。
属性名称
描述
justifyContent
设置子组件在主轴方向上的对齐格式。
alignItems
设置子组件在交叉轴方向上的对齐格式。
  1. 主轴方向的对齐（justifyContent）
子组件在主轴方向上的对齐使用justifyContent属性来设置，其参数类型是FlexAlign。FlexAlign定义

2.2 List组件

在我们常用的手机应用中，经常会见到一些列表和网格布局方式，如设置页面、通讯录、商品列表等。下图中两个页面中“首页”页面中包含两个网格布局，“商城”页面中包含一个列表布局。
上图中都包含一系列类似的项，连续多行或连续多行多列呈现同类数据，例如图片和文本。常见的布局方式有列表布局和网格布局。
notion image
为了帮助开发者构建包含上面两种布局的应用，ArkUI提供了List组件和Grid组件，开发者使用List和Grid组件能够很轻松的完成一些页面布局。
 
2.2.1 List组件简介
List是很常用的滚动类容器组件，一般和子组件ListItem一起使用，List列表中的每一个列表项对应一个ListItem组件。
notion image
2.2.2 使用ForEach渲染列表
列表往往由多个列表项组成，所以我们需要在List组件中使用多个ListItem组件来构建列表，这就会导致代码的冗余。使用循环渲染（ForEach）遍历数组的方式构建列表，可以减少重复代码，示例代码如下：
效果图如下：
notion image
2.2.3 设置列表项分割线
List组件子组件ListItem之间默认是没有分割线的，部分场景子组件ListItem间需要设置分割线，这时候您可以使用List组件的divider属性。divider属性包含四个参数：
  • strokeWidth: 分割线的线宽。
  • color: 分割线的颜色。
  • startMargin：分割线距离列表侧边起始端的距离。
  • endMargin: 分割线距离列表侧边结束端的距离。
      • notion image
2.2.4 List列表滚动事件监听
List组件提供了一系列事件方法用来监听列表的滚动，您可以根据需要，监听这些事件来做一些操作：
  • onScroll：列表滑动时触发，返回值scrollOffset为滑动偏移量，scrollState为当前滑动状态。
  • onScrollIndex：有子组件划入或划出List显示区域时触发。从API version 10开始，List显示区域中间位置子组件变化时也会触发。
  • onReachStart：列表到达起始位置时触发。
  • onReachEnd：列表到达末尾位置时触发。
  • onScrollStop：列表滑动停止时触发。
使用示例代码如下：
2.2.5 设置List排列方向
List组件里面的列表项默认是按垂直方向排列的，如果您想让列表沿水平方向排列，您可以将List组件的listDirection属性设置为Axis.Horizontal。
listDirection参数类型是Axis，定义了以下两种类型：
  • Vertical（默认值）：子组件ListItem在List容器组件中呈纵向排列。
      • notion image
  • Horizontal：子组件ListItem在List容器组件中呈横向排列。
      • notion image

2.3 Grid组件

Grid组件为网格容器，是一种网格布局，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。Grid组件一般和子组件GridItem一起使用，Grid网格中的每一个条目对应一个GridItem组件。
notion image
2.3.1 使用ForEach渲染网格布局
和List组件一样，Grid组件也可以使用ForEach来渲染多个GridItem项，我们通过下面的这段示例代码来介绍Grid组件的使用。
示例代码中使用了两层ForEach遍历长度为4的数组arr，创建了16个GridItem项。同时设置columnsTemplate的值为'1fr 1fr 1fr 1fr'，表示这个网格为4列，将Grid允许的宽分为4等分，每列占1份；rowsTemplate的值为'1fr 1fr 1fr 1fr'，表示这个网格为4行，将Grid允许的高分为4等分，每行占1份。这样就构成了一个4行4列的网格布局，然后使用columnsGap设置列间距为10vp，使用rowsTemplate设置行间距也为10vp。示例代码效果图如下：
notion image
上面构建的网格布局使用了固定的行数和列数，所以构建出的网格是不可滚动的。然而有时候因为内容较多，我们通过滚动的方式来显示更多的内容，就需要一个可以滚动的网格布局。我们只需要设置rowsTemplate和columnsTemplate中的一个即可。如果设置的是columnsTemplate，Grid的滚动方向为垂直方向；如果设置的是rowsTemplate，Grid的滚动方向为水平方向。
将示例代码中GridItem的高度设置为固定值，例如100；仅设置columnsTemplate属性，不设置rowsTemplate属性，就可以实现Grid列表的滚动：
此外，Grid像List一样也可以使用onScrollIndex来监听列表的滚动。
2.3.2 长列表性能优化
开发者在使用长列表时，如果直接采用循环渲染方式，会一次性加载所有的列表元素，从而导致页面启动时间过长，影响用户体验，推荐通过以下方式来进行长列表性能优化：
懒加载
缓存列表项
组件复用
布局优化
 

2.4 Tab组件

ArkUI开发框架提供了一种页签容器组件Tabs，开发者通过Tabs组件可以很容易的实现内容视图的切换。页签容器Tabs的形式多种多样，不同的页面设计页签不一样，可以把页签设置在底部、顶部或者侧边。
Tabs组件仅可包含子组件TabContent，每一个页签对应一个内容视图即TabContet组件。
💡
说明
  • TabContent组件不支持设置通用宽度属性，其宽度默认撑满Tabs父组件。
  • TabContent组件不支持设置通用高度属性，其高度由Tabs父组件高度与TabBar组件高度决定。
2.4.1 设置TabBar布局模式
因为Tabs的布局模式默认是Fixed的，所以Tabs的页签是不可滑动的。当页签比较多的时候，可能会导致页签显示不全，将布局模式设置为Scrollable的话，可以实现页签的滚动
Tabs的布局模式有Fixed（默认）和Scrollable两种：
  • BarMode.Fixed：所有TabBar平均分配barWidth宽度（纵向时平均分配barHeight高度），页签不可滚动，效果图如下：
  • BarMode.Scrollable：每一个TabBar均使用实际布局宽度，超过总长度（横向Tabs的barWidth，纵向Tabs的barHeight）后可滑动。
当页签比较多的时候，可以滑动页签，下面的示例代码将barMode设置为BarMode.Scrollable，实现了可滚动的页签：
2.4.2 设置TabBar位置和排列方向
Tabs组件页签默认显示在顶部，某些场景下您可能希望Tabs页签出现在底部或者侧边，您可以使用Tabs组件接口中的参数barPosition设置页签位置。此外页签显示位置还与vertical属性相关联，vertical属性用于设置页签的排列方向，当vertical的属性值为false（默认值）时页签横向排列，为true时页签纵向排列。
barPosition的值可以设置为BarPosition.Start（默认值）和BarPosition.End：
  • BarPosition.Start
vertical属性方法设置为false（默认值）时，页签位于容器顶部。
vertical属性方法设置为true时，页签位于容器左侧。
  • BarPosition.End
vertical属性方法设置为false时，页签位于容器底部。
vertical属性方法设置为true时，页签位于容器右侧。
2.4.3 自定义TabBar样式
TabBar的默认显示效果如下所示
notion image
往往开发过程中，UX给我们的设计效果可能并不是这样的，比如下面的这种底部页签效果：
notion image
TabContent的tabBar属性除了支持string类型，还支持使用@Builder装饰器修饰的函数。您可以使用@Builder装饰器，构造一个生成自定义TabBar样式的函数，实现上面的底部页签效果，示例代码如下：
示例代码中将barPosition的值设置为BarPosition.End，使页签显示在底部。使用@Builder修饰TabBuilder函数，生成由Image和Text组成的页签。同时也给Tabs组件设置了TabsController控制器，当点击某个页签时，调用changeIndex方法进行页签内容切换。
最后还需要给Tabs添加onChange事件，Tab页签切换后触发该事件，这样当我们左右滑动内容视图的时候，页签样式也会跟着改变。
 
参考链接
  • Tabs组件的更多属性和参数的使用，可以参考API：Tabs。
  • @Builder装饰器的使用，可以参考：@Builder。
  • Video组件的使用：可以参考：Video