前言

对于刚开始学习 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：

学习阶段	推荐内容	学习目标
第一阶段	ArkUI 基础组件（Text、Button、Image、List）	熟悉声明式 UI 开发
第二阶段	页面路由、Navigation、生命周期	掌握页面组织与导航
第三阶段	@State、@Prop、@Link 等状态管理	理解响应式开发模式
第四阶段	Preferences、数据库、网络请求	掌握数据管理
第五阶段	动画、手势、自定义组件	提升交互体验
第六阶段	相机、定位、通知、ArkWeb 等系统能力	学习系统 API 调用
第七阶段	综合官方示例项目	独立开发完整应用

---

总结

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