HarmonyOS ArkTS 开发示例项目

本项目是 HarmonyOS 应用开发的教学示例，涵盖了 ArkTS 语言和 ArkUI 框架的核心知识点。

项目概述

这是一个基于 HarmonyOS API 12 (5.0.0) 的 Stage 模型应用，通过多个独立页面演示了 ArkUI 开发中的常用技术和最佳实践。

核心知识点

1. 条件渲染与循环渲染

• IfPage: if/else 条件渲染的使用
• ForEachPage: ForEach 列表循环渲染，动态生成组件

2. 样式复用机制

• @Styles 装饰器 (StylesPage)

  • 全局样式函数定义
  • 组件内样式函数定义
  • 样式的复用和组合

• @Extend 装饰器 (ExtendPage)

  • 扩展内置组件的样式
  • 支持参数化样式定义
  • 可包含事件处理逻辑

3. 自定义构建函数

• @Builder 装饰器 (BuilderPage1, BuilderPage2)
  • 全局 Builder 函数
  • 组件内 Builder 函数
  • 按值传递 vs 按引用传递
  • UI 结构的抽取和复用

4. 插槽机制

• @BuilderParam 装饰器 (BuilderParam1, BuilderParam2, BuilderParam3)
  • 组件插槽的定义和使用
  • 尾随闭包语法（单插槽场景）
  • 构造参数传递（多插槽场景）
  • 默认内容的设置

5. 组件化开发

• 自定义组件封装

  • HmNavBar: 导航栏组件
  • HmCommentItem: 评论项组件
  • HmReplyInput: 回复输入组件

• 组件拆分

  • HomeHeader: 页面头部
  • HomeMain: 页面主体
  • HomeFooter: 页面底部

6. 数据模型

• TypeScript 接口和类 (models/index.ets)
  • 数据接口定义 (ReplyItem)
  • 数据模型类 (ReplyItemModel)
  • 类型安全的数据处理

7. 路由导航

• 页面跳转 (Index.ets)
  • router.pushUrl() 页面导航
  • 路由参数传递
  • 页面导航列表实现

8. 系统能力调用

• promptAction (ExtendPage, StylesPage)
  • Toast 提示框
  • 异常处理和设备兼容性

9. 资源引用

• 系统资源: $r('sys.media.xxx') 引用系统内置图标
• 应用资源: $r('app.media.xxx') 引用应用资源

项目结构

entry/src/main/ets/
├── components/          # 自定义组件
│   ├── HmNavBar.ets
│   ├── HmCommentItem.ets
│   └── HmReplyInput.ets
├── views/              # 视图模块
│   ├── HomeHeader.ets
│   ├── HomeMain.ets
│   └── HomeFooter.ets
├── models/             # 数据模型
│   └── index.ets
├── pages/              # 页面
│   ├── Index.ets       # 导航首页
│   ├── IfPage.ets
│   ├── ForEachPage.ets
│   ├── HomePage.ets
│   ├── StylesPage.ets
│   ├── ExtendPage.ets
│   ├── BuilderPage1.ets
│   ├── BuilderPage2.ets
│   ├── BuilderParam1.ets
│   ├── BuilderParam2.ets
│   ├── BuilderParam3.ets
│   └── CommentPage.ets
└── entryability/       # 应用入口
    └── EntryAbility.ets

技术栈

• 开发语言: ArkTS (TypeScript 的超集)
• UI 框架: ArkUI (声明式 UI)
• 开发模式: Stage 模型
• API 版本: API 12 (HarmonyOS 5.0.0)
• 开发工具: DevEco Studio

运行环境

• compatibleSdkVersion: 5.0.0(12)
• runtimeOS: HarmonyOS

快速开始

1. 使用 DevEco Studio 打开项目
2. 连接 HarmonyOS 设备或启动模拟器
3. 点击运行按钮，选择目标设备
4. 应用启动后，从导航页面选择要查看的示例

学习路径建议

1. 基础语法: IfPage → ForEachPage
2. 样式系统: StylesPage → ExtendPage
3. UI 复用: BuilderPage1 → BuilderPage2
4. 组件插槽: BuilderParam1 → BuilderParam2 → BuilderParam3
5. 综合应用: HomePage → CommentPage

注意事项

• 多个 @BuilderParam 的组件不能使用尾随闭包语法，需通过构造参数传递
• @Styles 只能定义通用属性，不能包含事件
• @Extend 只能扩展内置组件，可以包含事件处理
• 系统 API 调用建议添加异常处理（try-catch）

相关文档

• HarmonyOS 官方文档
• ArkTS 语言规范