HarmonyOS 登录页面开发实战：Image、Text、TextInput、Button 组件详解

黄健华Yeah

164人浏览 · 2026-08-05 14:22:51

黄健华Yeah · 2026-08-05 14:22:51 发布

引言

实际开发页面时，需要先设定页面布局结构，再分析页面元素构成，然后选择合适组件配置属性，控制各个元素的位置、大小和展示效果。本节课将以登录页面为例，系统讲解 HarmonyOS 中 Image、Text、TextInput、Button 四个基础 UI 组件的使用方法。

核心内容

登录页面布局分析

登录页面整体使用垂直 Column 容器布局，水平排列的组合组件需要嵌套 Row 容器实现，从上到下依次排布各类 UI 元素。

布局结构代码框架：

build() {
  Column() {
    Image(...)
    Text(...)
    Text(...)
    TextInput(...)
    TextInput(...)
    ...
    Row() {
      Text(...)
      Text(...)
    }
    ...
    Button(...)
    ...
    Row(...) {
      Button(...)
      Button(...)
      Button(...)
    }
  }
}

核心基础组件：

组件	功能
`Image`	渲染展示图片
`Text`	展示一段文本信息
`TextInput`	输入单行文本，响应输入事件
`Button`	响应用户点击操作

Image 组件基础使用

Image 组件用于渲染展示图片，支持加载本地资源图片和网络图片。

图片数据源设置

Image 组件入参 src 为图片数据源，支持三种数据类型：

ResourceStr：可加载网络图片、本地资源图片
PixelMap：加载像素地图对象
DrawableDescriptor：加载可绘制对象描述符

加载网络图片需要在 module.json5 配置文件中添加网络访问权限；本地资源图片需要提前放置到项目 resources 目录下再引用。

// 加载网络图片
Image('https://xxxxxx')

// 加载本地资源图片
Image($r('app.media.logo'))

// PixelMap 方式加载
Image(pixelMapObject)

// DrawableDescriptor 方式加载
Image((getContext().resourceManager.getDrawableDescriptor($r('app.media.icon').id)))

图片大小设置

width 和 height 属性支持三种参数类型：

参数类型	说明	示例
`number`	默认单位为 `vp`，直接写数值即可	`.width(78)`
`string`	需要显式指定单位	`.width('78vp')`
`Resource`	从 `resources` 资源文件中读取配置值	`.width($r('app.float.logo_image_size'))`

推荐优先使用 Resource 类型，便于统一维护。

// number 类型
Image($r('app.media.logo'))
  .width(78)
  .height(78)

// string 类型
Image($r('app.media.logo'))
  .width('78vp')
  .height('78vp')

// Resource 类型
Image($r('app.media.logo'))
  .width($r('app.float.logo_image_size'))
  .height($r('app.float.logo_image_size'))// number 类型
Image($r('app.media.logo'))
  .width(78)
  .height(78)

// string 类型
Image($r('app.media.logo'))
  .width('78vp')
  .height('78vp')

// Resource 类型
Image($r('app.media.logo'))
  .width($r('app.float.logo_image_size'))
  .height($r('app.float.logo_image_size'))

图片外边距设置

使用 margin 属性设置图片外间距，支持 Margin、Length、LocalizedMargin 三种参数类型：

// 四个方向外边距均为 20
Image($r('app.media.logo'))
  .width(78)
  .height(78)
  .margin(20)

// 仅设置底部外边距为 20
Image($r('app.media.logo'))
  .width(78)
  .height(78)
  .margin({ bottom: 20 })

图片缩放类型

使用 objectFit 属性设置图片在指定宽高框内的缩放模式，共 6 种类型：

取值	说明
`Contain`	保持宽高比缩放，保证图片完整显示在显示边界内
`Cover`	保持宽高比缩放，图片宽高都大于等于显示边界
`Auto`	根据图片原尺寸和组件尺寸自动缩放，保持比例填充
`Fill`	拉伸图片充满整个显示边界
`ScaleDown`	保持宽高比，缩小或保持原尺寸显示
`None`	按照图片原有尺寸原始显示

Text 组件基础使用

Text 组件用于在界面展示一段文本信息，是开发中最常用的基础组件。

添加子组件 Span

Text 支持添加 Span 作为子组件，实现同一文本块内不同样式的分段文本。

Span 必须写在 Text 组件内才会显示，单独使用不会生效；如果同时给 Text 和 Span 配置文本内容，Span 内容会覆盖 Text 的内容。

Text('我是Text') {
  Span('我是Span')
}
.padding(10)
.borderWidth(1)

文本内容设置

入参 content 为要显示的文本内容，支持两种数据类型：

// string 类型
Text('登录界面')

// Resource 类型
Text($r('app.string.login_page'))

文本样式设置

属性	说明	示例
`fontSize`	字体大小，`number` 默认单位为 `fp`	`.fontSize(24)`
`fontWeight`	字体粗细，支持数值（100~900，步长100，默认400）和枚举	`.fontWeight(FontWeight.Medium)`
`fontColor`	字体颜色，支持 `Color` 枚举、十六进制、RGB/RGBA、`Resource`	`.fontColor('#182431')`
`decoration`	文本装饰线（无/删除线/下划线/上划线）	`.decoration({ type: TextDecorationType.LineThrough })`

登录标题示例：

Text('登录界面')
  .fontSize(24)
  .fontWeight(FontWeight.Medium)
  .fontColor('#182431')

超长文本处理

textOverflow 属性需要配合 maxLines 属性一起使用才会生效，单独设置不会生效，可实现超长文本省略号折叠效果。

Text('这是一段很长的文本内容')
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

TextInput 组件基础使用

TextInput 组件用于实现单行文本输入，可响应用户输入事件，获取用户输入内容。

核心属性

属性	说明
`placeholder`	设置输入框占位提示文字，引导用户输入
`maxLength`	限制用户输入的最大字符数
`type`	指定输入框类型
`onChange`	输入事件回调，获取用户输入内容

输入类型

取值	说明
`InputType.Number`	仅允许输入数字，适用于手机号输入
`InputType.Password`	密码类型，输入内容会被遮挡

账号输入框示例：

TextInput({ placeholder: '账号' })
  .maxLength(11)
  .type(InputType.Number)
  .onChange((value: string) => {
    // 处理用户输入内容
    this.account = value;
  })

Button 组件基础使用

Button 组件用于响应用户点击操作，处理用户交互逻辑，常用于登录、提交等操作按钮。

按钮类型

通过 type 属性设置按钮类型：

取值	说明
`ButtonType.Capsule`	胶囊按钮，圆角自动等于按钮高度的一半
`ButtonType.Circle`	圆形按钮
`ButtonType.Normal`	普通按钮
`ButtonType.RoundedRectangle`	圆角矩形按钮

胶囊按钮和圆形按钮也可以通过 borderRadius 属性自定义修改圆角大小。

按钮样式定制

Button('登录')
  .type(ButtonType.Capsule)
  .borderRadius(20)           // 自定义圆角
  .borderWidth(1)             // 边框宽度
  .borderColor('#007dff')     // 边框颜色
  .backgroundColor('#007dff') // 背景色
  .fontSize(16)               // 文本大小
  .fontColor(Color.White)     // 文本颜色
  .onClick(() => {
    // 执行登录逻辑
    this.login();
  })

完整登录页面开发流程

顶部区域：在根 Column 容器内，首先添加 Image 组件放置 App Logo，设置对应宽高和外边距；然后添加 Text 组件作为页面标题，设置字体粗细和大小，再添加小号 Text 作为描述文字，设置字体大小、颜色和外边距。
账号密码输入区域：添加两个 TextInput 组件，分别实现账号和密码输入，对应设置 placeholder 提示文字、maxLength 长度限制、输入类型，添加 onChange 输入回调获取输入内容。
快捷链接区域：嵌套 Row 容器，放入两个 Text 组件分别对应“短信验证码登录”和“忘记密码”，通过设置水平对齐方式让两个文本居左居右分散对齐。
操作按钮区域：添加 Button 组件实现登录按钮，设置按钮类型、背景色、文本样式，添加 onClick 点击事件绑定登录逻辑；在按钮下方添加 Text 组件实现注册账号入口。
其他登录方式区域：使用 Row 容器放置三个第三方登录按钮，对于重复样式的按钮可以封装为公共方法批量调用，简化代码。

总结

本节课讲解了登录页面中用到的四个基础 UI 组件：

Image 组件：用于渲染展示图片，支持本地资源和网络图片加载。src 支持 ResourceStr、PixelMap、DrawableDescriptor 三种类型；加载网络图片需在 module.json5 中添加网络访问权限；width/height 支持 number、string、Resource 三种参数类型；objectFit 提供 6 种缩放模式。
Text 组件：用于展示文本信息。支持嵌套 Span 实现富文本（Span 必须写在 Text 内部）；textOverflow 必须与 maxLines 配合使用；fontSize、fontWeight、fontColor、decoration 等属性控制文本样式。
TextInput 组件：用于单行文本输入。placeholder 设置提示文字，maxLength 限制输入长度，type 设置输入类型（Number/Password 等），onChange 获取输入内容。
Button 组件：用于响应用户点击。支持 Capsule、Circle、Normal、RoundedRectangle 四种类型；通过 borderRadius、backgroundColor、fontSize 等自定义样式；onClick 绑定点击事件。