HarmonyOS NEXT快速开发实战：从环境搭建到Todo App

鸿蒙专家

HarmonyOS NEXT 是华为面向全场景智能设备的下一代操作系统，其核心开发语言 ArkTS 基于 TypeScript 进化而来，专为声明式 UI 框架 ArkUI 设计。开发者只需描述“界面长什么样”，框架自动处理渲染更新，大幅提升开发效率。本文从环境搭建开始，逐步演示基础组件、页面路由、状态管理，并提供一个完整的待办事项应用（Todo App）示例，帮助你快速上手。

一、开发环境搭建
1. 下载 DevEco Studio：访问华为开发者联盟官网，获取最新版本的 IDE。
2. 安装 Node.js：建议 v18+ 版本，用于构建脚本。
3. 配置 SDK：首次启动时选择“Full SDK”安装，包含 HarmonyOS SDK 和工具链。
4. 开启设备调试：通过 USB 连接或模拟器进行真机/模拟调试。

二、创建新项目
在 DevEco Studio 中，选择 File → New → Create Project → Empty Ability。项目创建向导会自动生成以下核心结构：

2. entry/
3. ├── src/main/
4. │ ├── ets/
5. │ │ ├── entryability/  # 应用入口
6. │ │ │ └── EntryAbility.ets
7. │ │ ├── pages/  # 页面文件
8. │ │ │ └── Index.ets  # 主页面
9. │ │ └── App.ets  # 全局应用配置
10. │ ├── module.json5  # 模块配置
11. │ └── resources/  # 资源目录

复制代码

其中 entryability 管理应用生命周期，pages 定义 UI 页面，App.ets 用于全局配置。

三、常用 UI 组件快速上手
ArkUI 提供丰富的声明式组件，以下是最常用的基础组件。
3.1 文本与按钮

2. // Index.ets - 基础组件使用示例
3. import hilog from '@ohos.hilog';
5. @Component
6. struct Index {
7.   @State message: string = 'Hello HarmonyOS';
9.   build() {
10.     Column({ space: 20 }) {
11.       Text(this.message)
12.         .fontSize(32)
13.         .fontWeight(FontWeight.Bold)
14.         .fontColor('#1A1A1A')
16.       Button('点击我')
17.         .width(200)
18.         .height(50)
19.         .fontSize(18)
20.         .backgroundColor('#007DFF')
21.         .borderRadius(25)
22.         .onClick(() => {
23.           this.message = '欢迎来到鸿蒙世界！';
24.           hilog.info(0, 'Demo', 'Button clicked');
25.         })
26.     }
27.     .width('100%')
28.     .height('100%')
29.     .justifyContent(FlexAlign.Center)
30.     .alignItems(HorizontalAlign.Center)
31.   }
32. }

复制代码

3.2 列表与循环渲染

2. // 列表渲染 - 使用 ForEach 遍历数据
3. @Component
4. struct ListDemo {
5.   @State fruits: string[] = ['苹果', '香蕉', '橙子', '葡萄'];
7.   build() {
8.     Column({ space: 10 }) {
9.       Text('水果列表')
10.         .fontSize(24)
11.         .fontWeight(FontWeight.Medium)
13.       List({ space: 10 }) {
14.         ForEach(this.fruits, (fruit: string, index: number) => {
15.           ListItem() {
16.             Row() {
17.               Text(`${index + 1}.`)
18.                 .fontSize(16)
19.                 .fontColor('#666666')
20.                 .width(40)
21.               Text(fruit)
22.                 .fontSize(18)
23.                 .fontWeight(FontWeight.Medium)
24.             }
25.             .width('100%')
26.             .padding(12)
27.             .backgroundColor('#F5F5F5')
28.             .borderRadius(8)
29.           }
30.         })
31.       }
32.       .width('90%')
33.       .height('60%')
34.     }
35.     .width('100%')
36.     .height('100%')
37.     .padding(20)
38.   }
39. }

复制代码

四、页面路由与导航
HarmonyOS NEXT 推荐使用 Navigation 组件实现页面导航。通过 NavPathStack 管理页面栈，使用 pushPathByName 跳转并传递参数，pop 返回上一页。需要在 module.json5 中配置路由映射，并在 resources/base/profile/router_map.json 中定义路由表。详细代码示例如下：

2. // src/main/ets/pages/MainPage.ets
3. @Entry
4. @Component
5. struct MainPage {
6.   @Provide('pageStack') pageStack: NavPathStack = new NavPathStack();
8.   build() {
9.     Navigation(this.pageStack) {
10.       Column({ space: 20 }) {
11.         Text('主页面')
12.           .fontSize(32)
13.           .fontWeight(FontWeight.Bold)
14.         Button('跳转到详情页')
15.           .onClick(() => {
16.             this.pageStack.pushPathByName('DetailPage', {
17.               'title': '详情标题',
18.               'id': 1001
19.             });
20.           })
21.       }
22.       .width('100%')
23.       .height('100%')
24.       .justifyContent(FlexAlign.Center)
25.     }
26.     .title('应用首页')
27.     .navDestination(this.routerBuilder)
28.   }
30.   @Builder
31.   routerBuilder(name: string, param: Object) {
32.     if (name === 'DetailPage') {
33.       DetailPage({ param: param as Record<string, number> });
34.     }
35.   }
36. }
38. @Component
39. struct DetailPage {
40.   @Consume('pageStack') pageStack: NavPathStack;
41.   @Param param: Record<string, number> = {};
43.   build() {
44.     NavDestination() {
45.       Column({ space: 20 }) {
46.         Text(`接收到的ID: ${this.param['id']}`)
47.           .fontSize(24)
48.         Button('返回')
49.           .onClick(() => {
50.             this.pageStack.pop();
51.           })
52.       }
53.       .width('100%')
54.       .height('100%')
55.       .justifyContent(FlexAlign.Center)
56.     }
57.     .title('详情页')
58.   }
59. }

复制代码

路由配置文件示例：

2. {
3.   "srcEntry": "./ets/entryability/EntryAbility.ets",
4.   "routerMap": "$profile:router_map"
5. }
6. // resources/base/profile/router_map.json
7. {
8.   "routerMap": [
9.     {
10.       "name": "MainPage",
11.       "pageSourceFile": "./ets/pages/MainPage.ets",
12.       "components": {
13.         "DetailPage": "./ets/pages/DetailPage.ets"
14.       }
15.     }
16.   ]
17. }

复制代码

五、数据管理快速方案
ArkUI 的状态管理通过装饰器实现。核心装饰器包括：@State（组件私有状态）、@Prop（单向接收父组件数据）、@Link（双向绑定）、@Provide/@Consume（跨级状态共享）。当状态变化时，框架自动触发渲染更新。以下是一个完整的状态管理示例：

2. @Entry
3. @Component
4. struct StateDemo {
5.   @State count: number = 0;
6.   @State inputText: string = '';
7.   @Provide('appTheme') theme: string = 'light';
9.   build() {
10.     Column({ space: 20 }) {
11.       Text(`计数: ${this.count}`).fontSize(28)
12.       Row({ space: 10 }) {
13.         Button('+1').onClick(() => this.count++)
14.         Button('-1').onClick(() => this.count--)
15.         Button('重置').onClick(() => this.count = 0)
16.       }
17.       TextInput({ placeholder: '请输入文本' })
18.         .width('80%')
19.         .height(50)
20.         .onChange((value: string) => { this.inputText = value; })
21.       Text(`输入的内容: ${this.inputText}`).fontSize(18).fontColor('#666666')
22.       ChildComponent()
23.     }
24.     .width('100%')
25.     .height('100%')
26.     .padding(20)
27.   }
28. }
30. @Component
31. struct ChildComponent {
32.   @Prop message: string = '来自父组件的消息';
33.   @Consume('appTheme') theme: string;
35.   build() {
36.     Column({ space: 10 }) {
37.       Text(this.message).fontSize(16)
38.       Text(`当前主题: ${this.theme}`).fontSize(14).fontColor('#888888')
39.     }
40.     .padding(15)
41.     .backgroundColor('#F0F0F0')
42.     .borderRadius(10)
43.   }
44. }

复制代码

六、快速开发实战示例 - Todo App
下面是一个完整的待办事项应用，涵盖列表渲染、状态管理、增删操作：

2. @Observed
3. class TodoItem {
4.   id: number;
5.   title: string;
6.   completed: boolean;
8.   constructor(id: number, title: string) {
9.     this.id = id;
10.     this.title = title;
11.     this.completed = false;
12.   }
13. }
15. @Entry
16. @Component
17. struct TodoApp {
18.   @State todoList: TodoItem[] = [];
19.   @State newTodoTitle: string = '';
21.   addTodo() {
22.     if (this.newTodoTitle.trim() === '') return;
23.     const newItem = new TodoItem(Date.now(), this.newTodoTitle.trim());
24.     this.todoList.push(newItem);
25.     this.newTodoTitle = '';
26.   }
28.   toggleTodo(item: TodoItem) {
29.     item.completed = !item.completed;
30.     this.todoList = [...this.todoList];
31.   }
33.   deleteTodo(id: number) {
34.     const index = this.todoList.findIndex(item => item.id === id);
35.     if (index !== -1) {
36.       this.todoList.splice(index, 1);
37.       this.todoList = [...this.todoList];
38.     }
39.   }
41.   build() {
42.     Column({ space: 16 }) {
43.       Text('我的待办').fontSize(28).fontWeight(FontWeight.Bold).width('100%').textAlign(TextAlign.Start)
44.       Row({ space: 10 }) {
45.         TextInput({ placeholder: '添加新待办...', text: this.newTodoTitle })
46.           .layoutWeight(1).height(48)
47.           .onChange((value: string) => { this.newTodoTitle = value; })
48.         Button('添加').height(48).fontSize(16).onClick(() => this.addTodo())
49.       }.width('100%')
50.       List({ space: 12 }) {
51.         ForEach(this.todoList, (item: TodoItem) => {
52.           ListItem() {
53.             Row({ space: 12 }) {
54.               Checkbox().select(item.completed).onChange((checked: boolean) => { this.toggleTodo(item); })
55.               Text(item.title)
56.                 .fontSize(18)
57.                 .decoration({ type: item.completed ? TextDecorationType.LineThrough : TextDecorationType.None })
58.                 .fontColor(item.completed ? '#999999' : '#333333')
59.                 .layoutWeight(1)
60.               Button('删除').fontSize(14).fontColor('#FF4444').backgroundColor('transparent').onClick(() => this.deleteTodo(item.id))
61.             }.width('100%').padding(16).backgroundColor('#FFFFFF').borderRadius(12).shadow({ radius: 4, color: '#10000000', offsetX: 2, offsetY: 2 })
62.           }
63.         })
64.       }.width('100%').layoutWeight(1)
65.       Text(`共 ${this.todoList.length} 项，已完成 ${this.todoList.filter(i => i.completed).length} 项`)
66.         .fontSize(14).fontColor('#666666').width('100%').textAlign(TextAlign.Center)
67.     }.width('100%').height('100%').padding(20).backgroundColor('#F5F5F5')
68.   }
69. }

复制代码

七、开发效率提升技巧
- 热重载（Hot Reload）：DevEco Studio 支持保存即生效的热重载功能，修改 .ets 文件并保存后，模拟器/设备会即时刷新，状态数据默认保留，极大加速 UI 调试循环。
- 预览器：右键点击 .ets 文件 → Preview 打开预览面板，支持多设备预览（手机、平板、智慧屏），实时查看不同屏幕尺寸下的布局效果。
- 代码片段（Code Snippets）：DevEco Studio 内置常用代码模板，可快速生成组件模板。
- 快速调试技巧：使用 hilog 进行日志输出，带标签便于过滤；也可在预览器中使用 console.info 调试。

2. import hilog from '@ohos.hilog';
3. hilog.info(0xFF00, 'MyApp', 'User logged in: %{public}s', userName);
4. hilog.error(0xFF00, 'MyApp', 'Network error: %{public}d', errorCode);
5. console.info('State changed:', JSON.stringify(this.state));

复制代码

总结
鸿蒙应用开发的核心在于掌握 ArkTS 声明式语法 + 状态驱动渲染 + Navigation 路由系统。环境搭建仅需 DevEco Studio + Full SDK；项目结构清晰，UI 开发使用 Column/Row 布局 + 基础组件 + ForEach 列表渲染；状态管理按需选用 @State/@Prop/@Link/@Provide/@Consume；页面导航通过 Navigation + NavPathStack 实现；同时善用热重载、预览器和代码片段可大幅提升开发效率。

热心网友5

感谢楼主的详细教程！从环境搭建到 Todo App 的完整流程很清晰，特别是 ArkTS 声明式 UI 和 ForEach 列表渲染的示例，对刚接触 HarmonyOS NEXT 的开发者非常友好。请问在页面路由部分，如果使用 Navigation + NavPathStack，多个页面之间如何共享全局状态（比如用户登录信息）呢？另外，有没有推荐的 ArkUI 组件库或最佳实践，用于快速构建复杂界面？再次感谢分享！