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

前言

对于刚开始学习 HarmonyOS 的开发者来说，官方 Sample（示例项目）是最好的学习资料。

很多开发者都有这样的困惑：

• 学了 ArkTS 语法，不知道如何写完整项目
• 会写页面，不知道如何组织工程
• DataPreferences、Router、Ability 不会结合使用
• 想学习官方最佳实践，却不知道从哪个 Sample 开始

事实上，HarmonyOS 官方提供了数百个 Sample。

本文将带你系统解析 HarmonyOS 示例项目。

包括：

✅ 示例项目分类

✅ 官方 Sample 下载

✅ 工程结构

✅ 页面组织方式

✅ 路由管理

✅ 状态管理

✅ 数据持久化

✅ 网络请求

✅ 页面生命周期

✅ 常用组件

✅ 实战案例拆解

真正做到：

看懂官方 Sample，自己也能写出完整 HarmonyOS 项目。

一、HarmonyOS Sample 是什么？

官方 Sample 可以理解成：

官方提供的最佳实践项目。

里面包含：

• ArkUI
• ArkTS
• Animation
• Router
• Preferences
• Database
• Ability
• Stage Model
• 网络请求
• AI能力
• 分布式能力
• 系统API

几乎所有开发能力都有对应 Demo。

二、官方 Sample 获取方式

主要有三个来源：

1、HarmonyOS 官方 Sample Center

里面几百个案例。

分类包括：

• UI
• 媒体
• 网络
• AI
• 安全
• Camera
• ArkWeb
• Location
• Bluetooth
• NFC
• Distributed

2、DevEco Studio

File

↓

New Project

↓

Sample

可以直接下载官方示例。

3、GitCode / Gitee

官方同步维护大量 Sample。

例如：

entry ├── pages ├── resources ├── ets ├── utils ├── model ├── common

三、Sample 工程目录解析

一个典型项目：

MyApplication AppScope │ entry │ ├── src │ ├── main │ │ │ ├── ets │ │ │ ├── pages │ │ │ ├── resources │ │ │ ├── module.json5 │ ├── hvigor ├── build-profile.json5

其中：

AppScope

整个应用公共配置。

entry

默认 Module。

resources

资源文件。

pages

页面。

ets

业务代码。

四、页面目录

官方 Sample 都会这样组织：

pages Index.ets Login.ets Home.ets User.ets Setting.ets

每一个页面都是：

@Component struct Home { build() { } }

页面十分独立。

五、Router 路由管理

官方 Sample 基本都采用：

router.pushUrl() router.replaceUrl() router.back()

例如：

Button("登录") .onClick(()=>{ router.pushUrl({ url:"pages/Home" }) })

返回：

router.back()

替换：

router.replaceUrl()

六、页面生命周期

HarmonyOS 页面：

aboutToAppear() build() aboutToDisappear()

例如：

aboutToAppear(){ console.info("页面出现") }

页面退出：

aboutToDisappear(){ console.info("页面销毁") }

这是官方推荐写法。

七、状态管理

Sample 中大量使用：

@State @Prop @Link @Provide @Consume @Observed @ObjectLink

例如：

@State count:number=0

更新：

this.count++

UI 自动刷新。

八、组件拆分

官方 Sample 很少一个页面几千行。

一般拆：

components TitleBar.ets UserCard.ets BottomBar.ets Loading.ets

页面：

Column(){ TitleBar() UserCard() BottomBar() }

非常清晰。

九、数据模型

通常：

model User.ts Goods.ts Order.ts

例如：

export class User{ id:number name:string avatar:string }

避免写：

let data:any

十、工具类

utils DateUtil.ts LogUtil.ts ToastUtil.ts PermissionUtil.ts

统一封装。

例如：

ToastUtil.show()

十一、网络请求

官方 Sample 多采用：

@ohos.net.http

流程：

创建 Request

↓

GET

↓

POST

↓

JSON

↓

关闭连接

示例：

http.createHttp()

请求：

request( url )

结束：

destroy()

十二、Preferences 数据存储

官方推荐：

Preferences

保存：

put() flush()

读取：

get()

例如：

preferences.put("token","123")

读取：

preferences.get("token")

十三、页面通信

常见方式：

State

↓

Router Param

↓

EventHub

↓

Provide

↓

Consume

例如：

router.pushUrl({ params:{ id:100 } })

接收：

router.getParams()

十四、资源管理

resources：

base element media profile rawfile

图片：

media

字符串：

string.json

颜色：

color.json

尺寸：

float.json

十五、常用组件 Sample

官方示例最多：

Text

Button

Image

List

Grid

Swiper

Tabs

Scroll

Navigation

Search

Refresh

Progress

Slider

DatePicker

Calendar

十六、List 示例解析

例如：

List(){ ForEach( this.list, (item)=>{ ListItem(){ Text(item.name) } } ) }

这是官方最经典写法。

十七、Grid 示例

Grid(){ ForEach( data, (item)=>{ GridItem(){ Image(item.icon) } } ) }

适合：

首页

菜单

分类

十八、Tabs 示例

Tabs(){ TabContent(){ Home() } TabContent(){ Mine() } }

很多 Sample 都采用这种结构。

十九、Navigation 示例

Navigation(){ NavDestination(){ Home() } }

HarmonyOS 5 推荐 Navigation 体系。

二十、动画 Sample

包括：

animateTo() scale() translate() rotate() opacity()

例如：

animateTo({ duration:500 }) { this.scale=1.2 }

二十一、手势 Sample

TapGesture LongPressGesture PanGesture PinchGesture

例如：

Gesture( TapGesture() .onAction(()=>{ }) )

二十二、弹窗 Sample

包括：

AlertDialog CustomDialog Toast Loading

例如：

AlertDialog.show()

二十三、媒体 Sample

包含：

图片

视频

音频

相机

扫码

录音

播放器

二十四、系统能力

官方 Sample 覆盖：

蓝牙

NFC

定位

联系人

电话

通知

剪贴板

振动

传感器

WiFi

二十五、ArkWeb Sample

包含：

Web()

支持：

网页

JS Bridge

Cookie

下载

上传

缓存

二十六、数据库 Sample

包括：

Preferences

RelationalStore

Rdb

DataShare

二十七、AI Sample

HarmonyOS 5 已提供大量 AI 示例，例如：

• AI 文本能力
• 图像识别
• 智能推荐
• 大模型接入
• Agent 能力

二十八、最佳实践总结

官方 Sample 共同特点：

1. 单一职责，一个页面只做一件事
2. UI 与业务逻辑分离
3. 合理拆分组件
4. 数据模型统一管理
5. 工具类统一封装
6. 使用状态驱动 UI
7. 资源统一管理
8. 生命周期管理规范
9. 网络请求统一封装
10. 注重代码可维护性

学习路线建议

如果你是 HarmonyOS 5 初学者，建议按照以下顺序学习官方 Sample：

总结

HarmonyOS 官方 Sample 不只是 Demo，更是一套完整的开发最佳实践。从工程结构、页面组织、状态管理、路由导航到系统能力调用，都体现了 HarmonyOS 5 推荐的开发方式。