鸿蒙应用开发 常用组件与布局
鸿蒙应用开发 常用组件与布局
1 组件介绍
组件（Component）是界面搭建与显示的最小单位，HarmonyOS ArkUI 声明式开发范式为开发者提供了丰富多样的 UI 组件，我们可以使用这些组件轻松的编写出更加丰富、漂亮的界面。
组件根据功能可以分为以下五大类：基础组件、容器组件、媒体组件、绘制组件、画布组件。其中基础组件是视图层的基本组成单元，包括 Text、Image、TextInput、Button、LoadingProgress 等，例如下面这个常用的登录界面就是由这些基础组件组合而成。
下面我们将分别介绍这些常用基础组件的使用。
2 Text
Text 组件用于在界面上展示一段文本信息，可以包含子组件 Span。
文本样式
针对包含文本元素的组件，例如 Text、Span、Button、TextInput 等，可使用 fontColor、fontSize、fontStyle、 fontWeight、fontFamily 这些文本样式，分别设置文本的颜色、大小、样式、粗细以及字体，文本样式的属性如下表：
| 名称 | 参数类型 | 描述 |
|---|---|---|
| fontColor | ResourceColor | 设置文本颜色。 |
| fontSize | Length | Resource | 设置文本尺寸，Length 为 number 类型时，使用 fp 单位。 |
| fontStyle | FontStyle | 设置文本的字体样式。默认值：FontStyle.Normal。 |
| fontWeight | number | FontWeight | string | 设置文本的字体粗细，number 类型取值 [100, 900]，取值间隔为 100，默认为 400，取值越大，字体越粗。string 类型仅支持 number 类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular”、“medium”，分别对应 FontWeight 中相应的枚举值。默认值：FontWeight.Normal。 |
| fontFamily | string | Resource | 设置文本的字体列表。使用多个字体，使用“，”进行分割，优先级按顺序生效。例如：“Arial，sans-serif”。 |
下面示例代码中包含两个 Text 组件，第一个使用的是默认样式，第二个给文本设置了一些文本样式。
@Entry
@Component
struct TextDemo {
build() {
Row() {
Column() {
Text('HarmonyOS')
.fontColor(Color.Blue)
.fontSize(20)
.fontStyle(FontStyle.Italic)
.fontWeight(FontWeight.Bold)
.fontFamily('Arial')
}
.width('100%')
}
.backgroundColor(0xF1F3F5)
.height('100%')
}
}
效果图如下：
除了通用属性和文本样式设置，下面列举了一些 Text 组件的常用属性的使用。
设置文本对齐方式
使用 textAlign 属性可以设置文本的对齐方式，示例代码如下：
Text('HarmonyOS')
.width(200)
.textAlign(TextAlign.Start)
.backgroundColor(0xE6F2FD)
textAlign 参数类型为 TextAlign，定义了以下几种类型：
-
Start（默认值）：水平对齐首部。
-
Center：水平居中对齐。
-
End：水平对齐尾部。
设置文本超长显示
当文本内容较多超出了 Text 组件范围的时候，您可以使用 textOverflow 设置文本截取方式，需配合 maxLines 使用，单独设置不生效，maxLines 用于设置文本显示最大行数。下面的示例代码将 textOverflow 设置为 Ellipsis ，它将显示不下的文本用 “…” 表示：
Text('This is the text content of Text Component This is the text content of Text Component')
.fontSize(16)
.maxLines(1)
.textOverflow({overflow:TextOverflow.Ellipsis})
.backgroundColor(0xE6F2FD)
效果图如下：
设置文本装饰线
使用 decoration 设置文本装饰线样式及其颜色，大家在浏览网页的时候经常可以看到装饰线，例如带有下划线超链接文本。decoration 包含 type 和 color 两个参数，其中 type 用于设置装饰线样式，参数类型为 TextDecorationTyp，color 为可选参数。
下面的示例代码给文本设置了下划线，下划线颜色为黑色：
Text('HarmonyOS')
.fontSize(20)
.decoration({ type: TextDecorationType.Underline, color: Color.Black })
.backgroundColor(0xE6F2FD)
效果图如下：
TextDecorationTyp 包含以下几种类型：
-
None：不使用文本装饰线。
-
Overline：文字上划线修饰。
-
LineThrough：穿过文本的修饰线。
-
Underline：文字下划线修饰。
3 Image
Image 组件用来渲染展示图片，它可以让界面变得更加丰富多彩。只需要给 Image 组件设置图片地址、宽和高，图片就能加载出来，示例如下：
Image($r("app.media.icon"))
.width(100)
.height(100)
效果图如下：
设置缩放类型
为了使图片在页面中有更好的显示效果，有时候需要对图片进行缩放处理。您可以使用 objectFit 属性设置图片的缩放类型，objectFit 的参数类型为 ImageFit。
现有原始图片如下：
将图片加载到 Image 组件，设置宽高各 100，设置 objectFit 为 Cover（默认值），设置图片背景色为灰色 0xCCCCCC。示例代码如下：
Image($r("app.media.image2"))
.objectFit(ImageFit.Cover)
.backgroundColor(0xCCCCCC)
.width(100)
.height(100)
效果图如下：
ImageFit 包含以下几种类型：
-
Contain：保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内。
-
Cover（默认值）：保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界。
-
Auto：自适应显示。
-
Fill：不保持宽高比进行放大缩小，使得图片充满显示边界。
-
ScaleDown：保持宽高比显示，图片缩小或者保持不变。
-
None：保持原有尺寸显示。
加载网络图片
比如浏览新闻的时候，图片一般从网络加载而来，Image 组件支持加载网络图片，将图片地址换成网络图片地址进行加载。
Image('https://www.example.com/xxx.png')
为了成功加载网络图片，您需要在 module.json5 文件中申明网络访问权限。
{
"module" : {
"requestPermissions":[
{
"name": "ohos.permission.INTERNET"
}
]
}
}
应用访问网络需要申请 ohos.permission.INTERNET 权限，因为 HarmonyOS 提供了一种访问控制机制即应用权限，用来保证这些数据或功能不会被不当或恶意使用。关于应用权限的的详细信息开发者可以参考：访问控制。
4 TextInput
TextInput 组件用于输入单行文本，响应输入事件。TextInput 的使用也非常广泛，例如应用登录账号密码、发送消息等。和 Text 组件一样，TextInput 组件也支持文本样式设置，下面的示例代码实现了一个简单的输入框：
TextInput()
.fontColor(Color.Blue)
.fontSize(20)
.fontStyle(FontStyle.Italic)
.fontWeight(FontWeight.Bold)
.fontFamily('Arial')
效果图如下：
设置输入提示文本
当我们平时使用输入框的时候，往往会有一些提示文字。例如登录账号的时候会有“请输入账号”这样的文本提示，当用户输入内容之后，提示文本就会消失，这种提示功能使用 placeholder 属性就可以轻松的实现。您还可以使用 placeholderColor 和 placeholderFont 分别设置提示文本的颜色和样式，示例代码如下：
TextInput({ placeholder: '请输入帐号' })
.placeholderColor(0x999999)
.placeholderFont({ size: 20, weight: FontWeight.Medium, family: 'cursive', style: FontStyle.Italic })
效果图如下：
设置输入类型
可以使用 type 属性来设置输入框类型。例如密码输入框，一般输入密码的时候，为了用户密码安全，内容会显示为“…”，针对这种场景，将 type 属性设置为 InputType.Password 就可以实现。示例代码如下：
TextInput({ placeholder: '请输入密码' })
.type(InputType.Password)
效果图如下：
type 的参数类型为 InputType，包含以下几种输入类型：
-
Normal：基本输入模式。支持输入数字、字母、下划线、空格、特殊字符。
-
Password：密码输入模式。
-
Email：e-mail 地址输入模式。
-
Number：纯数字输入模式。
设置光标位置
可以使用 TextInputController 动态设置光位置，下面的示例代码使用 TextInputController 的 caretPosition 方法，将光标移动到了第二个字符后。
@Entry
@Component
struct TextInputDemo {
controller: TextInputController = new TextInputController()
build() {
Column() {
TextInput({ controller: this.controller })
Button('设置光标位置')
.onClick(() => {
this.controller.caretPosition(2)
})
}
.height('100%')
.backgroundColor(0xE6F2FD)
}
}
效果图如下：
获取输入文本
我们可以给 TextInput 设置 onChange 事件，输入文本发生变化时触发回调，下面示例代码中的 value 为实时获取用户输入的文本信息。
@Entry
@Component
struct TextInputDemo {
@State text: string = ''
build() {
Column() {
TextInput({ placeholder: '请输入账号' })
.caretColor(Color.Blue)
.onChange((value: string) => {
this.text = value
})
Text(this.text)
}
.alignItems(HorizontalAlign.Center)
.padding(12)
.backgroundColor(0xE6F2FD)
}
}
效果图如下：
5 Button
Button 组件主要用来响应点击操作，可以包含子组件。下面的示例代码实现了一个“登录按钮”：
Button('登录', { type: ButtonType.Capsule, stateEffect: true })
.width('90%')
.height(40)
.fontSize(16)
.fontWeight(FontWeight.Medium)
.backgroundColor('#007DFF')
效果图如下：
设置按钮样式
type 用于定义按钮样式，示例代码中 ButtonType.Capsule 表示胶囊形按钮；stateEffect 用于设置按钮按下时是否开启切换效果，当状态置为 false 时，点击效果关闭，默认值为 true。
我们可以设置多种样式的 Button，除了 Capsule 可以以设置 Normal 和 Circle：
-
Capsule：胶囊型按钮（圆角默认为高度的一半）。
-
Circle：圆形按钮。
-
Normal：普通按钮（默认不带圆角）。
设置按钮点击事件
可以给 Button 绑定 onClick 事件，每当用户点击 Button 的时候，就会回调执行 onClick 方法，调用里面的逻辑代码。
Button('登录', { type: ButtonType.Capsule, stateEffect: true })
...
.onClick(() => {
// 处理点击事件逻辑
})
包含子组件
Button 组件可以包含子组件，让您可以开发出更丰富多样的 Button，下面的示例代码中 Button 组件包含了一个 Image 组件：
Button({ type: ButtonType.Circle, stateEffect: true }) {
Image($r('app.media.icon_delete'))
.width(30)
.height(30)
}
.width(55)
.height(55)
.backgroundColor(0x317aff)
效果图如下：
6 LoadingProgress
LoadingProgress 组件用于显示加载进展，比如应用的登录界面，当我们点击登录的时候，显示的“正在登录”的进度条状态。LoadingProgress 的使用非常简单，只需要设置颜色和宽高就可以了。
LoadingProgress()
.color(Color.Blue)
.height(60)
.width(60)
效果图如下：
7 使用资源引用类型
Resource 是资源引用类型，用于设置组件属性的值。推荐大家优先使用 Resource 类型，将资源文件（字符串、图片、音频等）统一存放于 resources 目录下，便于开发者统一维护。同时系统可以根据当前配置加载合适的资源，例如，开发者可以根据屏幕尺寸呈现不同的布局效果，或根据语言设置提供不同的字符串。
例如下面的这段代码，直接在代码中写入了字符串和数字这样的硬编码。
Button('登录', { type: ButtonType.Capsule, stateEffect: true })
.width(300)
.height(40)
.fontSize(16)
.fontWeight(FontWeight.Medium)
.backgroundColor('#007DFF')
我们可以将这些硬编码写到 entry/src/main/resources 下的资源文件中。
在 string.json 中定义 Button 显示的文本。
{
"string": [
{
"name": "login_text",
"value": "登录"
}
]
}
在 float.json 中定义 Button 的宽高和字体大小。
{
"float": [
{
"name": "button_width",
"value": "300vp"
},
{
"name": "button_height",
"value": "40vp"
},
{
"name": "login_fontSize",
"value": "18fp"
}
]
}
在 color.json 中定义 Button 的背景颜色。
{
"color": [
{
"name": "button_color",
"value": "#1890ff"
}
]
}
然后在 Button 组件通过“$r(‘app.type.name’)”的形式引用应用资源。app 代表应用内 resources 目录中定义的资源；type 代表资源类型（或资源的存放位置），可以取“color”、“float”、“string”、“plural”、“media”；name 代表资源命名，由开发者定义资源时确定。
Button($r('app.string.login_text'), { type: ButtonType.Capsule })
.width($r('app.float.button_width'))
.height($r('app.float.button_height'))
.fontSize($r('app.float.login_fontSize'))
.backgroundColor($r('app.color.button_color'))
8 案例：常用组件与布局
简介
HarmonyOS ArkUI 提供了丰富多样的 UI 组件，您可以使用这些组件轻松地编写出更加丰富、漂亮的界面。在本篇 Codelab 中，您将通过一个简单的购物社交应用示例，学习如何使用常用的基础组件和容器组件。本示例主要包含：“登录”、“首页”、“我的”三个页面。
效果图如下：
相关概念
- Text：显示一段文本的组件。
- Image：Image 为图片组件，常用于在应用中显示图片。Image 支持加载 string、PixelMap和Resource类型的数据源，支持 png、jpg、bmp、svg 和 gif 类型的图片格式。
- TextInput：单行文本输入框组件。
- Button：按钮组件，可快速创建不同样式的按钮。
- LoadingProgress：用于显示加载动效的组件。
- Flex：以弹性方式布局子组件的容器组件。
- Column：沿垂直方向布局的容器。
- Row：沿水平方向布局容器。
- List：列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。
- Swiper：滑块视图容器，提供子组件滑动轮播显示的能力。
- Grid：网格容器，由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。
使用说明
- 在登录界面输入账号和密码（任意字符），点击登录按钮跳转到应用首页。
- 点击底部的 Tabs，界面在“首页”和“我的”之间进行切换。
约束与限制
- 本示例仅支持标准系统上运行，支持设备：华为手机或运行在 DevEco Studio 上的华为手机设备模拟器。
- 本示例为 Stage 模型，支持 API version 9。
- 本示例需要使用 DevEco Studio 3.1 Release 版本进行编译运行。
源码地址
在公众号「Android指南」后台发消息「组件」即可获取。