系列文章：鸿蒙NEXT开发实战系列 -- 第11篇 适合人群：鸿蒙开发初学者和中级开发者 开发环境：DevEco Studio 5.0.5+ | HarmonyOS NEXT (API 14) 阅读时长：约35分钟

一、引言：为什么系统掌握组件库很重要

在鸿蒙应用开发中，UI组件是构建用户界面的基石。很多开发者在开发过程中经常遇到"这个效果该用什么组件实现"的困惑，或者明明ArkUI已经提供了内置组件，却因为不熟悉而自己重复造轮子。

ArkUI框架提供了42个精心设计的内置组件，覆盖了从基础展示到复杂交互的各类场景。系统掌握这些组件，不仅能大幅提升开发效率，还能保证应用的一致性和性能。

本文将这些组件按功能分为8大类，逐一讲解每个组件的核心用法和实战场景，建议收藏备用。

---

二、基础组件

基础组件是使用频率最高的UI元素，用于展示信息和接收用户输入。

2.1 Text - 文本组件

用于展示单行或多行文本内容。

常用属性	类型	说明
fontSize	Length	字体大小
fontWeight	number/FontWeight	字体粗细
fontColor	ResourceColor	字体颜色
maxLines	number	最大行数
textAlign	TextAlign	文本对齐方式
textOverflow	TextOverflow	文本溢出处理

Text('Hello HarmonyOS')
  .fontSize(24)
  .fontWeight(FontWeight.Bold)
  .fontColor('#333333')
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

2.2 Image - 图片组件

用于展示本地或网络图片资源。

常用属性	类型	说明
src	string/Resource	图片资源路径
objectFit	ImageFit	图片填充模式
alt	string/Resource	加载占位图
borderRadius	Length	圆角半径

Image($r('app.media.icon'))
  .width(100)
  .height(100)
  .objectFit(ImageFit.Cover)
  .borderRadius(12)

// 网络图片
Image('https://example.com/image.jpg')
  .alt($r('app.media.placeholder'))

2.3 Button - 按钮组件

用于触发点击事件的交互组件。

常用属性	类型	说明
type	ButtonType	按钮类型（Normal/Capsule/Circle）
stateEffect	boolean	是否开启按压效果
backgroundColor	ResourceColor	背景色

Button('点击我', { type: ButtonType.Capsule })
  .width(200)
  .height(48)
  .backgroundColor('#007DFF')
  .fontSize(16)
  .onClick(() => {
    console.info('Button clicked')
  })

2.4 TextInput - 单行输入框

用于接收用户单行文本输入。

常用属性	类型	说明
placeholder	string	占位提示文字
type	InputType	输入类型（Normal/Password/Email等）
maxLength	number	最大输入长度
showPasswordIcon	boolean	是否显示密码图标

TextInput({ placeholder: '请输入用户名' })
  .width('100%')
  .height(48)
  .maxLength(20)
  .onChange((value: string) => {
    console.info('输入内容: ' + value)
  })

2.5 TextArea - 多行输入框

用于接收用户多行文本输入。

常用属性	类型	说明
placeholder	string	占位提示文字
maxLength	number	最大输入长度
autoHeight	boolean	是否自动调整高度

TextArea({ placeholder: '请输入详细描述...' })
  .width('100%')
  .height(150)
  .maxLength(500)
  .fontSize(16)

2.6 Progress - 进度条组件

用于展示任务完成进度。

常用属性	类型	说明
value	number	当前进度值（0-100）
total	number	总进度值
type	ProgressType	进度条类型（Linear/Ring/Eclipse）
color	ResourceColor	进度条颜色

Progress({ value: 60, total: 100, type: ProgressType.Linear })
  .width('100%')
  .height(8)
  .color('#007DFF')

2.7 LoadingProgress - 加载进度

用于展示加载状态的旋转动画。

LoadingProgress()
  .width(48)
  .height(48)
  .color('#007DFF')

---

三、容器组件

容器组件用于布局和组织其他组件，是页面结构的骨架。

3.1 Column - 纵向布局

子组件沿垂直方向排列。

Column({ space: 16 }) {
  Text('第一行')
  Text('第二行')
  Text('第三行')
}
.width('100%')
.padding(16)

3.2 Row - 横向布局

子组件沿水平方向排列。

Row({ space: 12 }) {
  Text('左侧')
  Blank() // 弹性空白
  Text('右侧')
}
.width('100%')
.padding(16)

3.3 Stack - 层叠布局

子组件层叠堆放，后添加的在上层。

Stack({ alignContent: Alignment.BottomEnd }) {
  Image($r('app.media.bg'))
    .width(200)
    .height(200)
  Text('角标')
    .backgroundColor(Color.Red)
    .fontColor(Color.White)
    .padding(4)
}

3.4 Flex - 弹性布局

提供更灵活的布局能力，支持换行和对齐控制。

Flex({
  direction: FlexDirection.Row,
  wrap: FlexWrap.Wrap,
  justifyContent: FlexAlign.SpaceBetween,
  alignItems: ItemAlign.Center
}) {
  // 子组件
}
.width('100%')

3.5 Grid - 网格布局

以网格形式排列子组件。

Grid() {
  ForEach(this.items, (item: string) => {
    GridItem() {
      Text(item)
    }
  })
}
.columnsTemplate('1fr 1fr 1fr')
.rowsTemplate('1fr 1fr')
.columnsGap(8)
.rowsGap(8)
.width('100%')
.height(300)

3.6 RelativeContainer - 相对布局

子组件可以通过相对位置关系进行布局。

RelativeContainer() {
  Text('左上角')
    .id('topLeft')
    .alignRules({
      top: { anchor: '__container__', align: VerticalAlign.Top },
      left: { anchor: '__container__', align: HorizontalAlign.Start }
    })
}
.width('100%')
.height(200)

3.7 Scroll - 滚动容器

为子组件提供滚动能力。

Scroll() {
  Column({ space: 8 }) {
    ForEach(this.items, (item: string) => {
      Text(item).height(50)
    })
  }
}
.scrollable(ScrollDirection.Vertical)
.width('100%')
.height(300)

3.8 List - 列表容器

高效展示大量数据的滚动列表，支持懒加载。

List({ space: 8 }) {
  ForEach(this.dataList, (item: DataType) => {
    ListItem() {
      Row() {
        Text(item.title)
        Text(item.desc)
      }
    }
  }, (item: DataType) => item.id.toString())
}
.width('100%')
.layoutWeight(1)

---

四、表单组件

表单组件用于数据采集和状态切换。

4.1 Toggle - 开关组件

用于切换两种状态（开/关）。

Toggle({ type: ToggleType.Switch, isOn: this.isSwitchOn })
  .selectedColor('#007DFF')
  .onChange((isOn: boolean) => {
    this.isSwitchOn = isOn
  })

4.2 Slider - 滑动条组件

用于在一定范围内选择数值。

Slider({
  value: this.sliderValue,
  min: 0,
  max: 100,
  step: 5,
  style: SliderStyle.OutSet
})
  .width('100%')
  .blockColor('#007DFF')
  .onChange((value: number) => {
    this.sliderValue = value
  })

4.3 Radio - 单选组件

在一组选项中选择一个。

Radio({ value: 'option1', group: 'radioGroup' })
  .checked(this.selectedValue === 'option1')
  .onChange((isChecked: boolean) => {
    if (isChecked) {
      this.selectedValue = 'option1'
    }
  })
  .width(20)
  .height(20)

4.4 Checkbox - 复选框组件

在一组选项中选择多个。

Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
  .select(this.isChecked)
  .selectedColor('#007DFF')
  .onChange((value: boolean) => {
    this.isChecked = value
  })

4.5 Select - 下拉选择器

从预设选项列表中选择。

Select([
  { value: '选项一' },
  { value: '选项二' },
  { value: '选项三' }
])
  .selected(0)
  .value('请选择')
  .onSelect((index: number, value: string) => {
    console.info('选中: ' + value)
  })

4.6 DatePicker - 日期选择器

选择日期。

DatePicker({
  start: new Date('2020-01-01'),
  end: new Date('2030-12-31'),
  selected: this.selectedDate
})
  .onChange((value: DatePickerResult) => {
    this.selectedDate = new Date(value.year, value.month, value.day)
  })

4.7 TimePicker - 时间选择器

选择时间。

TimePicker({
  selected: this.selectedTime
})
  .onChange((value: TimePickerResult) => {
    this.selectedTime = new Date(0, 0, 0, value.hour, value.minute)
  })

---

五、媒体组件

5.1 Video - 视频组件

用于播放视频内容。

Video({
  src: $r('app.media.video'),
  previewUri: $r('app.media.cover')
})
  .width('100%')
  .height(240)
  .autoPlay(false)
  .controls(true)
  .objectFit(ImageFit.Contain)

5.2 XComponent - 自绘组件

用于渲染自定义内容，常用于游戏、相机预览等场景。

XComponent({
  id: 'xcomponent',
  type: XComponentType.SURFACE,
  libraryname: 'mylib'
})
  .width('100%')
  .height(300)

---

六、导航组件

6.1 Tabs + TabContent - 页签组件

实现页签切换效果。

Tabs({ barPosition: BarPosition.Start }) {
  TabContent() {
    Text('首页内容')
  }
  .tabBar('首页')

  TabContent() {
    Text('分类内容')
  }
  .tabBar('分类')

  TabContent() {
    Text('我的内容')
  }
  .tabBar('我的')
}
.scrollable(false)
.barWidth('100%')
.barHeight(56)
.onChange((index: number) => {
  console.info('切换到Tab: ' + index)
})

6.2 Navigation - 导航组件

提供页面路由和导航能力。

Navigation() {
  // 页面内容
}
.title('页面标题')
.mode(NavigationMode.Stack)
.titleMode(NavigationTitleMode.Mini)

6.3 NavRouter - 路由导航

用于页面间的路由跳转。

NavRouter() {
  // 源页面
  Column() {
    Text('点击跳转')
  }

  // 目标页面
  Column() {
    Text('目标页面')
  }
}

---

七、弹窗组件

7.1 AlertDialog - 警告弹窗

显示提示信息或确认操作。

AlertDialog.show({
  title: '提示',
  message: '确定要删除吗？',
  primaryButton: {
    value: '取消',
    action: () => {
      console.info('取消')
    }
  },
  secondaryButton: {
    value: '确定',
    fontColor: Color.Red,
    action: () => {
      console.info('确定')
    }
  }
})

7.2 CustomDialog - 自定义弹窗

完全自定义弹窗内容和样式。

@CustomDialog
struct MyDialog {
  controller: CustomDialogController = new CustomDialogController({
    builder: MyDialog(),
    cancel: () => { console.info('关闭') },
    autoCancel: true,
    alignment: DialogAlignment.Center
  })

  build() {
    Column({ space: 12 }) {
      Text('自定义弹窗')
      Button('关闭')
        .onClick(() => {
          this.controller.close()
        })
    }
    .padding(24)
  }
}

7.3 Popup - 气泡弹窗

在组件附近显示气泡提示。

Text('长按查看')
  .bindPopup(this.showPopup, {
    popup: Column() {
      Text('这是气泡内容')
    },
    placement: Placement.Bottom,
    mask: true,
    onStateChange: (e) => {
      this.showPopup = e.isVisible
    }
  })

---

八、菜单组件

8.1 Menu + MenuItem - 菜单组件

创建上下文菜单或下拉菜单。

Button('更多操作')
  .bindContextMenu(this.showMenu, ContextMenuType.LongPress, {
    builder: Column() {
      MenuItem({ content: '复制', labelInfo: 'Ctrl+C' })
        .onClick(() => { console.info('复制') })
      MenuItem({ content: '粘贴', labelInfo: 'Ctrl+V' })
        .onClick(() => { console.info('粘贴') })
      MenuItem({ content: '删除' })
        .onClick(() => { console.info('删除') })
    }
  })

---

九、组件速查表

组件名	功能	常用属性	适用场景
Text	文本展示	fontSize, fontColor, maxLines	标题、正文、提示文字
Image	图片展示	src, objectFit, borderRadius	头像、图标、背景图
Button	按钮交互	type, backgroundColor	提交、确认、触发操作
TextInput	单行输入	placeholder, type, maxLength	用户名、密码、搜索框
TextArea	多行输入	placeholder, maxLength, autoHeight	评论、描述、备注
Progress	进度展示	value, type, color	下载进度、任务完成度
LoadingProgress	加载状态	color	数据加载中
Column	纵向布局	space, justifyContent	表单、卡片内容
Row	横向布局	space, alignItems	标题栏、操作按钮
Stack	层叠布局	alignContent	角标、水印、遮罩
Flex	弹性布局	direction, wrap, justifyContent	流式标签、自适应布局
Grid	网格布局	columnsTemplate, rowsTemplate	宫格、九宫格
RelativeContainer	相对布局	alignRules	复杂相对定位
Scroll	滚动容器	scrollable, scrollBar	长内容滚动
List	列表容器	space, divider	消息列表、设置列表
Toggle	开关	type, isOn	设置开关
Slider	滑动条	value, min, max	音量、亮度调节
Radio	单选框	value, group	性别、选项选择
Checkbox	复选框	name, select	多选标签、协议勾选
Select	下拉选择	selected, value	城市、分类选择
DatePicker	日期选择	start, end, selected	生日、预约日期
TimePicker	时间选择	selected	闹钟、会议时间
Video	视频播放	src, autoPlay, controls	视频播放器
XComponent	自绘组件	type, libraryname	游戏、相机预览
Tabs	页签切换	barPosition, scrollable	底部导航、顶部切换
TabContent	页签内容	tabBar	配合Tabs使用
Navigation	导航容器	title, mode	页面导航框架
NavRouter	路由导航	-	页面跳转
AlertDialog	警告弹窗	title, message, primaryButton	确认、提示
CustomDialog	自定义弹窗	builder, alignment	复杂交互弹窗
Popup	气泡弹窗	popup, placement	提示、快捷操作
Menu	菜单容器	builder	右键菜单、长按菜单
MenuItem	菜单项	content, labelInfo	配合Menu使用

---

十、总结

本文系统梳理了ArkUI框架的42个内置组件，按照功能分为8大类：

1. 基础组件（7个）：文本、图片、按钮、输入框、进度条等基础UI元素

2. 容器组件（8个）：各种布局容器，解决页面排列问题

3. 表单组件（7个）：数据采集和状态切换的交互组件

4. 媒体组件（2个）：视频播放和自绘内容渲染

5. 导航组件（4个）：页面路由和导航框架

6. 弹窗组件（3个）：各类弹窗提示交互

7. 菜单组件（2个）：上下文菜单和下拉菜单

掌握这些组件的最佳方式是：

• 先通读本文，建立整体认知

• 遇到具体需求时，查阅对应组件的详细文档

• 动手实践，在DevEco Studio中多写多练

建议收藏本文，在开发过程中随时查阅，告别"组件不认识"的尴尬。

---

下期预告：第12篇将深入讲解ArkUI的自定义组件开发，教你如何封装可复用的业务组件。