当前位置：首页 > news >正文

【Harmony OS】组件

news 来源：原创 2025/4/26 3:52:14

组件概述

组件常用属性

系统内置组件

Text

TextArea 多行文本输入框组件

TextInput 文本输入框

Button

Image 图片组件，支持本地图片和网络图片

Radio 单选框

Checkbox 复选框

Blank 空白填充组件

Divider 分隔符

PatternLock 图案密码锁组件

Progress 进度条组件

QRCode 二维码组件

Rating 评分组件

RichText 富文本组件

Search 搜索框组件

Select 下拉选择菜单

Slider 滑动条组件

Stepper与StepperItem 步骤导航器组件

TextClock 当前系统时间显示，支持不同时区的时间显示，最高精确到秒级

TextTimer 计时器组件

Toggle 组件提供复选框样式、状态按钮样式及开关样式

DataPanel 数据面板，主要支持两类数据面板

Gauge 数据量规图表

ImageAnimator 动画组件，来实现逐帧播放图片

Marquee 跑马灯组件

系统图表库

组件概述

组件需要放置到组件容器中

组件容器也称为布局

• 基于ArkTS的HarmonyOS应用开发中，系统提供了丰富的组件，如Text、TextArea、Button、Image、Slider等

• 系统也提供了很多容器组件，如Row、Column、Flex、Navigator、List、Tabs等

• 尽管这里把组件分为容器组件和普通组件，但实际上有的普通组件也是可以容纳其它的组件，因此容器组件和普通组件实际上没有明确的界限，都是组件

• 在应用界面中，实例化组件的一般语法为：
组件名([参数]){

//参数视组件而定，是可选的

//子组件，如果没有子组件，此部分和花括号都可以省略

}.链式调用组件属性方法( ) //组件属性方法一般也有参数
Row() {
Image($r('app.media.loading')) 
.width(20).height(20).margin({ left: 12 })
Text('加载中...')
.fontSize(12).fontColor(0xFFFFFF)
}.alignItems( VerticalAlign.Center )
@Entry // 入口组件装饰器

@Component // 组件装饰器

struct Index { // 定义组件

build() { // 生成器函数

Column() { // 列容器组件

Image($r('app.media.icon')) // 图片组件

.height(100).width(100) // 设置高、宽属性

.margin({ top: 150 }) // 设置边距

TextInput().width("80%").height(50).margin(10) // 输入框组件

TextInput().width("80%").height(50).margin(10)

.type(InputType.Password)

Button(" 登录 ") // 按钮组件

.width("60%")

.height(50)

.margin(20)

}.height("100%") // 设置 Column 的高度

.width("100%") // 设置 Column 的宽度

}

}

组件常用属性

• 组件属性可以分为通用属性和自定义属性

• 通用属性包括尺寸、位置、背景、文本样式等等

• 尺寸是用来设置组件大小的，如宽、高等。一般组件都具有的尺寸属性及说明如表

名称	说明	取值举例
width	宽度，缺省时使用元素自身内容需要的宽度，值为Length类型	Button("您好").width(100) .height(50)
height	高度，缺省时使用元素自身内容需要的高度，值为Length类型	Button("您好").width('100%'). height('30px')
size	大小，可以同时设置宽高，值为JSON对象，内部包含宽度和高度，宽高类型为Length类型	{width?:Length,height?:Length}
padding	内边距，可以同时设置四个方向内边距，也可设置指定方向的内边距，设置四个方向时，采用JSON对象参数，内包含四个方向的值都是Length类型，当设置一个值时表示同时设置四个方向内边距一致	{top?:Length,right?:Length,bottom ?:Length,left?:Length}或 Length
margin	外边距，方式同上	同上
constraintSize	设置约束尺寸，对组件布局进行尺寸范围限制，包括宽度和高度的最小值和最大值	{minWidth?:Length,maxWidth?:Length,minHeight?:Length,maxHeig ht?:Length}
layoutWeight	组件在布局中的大小权重，在容器尺寸确定时，元素与兄弟结点主轴布局尺寸按照权重进行分配，默认自适应占满剩余空间。该属性仅在Row/Column/Flex有效	值为number类型数值

• 在描述尺寸时一般会用到 Length 类型值，Length类型是系统定义的类型，它可以是字符串（string）、数值（number）和资源（Resource）。

• 在使用字符串（string）表示文字大小时，可以显式指定像素单位，如'30px'、'30vp'等，也可设置百分比字符串，如'80%'。

• 在使用数值（number）表示尺寸大小时，可以直接使用数值，其默认单位是vp，如30。

• 资源（Resource）是使用引入资源的方式，使用系统资源或者应用资源中的尺寸。

• 位置属性顾名思义是设置组件的位置关系的，如居中、坐标、偏移量等。

一般组件都具有的位置属性及说明如表

名称	说明	取值举例
align	组件内容的对齐方式，只有当设置的宽、高超过元素内容大小时才有效，值为类型	Text('您好') .size({width:100,height:100 }) .align(Alignment.End) 另外， Alignment还有Top、TopStart、Start 、Center、Buttom等枚举值
direction	设置元素水平方向的布局，可选值为Direction枚举类型	有三个枚举值Ltr表示元素从左到右布局 Rtl表示元素从右到左布局Auto表示系统默认布局方向
position	位置，表示组件在父容器中的位置。默认以组件的左上角为基准	{x:Length,y:Length}
markAnchor	组件位置定位时的锚点，以元素顶部起点作为基准点进行偏移	{x:Length,y:Length}默认值是（0，0）
offset	相对布局完成位置坐标偏移量，设置该属性，不影响父容器布局，仅在绘制时进行位置调整。	{x:Length,y:Length}默认值是（0，0）

• 文本样式主要是设置组件内显示的文本的颜色、大小、字体等，关于文本设置的主要属性如表

名称	说明	取值举例
fontColor	文本颜色，值为Color类型，可以直接用颜色值，也可以采用系统中的颜色	Text('您好') .size({width:100,height:100 }) .fontColor(0xFF0000)
fontSize	字体大小，值为Length类型，当为数值时默认单位为fp	Text('您好') .size({width:100,height:100 }) .fontSize(30)
fontStyle	字体样式，值为类型	Text('您好') .fontStyle(FontStyle.Normal)
fontWeight	字体粗细，值为number或FontWeight 以取100~900 枚举类型，数值可中的整百数值，默认为400 ，值越大字越粗，FontWeight提供了枚举类型	Text(this.message).fontSize(50) .fontWeight(FontWeight.Bold)
fontFamily	字体，值为字符串类型。可以设置一种字体，也可以设置多种候选字体，以‘,’分割，按顺序选择显示的字体	Text(this.message).fontSize(50) .fontFamily(‘Arial,sans-serif’)

其它属性

• 属性都可以通过链式调用方式设置

• 关于组件属性的分类说明如表

名称	主要用途说明
显示样式方面	组件的大小、位置、背景、透明度、边框、颜色渐变等
布局约束方面	宽高比、显示优先级、Flex约束、栅格间距等
显示控制方面	显示隐藏控制、禁用控制、增加浮层、Z序控制（层控制）等
图形图像处理方面	图形变换（旋转、平移、缩放、矩阵变换），图像效果（模糊、阴影、灰度、高光、饱和度、对比度、反转、颜色叠加、色相旋转、裁剪、遮盖等）