鸿蒙原生开发手记：徒步迹 - ArkUI 声明式UI基础组件

学习 ArkUI 核心组件，构建"徒步迹"的用户界面基础

一、前言

ArkUI 是鸿蒙原生应用的声明式 UI 框架，采用类似 SwiftUI 和 Jetpack Compose 的声明式编程范式。开发者只需描述 UI 的最终状态，框架自动处理状态变化时的界面更新。

本文将系统介绍 ArkUI 的基础组件，包括布局容器、文本、图片、按钮、输入框等，并结合"徒步迹"的实际场景演示用法。

二、组件基础结构

2.1 组件树

ArkUI 中每个页面由组件树构成，组件通过链式调用设置属性：

@Entry@Componentstruct ExamplePage{build(){Column(){// 父组件：列布局Text('Hello')// 子组件1：文本.fontSize(20)// 链式属性设置.fontColor('#333');Button('点击')// 子组件2：按钮.onClick(()=>{});}.width('100%')// 父组件属性.padding(16);}}

2.2 组件分类

ArkUI 组件按功能可分为：

• 布局组件：Column、Row、Stack、Flex、Grid、List
• 基础组件：Text、Image、Button、TextInput、Slider
• 展示组件：Progress、LoadingProgress、Badge、Panel
• 交互组件：Dialog、Menu、Picker、DatePicker
• 导航组件：Navigation、Tab、NavRouter

三、布局容器

3.1 Column - 垂直布局

Column 是最常用的垂直排列布局，子组件从上到下排列：

// 徒步迹 - 个人中心头部布局Column(){// 头像Image($r('app.media.avatar')).width(80).height(80).borderRadius(40);// 用户名Text('徒步爱好者').fontSize(20).fontWeight(FontWeight.Bold).fontColor($r('app.color.text_primary'));// 统计信息Text('累计徒步 86km').fontSize(14).fontColor($r('app.color.text_secondary'));}.width('100%').alignItems(HorizontalAlign.Center)// 居中对齐.padding(24);

3.2 Row - 水平布局

Row 用于水平排列子组件：

// 徒步迹 - 今日概览统计行Row(){this.StatItem('🏃','8,642','步数');this.StatItem('📏','5.2','距离');this.StatItem('🔥','320','卡路里');}.width('100%').justifyContent(FlexAlign.SpaceAround);// 均匀分布

3.3 Stack - 层叠布局

Stack 用于组件叠加（类似 CSS 的 position: absolute）：

// 徒步迹 - 路线卡片顶部区域Stack(){// 背景图片Image($r('app.media.route_bg')).width('100%').height(140).objectFit(ImageFit.Cover);// 难度标签，叠加在图片上Text('中等').fontSize(12).fontColor(Color.White).backgroundColor($r('app.color.warning_color')).padding({left:10,right:10,top:4,bottom:4}).borderRadius(10).position({top:8,right:8});// 绝对定位}.width('100%').height(140);

3.4 Flex - 弹性布局

Flex 提供了更灵活的布局控制：

Flex({direction:FlexDirection.Row,// 主轴方向wrap:FlexWrap.Wrap,// 是否换行justifyContent:FlexAlign.Center,// 主轴对齐alignItems:ItemAlign.Center,// 交叉轴对齐}){Text('标签1').padding(8).backgroundColor('#E8F5E9').borderRadius(4);Text('标签2').padding(8).backgroundColor('#E3F2FD').borderRadius(4);Text('标签3').padding(8).backgroundColor('#FFF3E0').borderRadius(4);}

四、基础组件

4.1 Text - 文本

ArkUI 中最常用的文本组件：

// 基本用法Text('徒步迹').fontSize(24)// 字号.fontWeight(FontWeight.Bold)// 加粗.fontColor($r('app.color.primary_color'));// 取色// 多行文本Text('这是一条风景优美的徒步路线，沿途经过森林和溪流').fontSize(14).fontColor($r('app.color.text_secondary')).maxLines(2)// 最多2行.textOverflow({overflow:TextOverflow.Ellipsis});// 溢出省略// 富文本（部分样式）Text(){Span('徒步')// 内联片段.fontSize(16).fontColor($r('app.color.primary_color'));Span('迹').fontSize(20).fontColor($r('app.color.accent_color'));}

4.2 Image - 图片

// 加载资源图片Image($r('app.media.app_icon')).width(100).height(100).borderRadius(16).objectFit(ImageFit.Cover);// 裁剪模式// 加载网络图片（需申请网络权限）Image('https://example.com/photo.jpg').width('100%').height(200).objectFit(ImageFit.Cover);

4.3 Button - 按钮

// 文本按钮Button('开始徒步').width(200).height(48).backgroundColor($r('app.color.primary_color')).borderRadius(24).fontColor(Color.White).fontSize(16).onClick(()=>{console.log('开始记录轨迹');});// 自定义内容按钮Button(){Row(){Image($r('app.media.app_icon')).width(18).height(18);Text('创建团队').fontSize(14).fontColor(Color.White);}.alignItems(HorizontalAlign.Center);}.width('90%').height(44).backgroundColor($r('app.color.primary_color')).borderRadius(22);

4.4 TextInput - 文本输入框

// 普通输入TextInput({placeholder:'请输入手机号'}).width('100%').height(48).backgroundColor('#F5F5F5').borderRadius(12).padding({left:16}).type(InputType.PhoneNumber)// 输入类型.maxLength(11)// 最大长度.onChange((value:string)=>{console.log(`输入:${value}`);});// 密码输入TextInput({placeholder:'请输入密码'}).width('100%').height(48).backgroundColor('#F5F5F5').borderRadius(12).padding({left:16}).type(InputType.Password)// 密码类型.showPasswordIcon(true);// 显示密码切换

五、列表组件

5.1 ForEach - 循环渲染

@Stateroutes:HikingRoute[]=[{id:1,name:'香山徒步'},{id:2,name:'奥森公园'},{id:3,name:'百望山'},];build(){Column(){ForEach(this.routes,(route:HikingRoute)=>{Text(route.name).fontSize(16).padding(12).width('100%');},(route:HikingRoute)=>route.id.toString());}}

5.2 List - 高效长列表

List(){ForEach(this.routes,(route:HikingRoute)=>{ListItem(){RouteCard({route:route});}},(route:HikingRoute)=>route.id.toString());}.divider({strokeWidth:1,color:'#EEE'})// 分割线.edgeEffect(EdgeEffect.Spring);// 弹性效果

六、修饰符与链式调用

ArkUI 采用链式调用来设置组件属性，这是最常用的编程模式：

// 单行链式Text('徒步迹').fontSize(20).fontColor('#4CAF50').fontWeight(FontWeight.Bold);// 多行链式（推荐，可读性更好）Text('徒步迹').fontSize(20).fontColor($r('app.color.primary_color')).fontWeight(FontWeight.Bold).margin({top:12,bottom:12}).padding({left:16,right:16}).backgroundColor('#F5F5F5').borderRadius(8).textAlign(TextAlign.Center).width('100%');

七、实战：徒步迹首页概览卡片

综合运用所学组件，实现"徒步迹"首页的今日概览卡片：

@Componentstruct TodayOverview{@Propsteps:number=0;@Propdistance:number=0;@Propcalories:number=0;build(){Column(){Text('今日概览').fontSize(16).fontWeight(FontWeight.Medium).width('100%');Row(){// 步数Column(){Text('🏃').fontSize(28);Text(`${this.steps}`).fontSize(22).fontWeight(FontWeight.Bold);Text('步').fontSize(12).fontColor('#999');}.alignItems(HorizontalAlign.Center).layoutWeight(1);// 距离Column(){Text('📏').fontSize(28);Text(`${this.distance.toFixed(1)}`).fontSize(22).fontWeight(FontWeight.Bold);Text('km').fontSize(12).fontColor('#999');}.alignItems(HorizontalAlign.Center).layoutWeight(1);// 卡路里Column(){Text('🔥').fontSize(28);Text(`${this.calories}`).fontSize(22).fontWeight(FontWeight.Bold);Text('kcal').fontSize(12).fontColor('#999');}.alignItems(HorizontalAlign.Center).layoutWeight(1);}.width('100%').margin({top:16}).padding(12);}.width('100%').padding(16).backgroundColor(Color.White).borderRadius(16);}}// 使用@Entry@Componentstruct HomePage{build(){Column(){TodayOverview({steps:8642,distance:5.2,calories:320});}.width('100%').height('100%').backgroundColor('#F5F5F5').padding(16);}}

这段代码在 App 中的实际效果，可以参考项目截图：

八、总结

本文介绍了 ArkUI 的核心基础组件，包括 Column、Row、Stack 布局容器，Text、Image、Button、TextInput 等基础组件，以及 ForEach、List 等列表组件。掌握这些组件后，你已经可以构建大部分应用界面。

下一篇文章我们将学习 Stage 模型和 UIAbility 的深入应用，理解鸿蒙应用的运行机制。

下一篇预告：鸿蒙原生开发手机：徒步迹 - Stage 模型与UIAbility详解

有问题欢迎在评论区交流探讨。