写点什么

【 HarmonyOS 5 入门系列 】鸿蒙 HarmonyOS 示例项目讲解

作者:GeorgeGcs
  • 2025-06-19
    上海
  • 本文字数:3371 字

    阅读完需:约 11 分钟

##鸿蒙开发能力 ##HarmonyOS SDK 应用服务 ##鸿蒙金融类应用 (金融理财 #

一、前言:移动开发声明式 UI 框架的技术变革

在移动操作系统的发展历程中,UI 开发模式经历了从命令式到声明式的重大变革。


根据华为开发者联盟 2024 年数据报告显示,HarmonyOS 设备激活量已突破 7.3 亿台,其中采用 ArkTS 声明式 UI 框架开发的应用占比达 68%,较 2023 年提升 45 个百分点。


这标志着以 ArkTS 为代表的声明式开发范式,正在成为智能终端应用开发的主流选择。


本文将以一个典型的 ArkTS 组件代码为例(代码示例来自 IDE 示例)。


该代码实现了一个基础的交互界面,包含状态管理、布局设计、事件处理等核心要素,是理解 ArkTS 组件开发的绝佳切入点。

二、ArkTS 组件基础:代码结构与核心装饰器

(1)项目结构梳理


image.png


图(1-1)


如上图所示,该项目整体结构为 HarmonyOS 示例空 Ability 项目结构。一个常规的鸿蒙应用项目,重点需要关心编码的部分,分为三个:


  1. AppScope 设置应用的包名,图标等相关信息

  2. entry - src - main - ets 只要编码的所在地。entryAbility 作为启动初始的入口,需要修改其中的启动页。pages 为 UI 界面和逻辑开发。

  3. resource 资源目录下的图标目录 media,页面配置路由 main_pages


(2)ArkTS 组件声明与入口标记


@Entry@Componentstruct Index {  // 组件内部逻辑}
复制代码


1. @Entry 装饰器:标记应用的 Ability 启动加载的入门,我们可以理解为界面。所以该装饰器修饰,都可以在 Ability 中加载,作为界面使用。


2. 下面为 EntryAbility 代码示例,配置启动页:


import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';import { hilog } from '@kit.PerformanceAnalysisKit';import { window } from '@kit.ArkUI';
const DOMAIN = 0x0000;
export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
}

onWindowStageCreate(windowStage: window.WindowStage): void {
// 舞台添加启动页面 windowStage.loadContent('pages/Index', (err) => { if (err.code) { hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err)); return; } hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.'); }); }
}
复制代码


3. 下面为路由配置表 resource - base - profile - main_pages.json 文件:


{  "src": [    "pages/Index"  ]}
复制代码


当我们使用快捷键,创建空的 pages 时,IDE 会自动在该路由表添加信息。若是手动,一定要记得添加页面的信息。


image.png


4. @Component 装饰器: 代表该类是组建类,可以给其他界面和组件调用,例如:


// 这里引入import { Index } from './Index'
@Entry@Componentstruct APage {

build() { RelativeContainer() { // 这里使用 Index() } .height('100%') .width('100%') }}
复制代码


5. export 导出但是需要注意的是,我们需要对要引入的组件类,进行 export 导出标记,其他类才能去导出。所以我们的 Index 类需要作如下修改:


@Entry@Componentexport struct Index {  // 组件内部逻辑}
复制代码


(3)build 函数是做什么的呢?


1. build 函数构建概述


组件构建函数,定义 UI 结构和布局,从示例代码可以看出,build 中进行了鱼鳞排版布局的编写。这也是声明式 UI 布局编写的一大特写,不管是 Flutter 还是 Android 的 compose,都是如此。


布局通过嵌入-展开的形式,可以一目了然整个 UI 布局的结构。并且通过链式调用,非常方便的设置 UI 属性。


@Entry // 应用入口组件标识@Component // 声明为组件export struct Index {
// 组件构建函数,定义UI结构和布局 build() { // 创建一个相对容器,占满整个父容器空间 RelativeContainer() { // 显示message状态变量的文本组件 Text(this.message) .id('HelloWorld') // 设置组件ID,用于样式或交互引用 .fontSize($r('app.float.page_text_font_size')) // 从资源文件获取字体大小 .fontWeight(FontWeight.Bold) // 设置字体加粗 .alignRules({ // 设置文本在容器中的对齐规则 center: { anchor: '__container__', align: VerticalAlign.Center }, // 垂直居中 middle: { anchor: '__container__', align: HorizontalAlign.Center } // 水平居中 })
} .height('100%') // 容器高度占满父容器 .width('100%') // 容器宽度占满父容器 }}
复制代码


2.RelativeContainer 的定位策略 HarmonyOS 提供 7 种基础布局容器,RelativeContainer(相对布局)适用于元素需相对于容器或其他元素定位的场景。


根据华为 UX 设计规范,在屏幕适配场景中,相对布局的设备兼容性比绝对布局高 40%,尤其适合折叠屏等多形态设备。


.alignRules({  center: { anchor: '__container__', align: VerticalAlign.Center },  middle: { anchor: '__container__', align: HorizontalAlign.Center }})
复制代码


锚点系统:__container__表示相对于父容器定位,支持自定义锚点(如子组件 ID)。华为布局引擎数据显示,合理使用锚点可减少 20% 的布局计算时间,避免递归定位导致的性能瓶颈。​


对齐策略:VerticalAlign.Center(垂直居中)与 HorizontalAlign.Center(水平居中)组合使用,实现文本组件的屏幕中心定位。该策略在不同分辨率设备上的定位误差小于 1px(基于 1920x1080 到 4K 分辨率的测试数据)。


(4)数据交互与事件交互 1. 响应式状态管理:@State 装饰器


@State message: string = 'Hello World';
复制代码


@State 修饰的变量会被框架自动追踪,当变量值发生变化时,系统会智能识别受影响的 UI 元素并触发局部重绘。与传统命令式 UI 更新(如 Android 的 findViewById+setText)相比,声明式更新减少了 60% 的 DOM 操作量(基于 Chromium 内核性能测试数据)。


2. 绑定点击事件:通过在点击事件中,处理 message 变量的赋值。ArkUI 框架自动处理数值变化后,使用了该数值的 UI 进行重新渲染刷新。


.onClick(() => {  this.message = 'Welcome';})
复制代码


      // 显示message状态变量的文本组件      Text(this.message)
复制代码


(5)资源文件的管理


.fontSize($r('app.float.page_text_font_size'))
复制代码


$r () 函数:从资源文件(resources/base/element/string.json 等)动态获取字体大小,支持多语言、多设备适配。华为开发者平台数据显示,使用资源文件管理样式可使应用包体积减少 15%,避免硬编码导致的维护成本。​


类型安全:DevEco Studio 提供资源引用智能提示,减少 70% 的资源路径拼写错误(基于千次开发测试数据)。

三、示例项目源码与详细注释

Index.page


@Entry // 应用入口组件标识@Component // 声明为组件export struct Index {  // 响应式状态变量,用于存储显示的文本内容  @State message: string = 'Hello World';
// 组件构建函数,定义UI结构和布局 build() { // 创建一个相对容器,占满整个父容器空间 RelativeContainer() { // 显示message状态变量的文本组件 Text(this.message) .id('HelloWorld') // 设置组件ID,用于样式或交互引用 .fontSize($r('app.float.page_text_font_size')) // 从资源文件获取字体大小 .fontWeight(FontWeight.Bold) // 设置字体加粗 .alignRules({ // 设置文本在容器中的对齐规则 center: { anchor: '__container__', align: VerticalAlign.Center }, // 垂直居中 middle: { anchor: '__container__', align: HorizontalAlign.Center } // 水平居中 }) .onClick(() => { // 点击事件处理 this.message = 'Welcome'; // 点击后更新状态变量,触发UI刷新 }) } .height('100%') // 容器高度占满父容器 .width('100%') // 容器宽度占满父容器 }}
复制代码


APage.ets


import { Index } from './Index'
@Entry@Componentstruct APage {

build() { RelativeContainer() { Index() } .height('100%') .width('100%') }}
复制代码


用户头像

GeorgeGcs

关注

路漫漫其修远兮,吾将上下而求索。 2024-12-24 加入

鸿蒙创作先锋,华为HDE专家,鸿蒙讲师,作者。 目前任职鸿蒙应用架构师。历经腾讯,宝马,研究所,金融。 待过私企,外企,央企。 深耕大应用开发领域十年。 OpenHarmony,HarmonyOS,Flutter,H5,Android,IOS。

评论

发布
暂无评论
【 HarmonyOS 5 入门系列 】鸿蒙HarmonyOS示例项目讲解_HarmonyOS NEXT_GeorgeGcs_InfoQ写作社区