第5 章
UI 组 件 
本章主要讲解常见UI组件的使用方法及其特性。第4章中介绍了HarmonyOS的常
用UI布局,而一个界面除了UI布局,组件也是非常重要的组成部分。组件是构建页面的
核心,每个组件通过对数据和方法的简单封装,实现独立的可视、可交互功能单元。组件之
间相互独立,随取随用,也可以在需求相同的地方重复使用。HarmonyOS的UI常见组件
可以分为三大类:显示组件、交互组件和高级组件。组件的具体使用场景,需要根据业务需
求来选择使用。
通过阅读本章,读者可以掌握: 
如何创建使用各类组件。
了解各类组件所支持的属性。
如何设置组件样式。
5.1 展示组件
5.1.1 文本组件 
文本组件(Text)是最常用的组件之一。Text是用来显示字符串的组件,在界面上显示
为一块文本区域。Text作为一个基本组件有很多扩展,常见的有按钮组件Button,文本编
辑组件TextField。Text是Component类的子类之一,所以它能够使用Component类的所
有公开的属性和方法,Text类自身也提供了一些特殊的属性、方法、内部类和接口。
1.创建Text 
(1)布局文件中创建Text。
在layout文件下创建text.xml,在XML文件中声明布局和组件。例如,创建一个高为
150vp,长为300vp的text组件,组件具体属性代码如下: 
<Text 
ohos:id="$+id:text" //当前组件唯一标识,在单个布局文件中不允许id 标识重复 
ohos:width="300vp" 
ohos:height="150vp" 
ohos:text="Text 组件" //显示文本 
ohos:background_element="$graphic:background_text" //设置Text 背景 
ohos:text_size="66fp" 
ohos:text_color="white" 
ohos:italic="true"

第5 章　UI 组件 89 
ohos:text_weight="700" 
ohos:text_font="serif" 
/> 
组件常用的背景可以采用XML格式放置在graphic目录下。在graphic目录下创建
background_text.xml,在XML文件中定义文本的背景,代码如下: 
<?xml version="1.0" encoding="utf-8"?> 
<shape xmlns:ohos="http://schemas.huawei.com/res/ohos" 
ohos:shape="rectangle"> 
<corners ohos:radius="20"/> 
<solid ohos:color="#FF1992C3"/> 
</shape> 
最后,在MainAbilitySlice.java中,通过setUIContent()加载该XML布局。代码如下: 
public class MainAbilitySlice extends AbilitySlice { 
@Override 
public void onStart (Intent intent){ 
Super.onStart(intent); 
Super.setUIContent(ResourceTable.Layout_text); 
} 
}
运行效果如图5-1所示。
图5-1 XML创建Text 
(2)Java代码中创建Text。
打开MainAbilitySlice.java文件,找到onStart()方法,创建Text组件,代码如下:

90 HarmonyOS 应用程序开发与实战（Java 版） 
Text text = (Text) findComponentById 
(ResourceTable.Id_text); //获取布局中的组件
text.setText("text 组件"); //设置文本
text.setTextSize(66); //设置文字大小
text.setTextColor(Color.WHITE); //设置文字颜色
text.setWidth(300); 
text.setHeight(150); 
2.设置Text组件样式
(1)设置字体大小和颜色。
通常设置文本大小text_size和文本颜色text_color两个属性。text_size为float类型, 
可以是浮点数值,其默认单位为px;还可以是带px/vp/fp单位的浮点数值;还可以引用
float资源。text_color为color类型,可以直接设置色值,也可以引用color资源。代码
如下: 
ohos:text_size="66fp" 
ohos:text_color="#FF0000" 
(2)设置字体风格和字重。
字体为text_font属性,可以设置的值包括sans-serif、sans-serif-medium、HwChinesemedium
、sans-serif-condensed、sans-serif-condensed-medium、monospace。italic表示文本
是否斜体字体,为boolean类型,可以直接设置true/false,也可以引用boolean资源。text_ 
weight则表示字重。代码如下: 
ohos:italic="true" 
ohos:text_weight="700" 
ohos:text_font="sans-serif" 
(3)设置文本对齐方式,换行和最大显示行数。
text_alignment表示文本对齐方式,包含left文本靠左对齐,top文本靠顶部对齐,right 
文本靠右对齐,bottom 文本靠底部对齐,horizontal_center文本水平居中对齐,vertical_ 
center文本垂直居中对齐,center文本居中对齐,start文本靠起始端对齐以及end文本靠结
尾端对齐。multiple_lines为多行模式设置,boolean类型。max_text_lines表示文本最大
行数,为integer类型。代码如下: 
ohos:text="Text 是一个文本组件" 
ohos:text_alignment="horizontal_center " 
ohos:multiple_lines="true" 
ohos:max_text_lines="2" 
运行效果如图5-2所示。
(4)自动调节字体大小。
Text对象可以实现根据文本长度来自动调整文本的字体大小和换行。通过设置auto_ 
font_size来控制文本是否自动调整文本字体大小,该属性为boolean类型。效果如图5-3

第5 章　UI 组件 91 
所示,代码如下:
图5-2 文本效果 
图5-3 自动调节字体大小 
ohos:multiple_lines="true" //自动换行
ohos:max_text_lines="1" //最大显示行数
ohos:auto_font_size="true" //自动调节字体大小
(5)跑马灯效果。
在文本过长的情况下,可以通过设置跑马灯效果来实现文本滚动显示。但在这里要注
意的是,首先要关闭文本换行并且设置最大显示行数为1,一般默认即可。代码如下: 
text.setTruncationMode(Text.TruncationMode.AUTO_SCROLLING);//自动滚动状态
text.setAutoScrollingCount(Text.AUTO_SCROLLING_FOREVER); 
text.startAutoScrolling(); //启动跑马灯效果
5.1.2 图像组件
图像组件(Image)是用来在屏幕上显示图片的组件,各种图片的展示都需要该组件的
使用。例如,在做网站首页时需要显示的背景图,动态加载显示用户头像以及朋友圈发布图
片等场景,都可以使用Image图像组件进行显示。
1.创建Image 
首先将所需图片资源image.jpg添加至media文件夹下,这里以“image.jpg”为例。在
image.xml文件中声明组件,然后在Java文件中加载该XML布局。运行效果如图5-4所
示,代码如下:

92 HarmonyOS 应用程序开发与实战（Java 版） 
<Image 
ohos:id="$+id:imageComponent" 
ohos:height="match_parent" 
ohos:width="match_parent" 
ohos:image_src="$media:image"/> 
或者用Java代码创建Image组件,在MainAbilitySlice.java文件中找到onStart()方法,创
建Image组件,代码如下: 
Image image = new Image(getContext()); //创建Image 
image.setPixelMap(ResourceTable.Media_image); //设置要显示的图片
DirectionalLayout layout = new DirectionalLayout(getContext());//创建布局
layout.addComponent(image); //Image 组件添加到布局中
super.setUIContent(layout); 
2.设置Image样式
(1)设置透明度。
通过设置alpha透明度属性来修改图片的透明度,效果如图5-5所示。代码如下: 
ohos:alpha="0.5" //设置透明度为0.5 
(2)设置缩放系数。
通过设置X 轴和Y 轴缩放系数来控制图片的缩放,效果如图5-6所示。代码如下: 
图5-4 创建Image组件 
图5-5 透明度效果 
图5-6 坐标轴缩放 
ohos:scale_x="0.5" 
ohos:scale_y="0.5"

第5 章　UI 组件 93 
图5-7 缩放效果
(3)设置缩放方式。
当图片尺寸与Image尺寸不同时,可以根据不同的缩放方
式对图片进行缩放。缩放方式scale_mode有下面几种: 
● center表示不缩放,按Image大小显示原图中间部分。
● zoom_center表示原图按照比例缩放到与Image最窄
边一致,并居中显示。
● zoom_start表示原图按照比例缩放到与Image最窄边
一致,并靠起始端显示。
● zoom_end表示原图按照比例缩放到与Image最窄边一
致,并靠结束端显示。
● stretch表示将原图缩放到与Image大小一致。
● inside表示将原图按比例缩放到与Image相同或更小
的尺寸,并居中显示。
● clip_center表示将原图按比例缩放到与Image相同或
更大的尺寸,并居中显示。
例如,设置Image的宽为300vp,高为150vp,分别设置缩
放方式为zoom_start、zoom_center和zoom_end,为了突出效
果,将image的背景色设为灰色,运行效果如图5-7所示。
代码如下: 
<Image 
ohos:id="$+id:image" 
ohos:width="300vp" 
ohos:height="150vp" 
ohos:bottom_margin="20vp" 
ohos:image_src="$media:image" 
ohos:background_element="$graphic:background_image" 
ohos:scale_mode="zoom_start"/> 
<Image 
ohos:id="$+id:image1" 
ohos:width="300vp" 
ohos:height="150vp" 
ohos:bottom_margin="20vp" 
ohos:image_src="$media:image" 
ohos:background_element="$graphic:background_image" 
ohos:scale_mode="zoom_center"/> 
<Image 
ohos:id="$+id:image2" 
ohos:width="300vp" 
ohos:height="150vp" 
ohos:image_src="$media:image" 
ohos:background_element="$graphic:background_image" 
ohos:scale_mode="zoom_end"/>

94 HarmonyOS 应用程序开发与实战（Java 版） 
(4)设置裁剪对齐方式。
当Image组件设定的尺寸小于图片实际尺寸时,可以对图片进行裁剪。通过设置clip_ 
alignment样式来进行图片剪裁:left表示左对齐裁剪;right表示右对齐裁剪;top 表示顶
部对齐裁剪;bottom 表示底部对齐裁剪;center表示居中对齐裁剪。
例如,创建一个宽和高都为200vp的Image组件,设置左对齐clip_alignment=“left”, 
效果如图5-8所示。
图5-8 裁剪效果
代码如下: 
<Image 
ohos:id="$+id:image" 
ohos:width="200vp" 
ohos:height="200vp" 
ohos:layout_alignment="center" 
ohos:image_src="$media:image" 
ohos:clip_alignment="left" 
/> 
5.1.3 进度条组件
ProgressBar用于显示内容或操作的进度。可以通过进度条查看一些功能操作的进度。
使用场景:项目开发中通过设置数值改变进度条的样式,或者通过手动拖动改变进度条和
进度值。
1.创建ProgressBar 
在layout目录下的XML 文件中创建一个ProgressBar,同时在Java文件中加载该

第5 章　UI 组件 95 
XML布局。运行效果如图5-9所示。代码如下: 
<ProgressBar 
ohos:id="$+id:progressbar" 
ohos:orientation="horizontal" 
ohos:progress_width="40vp" 
ohos:height="120vp" 
ohos:width="match_parent" 
ohos:max="100" 
ohos:min="0" 
ohos:progress="60" 
ohos:progress_hint_text="60%" 
ohos:progress_hint_text_color="black" 
/> 
图5-9 progressBar效果
2.设置ProgressBar样式
(1)设置ProgressBar的方向。
属性orientation表示排列方向,包含horizontal水平显示和vertical垂直显示。设置
ProgressBar方向为水平,代码如下: 
ohos:orientation="horizontal" 
(2)设置ProgressBar的进度和提示文字。
设置当前进度progress为integer类型,可以直接设置整型数值,也可以引用integer资
源。属性progress_hint_text表示进度提示文本,为string类型。progress_hint_text_color 
表示进度提示文本颜色,为color类型。例如,设置进度为60%,颜色为black,代码如下:

96 HarmonyOS 应用程序开发与实战（Java 版） 
ohos:progress="60" 
ohos:progress_hint_text="60%" //设置进度条数值
ohos:progress_hint_text_color="black" //设置进度条数值颜色
(3)设置最大值和最小值。
通过设置最大值max和最小值min来控制进度条,两个属性都为integer类型,可以直
接设置整型数值,也可以引用integer资源。例如,设置最大值为100,最小值为0,在XML 
文件中设置: 
ohos:max="100" 
ohos:min="0" 
或者在Java中设置: 
progressBar.setMaxValue(100); 
progressBar.setMinValue(0); 
(4)设置ProgressBar的颜色和分割线。
属性background_instruct_element表示背景色,progress_element表示进度条颜色。
两者都为element类型,可直接配置色值,也可引用color资源或引用media/graphic下的图
片资源。代码如下: 
ohos:progress_element="#FF9900" 
ohos:background_instruct_element="#FF0000" 
属性divider_lines_enabled表示分割线,为boolean类型,可以直接设置true/false,也
可以引用boolean资源。divider_lines_number表示分割线数量,为integer类型,可以直接
设置整型数值,也可以引用integer资源。运行效果如图5-10所示,如在XML文件中配置: 
图5-10 进度颜色和分割线效果

第5 章　UI 组件 97 
ohos:divider_lines_enabled="true" //设置是否显示分割线
ohos:divider_lines_number="5" //设置分割线个数
通过在Java文件中设置分割线颜色,代码如下: 
progressBar.setDividerLineColor(Color.black); 
5.1.4 圆形进度条
RoundProgressBar继承自ProgressBar,拥有ProgressBar的属性,在设置同样的属性
时用法和ProgressBar一致,用于显示环形进度。
1.创建RoundProgressBar 
在layout目录下的XML文件中创建一个RoundProgressBar,同时在Java文件中加载
该XML布局。运行效果如图5-11所示,代码如下: 
<RoundProgressBar 
ohos:id="$+id:round_progress_bar" 
ohos:height="250vp" 
ohos:width="250vp" 
ohos:progress_width="15vp" 
ohos:progress="60" 
ohos:progress_color="blue" 
ohos:progress_hint_text="60%" 
ohos:progress_hint_text_color="#007DFF" 
/> 
2.设置样式
组件RoundProgressBar的基础属性与组件ProgressBar保持一致,如设置进度条的大
小、颜色、进度和提示文字等,都使用同样的属性进行控制,具体属性描述可以参考5.1.3节。
这里主要讲解如何设置RoundProgressBar的开始和结束角度。
RoundProgressBar的自有XML属性为start_angle和max_angle。start_angle表示圆
形进度条的起始角度,max_angle表示圆形进度条的最大角度。通过设置这两个属性值来
控制进度条的开始和结束角度。例如,设置start_angle为20,max_angle为340,运行效果
如图5-12所示。代码如下: 
ohos:start_angle="20" 
ohos:max_angle="340" 
5.1.5 时钟组件
时钟组件是Text的子类,所以可以使用Text的一些属性。
1.创建Clock 
在layout目录下的XML文件中创建一个Clock,同时在Java文件中加载该XML布