前言对于刚开始学习 HarmonyOS 的开发者来说官方 Sample示例项目是最好的学习资料。很多开发者都有这样的困惑学了 ArkTS 语法不知道如何写完整项目会写页面不知道如何组织工程DataPreferences、Router、Ability 不会结合使用想学习官方最佳实践却不知道从哪个 Sample 开始事实上HarmonyOS 官方提供了数百个 Sample。本文将带你系统解析 HarmonyOS 示例项目。包括✅ 示例项目分类✅ 官方 Sample 下载✅ 工程结构✅ 页面组织方式✅ 路由管理✅ 状态管理✅ 数据持久化✅ 网络请求✅ 页面生命周期✅ 常用组件✅ 实战案例拆解真正做到看懂官方 Sample自己也能写出完整 HarmonyOS 项目。一、HarmonyOS Sample 是什么官方 Sample 可以理解成官方提供的最佳实践项目。里面包含ArkUIArkTSAnimationRouterPreferencesDatabaseAbilityStage Model网络请求AI能力分布式能力系统API几乎所有开发能力都有对应 Demo。二、官方 Sample 获取方式主要有三个来源1、HarmonyOS 官方 Sample Center里面几百个案例。分类包括UI媒体网络AI安全CameraArkWebLocationBluetoothNFCDistributed2、DevEco StudioFile↓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:number0更新this.countUI 自动刷新。八、组件拆分官方 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()十四、资源管理resourcesbase element media profile rawfile图片media字符串string.json颜色color.json尺寸float.json十五、常用组件 Sample官方示例最多TextButtonImageListGridSwiperTabsScrollNavigationSearchRefreshProgressSliderDatePickerCalendar十六、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.scale1.2 }二十一、手势 SampleTapGesture LongPressGesture PanGesture PinchGesture例如Gesture( TapGesture() .onAction((){ }) )二十二、弹窗 Sample包括AlertDialog CustomDialog Toast Loading例如AlertDialog.show()二十三、媒体 Sample包含图片视频音频相机扫码录音播放器二十四、系统能力官方 Sample 覆盖蓝牙NFC定位联系人电话通知剪贴板振动传感器WiFi二十五、ArkWeb Sample包含Web()支持网页JS BridgeCookie下载上传缓存二十六、数据库 Sample包括PreferencesRelationalStoreRdbDataShare二十七、AI SampleHarmonyOS 5 已提供大量 AI 示例例如AI 文本能力图像识别智能推荐大模型接入Agent 能力二十八、最佳实践总结官方 Sample 共同特点单一职责一个页面只做一件事UI 与业务逻辑分离合理拆分组件数据模型统一管理工具类统一封装使用状态驱动 UI资源统一管理生命周期管理规范网络请求统一封装注重代码可维护性学习路线建议如果你是 HarmonyOS 5 初学者建议按照以下顺序学习官方 Sample学习阶段推荐内容学习目标第一阶段ArkUI 基础组件Text、Button、Image、List熟悉声明式 UI 开发第二阶段页面路由、Navigation、生命周期掌握页面组织与导航第三阶段State、Prop、Link等状态管理理解响应式开发模式第四阶段Preferences、数据库、网络请求掌握数据管理第五阶段动画、手势、自定义组件提升交互体验第六阶段相机、定位、通知、ArkWeb 等系统能力学习系统 API 调用第七阶段综合官方示例项目独立开发完整应用总结HarmonyOS 官方 Sample 不只是 Demo更是一套完整的开发最佳实践。从工程结构、页面组织、状态管理、路由导航到系统能力调用都体现了 HarmonyOS 5 推荐的开发方式。
