HarmonyOS鸿蒙开发 | ArkUI | 界面开发
在学习HarmonyOS ArkUI（方舟开发框架）时，整理了一份笔记，方便日后回顾。
本文档为HarmonyOS ArkUI（方舟开发框架）零基础入门学习笔记，基于ArkTS声明式开发范式编写，既适合新手快速上手鸿蒙界面开发，也可作为日常开发的速查手册。
开发环境为HarmonyOS官方开发工具 DevEco Studio 。
一、开发起步
核心开发工具
HarmonyOS界面开发的官方IDE为 DevEco Studio，内置代码编辑器、实时预览器、模拟器等全套开发工具，无需额外配置环境即可快速开发。
-
代码编写：在
build()函数内编写UI构建代码 -
效果查看：通过右侧预览器查看界面效果
声明式UI核心入口
ArkTS声明式开发的核心是自定义组件，每个组件的UI结构都必须在 build() 函数中声明。
build() 函数有且仅有一个根容器组件，不允许多个同级根元素。
基础代码结构模板：
@Entry
@Component
struct Index {
// 声明状态变量等业务逻辑
build() {
// 唯一根容器组件
Column() {
// 界面内容：子组件、嵌套容器等
}
// 组件的属性样式
.width('100%')
.height('100%')
}
}
-
@Component：装饰器，标记当前结构体为自定义组件，可复用。 -
@Entry：装饰器，标记当前组件为页面入口组件，预览器会优先渲染该组件。
二、布局思路：组件化开发
ArkUI（方舟开发框架）是鸿蒙官方主推的应用界面构建框架，核心采用组件化的声明式开发思想，所有界面元素都由组件构成。
组件分类
| 组件类型 | 核心作用 | 常见示例 |
|---|---|---|
| 基础组件 | 界面呈现的最小基础元素 负责内容展示与交互 | 文本Text、按钮Button 图片Image、输入框TextInput |
| 容器组件 | 负责子组件的布局排列、尺寸约束 控制界面整体结构 | 行布局Row、列布局Column 列表List、堆叠布局Stack |
标布局开发流程
界面开发遵循「先排版 、再填内容 、最后美化」的核心思路：
-
拆分界面结构，用容器组件完成整体行列排版。
-
在容器中放入基础组件，填充界面内容。
-
通过属性方法为组件设置样式、交互，完成界面美化。
三、组件的属性方法
属性方法用于美化组件外观、约束组件尺寸，通用属性可用于所有组件 。
| 属性方法 | 作用说明 | 使用注意事项 |
|---|---|---|
.width(数值) | 设置组件宽度 | 纯数值直接写数字即可 百分比需要用单引号包裹，如 .width('100%')。 |
.height(数值) | 设置组件高度 | 纯数值直接写数字即可 百分比需要用单引号包裹，如 .height('100%')。 |
.backgroundColor(颜色值) | 设置组件背景色 | 支持颜色枚举和16进制色值 |
.padding(数值/边距对象) | 设置组件内边距 | 单数值为四边统一内边距 可指定单独边距，如 .padding({ left: 10, right: 10, top: 5, bottom: 5 })。 |
.margin(数值/边距对象) | 设置组件外边距 | 控制组件与其他组件的间距 单数值为四边统一内边距;可指定单独边距，如 .margin({ left: 10, right: 10, top: 5, bottom: 5 })。 |
// 组件声明在前 属性方法按顺序链式调用（每个属性独占一行更易读）
组件名(参数) {
// 容器组件的子内容
}
.属性方法1(参数)
.属性方法2(参数)
.属性方法3(参数)
四、基础组件
1. 文本组件 Text
用于在界面中展示文本内容，是最基础的内容组件，支持丰富的文本样式配置。
Text('文本内容') // 语法
核心属性与用法
-
字体样式配置
Text('鸿蒙开发') .fontSize(30) // 字体大小 .fontWeight(FontWeight.Bold) // 字体粗细 .fontColor(Color.Blue) // 字体颜色 .lineHeight(40) // 文本行高（控制文本垂直间距）-
字体粗细：支持枚举值（
FontWeight.Normal/Bold/Bolder/Lighter等） 支持100-900的数值设置，默认值为400（Normal），700等同于Bold -
字体颜色：两种写法通用所有颜色相关属性
-
枚举颜色：
Color.颜色名IDE会自动弹出可选颜色列表 -
16进制色值：
'#十六进制色号'必须用单引号包裹（如'#df3c50'、'#333333'）
-
-
-
文本溢出省略
文本溢出省略是超长文本的展示控制
textOverflow 必须配合 maxLines 使用才会生效
Text('这是一段超长的文本内容，用于测试文本溢出省略的效果，超出指定行数后会自动显示省略号')
.width(200) // 必须约束宽度 否则文本会无限撑开
.maxLines(2) // 限制最大显示行数
.textOverflow({ overflow: TextOverflow.Ellipsis }) // 溢出显示省略号
溢出模式可选值：
-
TextOverflow.Ellipsis：溢出文本显示省略号（最常用） -
TextOverflow.Clip：溢出文本直接裁切，无省略号。 -
TextOverflow.Marquee：文本单行滚动展示（跑马灯效果）（maxLines设置无效）
2. 图片组件 Image
用于在界面中展示图片 支持本地图片资源和网络图片资源
Image(图片数据源) // 语法
网络图片 直接传入图片的网络地址字符串 注意：加载网络图片需要在应用配置中申请网络权限
Image('https://example.com/image.jpg')
.width(200)
.height(200)
.objectFit(ImageFit.Cover) // 图片缩放模式
本地图片
本地图片需存放至项目固定路径 main/resources/base/media 目录下，通过 $r 资源引用语法调用，无需写文件后缀名。
// 示例：media目录下有一张logo.png图片
Image($r('app.media.logo'))
.width(150)
.height(50)
关键注意事项
-
仅设置width或height其中一个属性，另一个维度会自动按图片原始比例等比例缩放，无需手动计算。
-
objectFit属性用于控制图片缩放模式- 常用值：
ImageFit.Cover和ImageFit.Contain ImageFit.Cover: 铺满容器 不变形 裁切多余部分）ImageFit.Contain: 完整展示图片 不变形 容器可能留空）
- 常用值：
3. 输入框组件 TextInput
用于接收用户输入的文本内容，常用于登录、注册、表单等场景。
// 语法
TextInput(参数对象)
.属性方法()
核心用法
- 基础输入框配置
// 用户名输入框（明文） TextInput({ placeholder: '请输入用户名' // 占位提示文本 无输入时显示 }) .type(InputType.Normal) // 输入框类型 明文普通输入 .width('100%') .height(45) // 密码输入框（密文） TextInput({ placeholder: '请输入密码' }) .type(InputType.Password) // 密码类型 输入内容自动隐藏 .width('100%') .height(45)
- 常用输入类型
| 类型枚举 | 适用场景 |
|---|---|
InputType.Normal | 普通文本输入，明文显示，无特殊限制。 |
InputType.Password | 密码输入，密文隐藏内容。 |
InputType.Email | 邮箱地址输入 |
InputType.Number | 数字输入，仅支持输入数字。 |
InputType.PhoneNumber | 手机号输入 |
InputType.NUMBER_DECIMAL | 带小数点的数字输入 只能输入数字0-9和小数点 |
InputType.URL | 带URL的输入，无特殊限制。 |
- 输入内容获取
通过 onChange 事件实时获取用户输入的内容，搭配状态变量使用。
// 先声明状态变量存储输入内容
@State userName: string = ''
// 输入框绑定事件
TextInput({ placeholder: '请输入用户名' })
.onChange((value: string) => {
this.userName = value // 实时赋值给状态变量
})
4. 按钮组件 Button
用于响应用户点击操作，是界面交互的核心组件。
// 语法
Button('按钮显示文本')
.属性方法()
.onClick(() => {
// 点击按钮执行的逻辑
})
常用配置示例
Button('登录')
.width('100%')
.height(50)
.fontSize(18)
.fontWeight(FontWeight.Medium)
.backgroundColor('#007DFF')
.onClick(() => {
// 点击登录按钮执行的逻辑
console.log('点击了登录按钮')
})
五、容器组件
容器组件是布局的核心，用于控制子组件的排列方式。
最常用的容器组件为Row行布局和Column列布局，二者统称为弹性布局容器。
1. 基础语法
容器组件通过()内的参数配置布局规则，{}内写入子组件，子组件会按容器规则自动排列。
// 基础结构
容器组件名({ 布局参数 }) {
子组件1
子组件2
子组件3
}
.容器通用属性
2. 列布局 Column
垂直方向排列子组件，主轴为垂直方向，交叉轴为水平方向，是页面最常用的根容器。
参数与属性
-
子组件间距：
space参数（控制子组件之间的垂直间距）Column({ space: 20 }) { Text('文本1') Text('文本2') Text('文本3') } // 三个文本之间会自动保留20vp的垂直间距
-
主轴对齐（垂直方向）：
justifyContent属性Column() { // 子组件 } .justifyContent(FlexAlign.Center) // 垂直方向居中常用对齐枚举：
-
FlexAlign.Start：顶部对齐（默认值） -
FlexAlign.Center：垂直居中 -
FlexAlign.End：底部对齐 -
FlexAlign.SpaceBetween：两端对齐，子组件之间间距均分。 -
FlexAlign.SpaceAround：每个子组件左右两侧间距均分 -
FlexAlign.SpaceEvenly：所有间距完全均分
-
-
交叉轴对齐（水平方向）：
alignItems属性Column() { // 子组件 } .alignItems(HorizontalAlign.Start) // 水平方向居左常用对齐枚举：
-
HorizontalAlign.Center：水平居中（默认值） -
HorizontalAlign.Start：居左对齐 -
HorizontalAlign.End：居右对齐
-
3. 行布局 Row
水平方向排列子组件，主轴为水平方向，交叉轴为垂直方向，常用于横向排列的内容，如标签栏、按钮组、信息行等。
参数与属性
- 子组件间距：
space参数（控制子组件之间的水平间距）Row({ space: 10 }) { Text('都市') Text('生活') Text('情感') Text('男频') } // 四个文本之间自动保留10vp的水平间距
-
主轴对齐（水平方向）：
justifyContent属性（控制水平方向的子组件排列）Row() { // 子组件 } .justifyContent(FlexAlign.Center) // 水平方向居中常用主轴对齐枚举：
-
FlexAlign.Start：水平居左（默认值） -
FlexAlign.Center：水平居中 -
FlexAlign.End：水平居右 -
FlexAlign.SpaceBetween：两端对齐（靠边），子组件间间距均分。 -
justifyContent(FlexAlign.SpaceAround)：两端对齐（元素间间距的一半），子组件间间距均分。 -
justifyContent(FlexAlign.SpaceEvenly)：两端对齐（与元素间间距相同），子组件间间距均分。
-
-
交叉轴对齐（垂直方向）：
alignItems属性（控制垂直方向的子组件对齐）Row() { // 子组件 } .alignItems(VerticalAlign.Top) // 垂直方向居上常用对齐枚举：
-
VerticalAlign.Center：垂直居中（默认值） -
VerticalAlign.Top：居上对齐 -
VerticalAlign.Bottom：居下对齐
-
六、注意事项
-
build函数规则
build()内有且仅有一个根容器组件，禁止多个同级根元素，否则会编译报错。
-
文本溢出规则
textOverflow必须配合maxLines和固定宽度.width使用，三者缺一不可，否则省略号不生效。
-
单位与引号规则 纯数值无需加引号，百分比、16进制色值、字符串参数必须用引号包裹。
-
网络图片权限 加载网络图片必须在
module.json5中申请ohos.permission.INTERNET网络权限，否则图片无法加载。
-
容器对齐默认值 Column默认水平居中、垂直顶部对齐 Row默认垂直居中、水平居左对齐
-
属性调用顺序 组件的属性方法必须写在组件声明的括号之后，容器组件的属性要写在
{}闭合之后，不能写在子组件内部。
-
资源引用规则 本地图片引用
$r('app.media.文件名')，无需写文件后缀，文件名不能有中文、空格和特殊符号。
