鸿蒙原生项目实战（一）：项目初始化与工程架构解析

鸿蒙原生项目实战一项目初始化与工程架构解析本系列基于 HarmonyOS NEXT 6.1.1API 23平台以一款名为「习惯大师」的完整应用为实例从零到一带你掌握鸿蒙原生开发全流程。一、前言在正式开始编码前我们需要先搭建好鸿蒙原生开发环境。本文默认你已经完成了以下准备工作安装了DevEco Studio NEXT推荐 5.0 版本配置了 HarmonyOS SDK本文基于 API 23/24即 HarmonyOS 6.1.x注册了华为开发者账号并完成了签名配置二、创建项目2.1 新建项目打开 DevEco Studio点击Create Project选择Empty Ability模板填写项目名称MyApplicationBundle namecom.example.myapplicationCompatible SDK6.1.0(23)语言ArkTS2.2 项目结构概览创建完成后我们来看项目的整体目录结构MyApplication/ ├── AppScope/ # 应用级配置与资源 │ ├── app.json5 # 全局应用配置 │ └── resources/ # 应用级资源图标、字符串 ├── entry/ # 主模块entry类型 │ ├── src/main/ets/ # ArkTS源码目录 │ │ ├── entryability/ # Ability生命周期 │ │ ├── entrybackupability/ # 备份扩展能力 │ │ ├── model/ # 数据模型与业务逻辑 │ │ └── pages/ # 页面组件 │ ├── src/main/resources/ # 模块级资源 │ └── build-profile.json5 # 模块构建配置 ├── hvigor/ # 构建工具配置 ├── oh_modules/ # 依赖模块 ├── build-profile.json5 # 应用级构建配置 ├── hvigorfile.ts # 构建入口脚本 └── oh-package.json5 # 包管理配置三、核心配置解析3.1 应用级配置AppScope/app.json5{app:{bundleName:com.example.myapplication,vendor:example,versionCode:1000000,versionName:1.0.0,buildVersion:1,icon:$media:layered_image,label:$string:app_name}}关键字段说明字段说明注意点bundleName应用唯一标识发布后不可更改versionCode内部版本号递增的正整数versionName用户可见版本语义化版本号icon应用图标使用$media:资源引用label应用名称使用$string:资源引用3.2 模块级配置entry/build-profile.json5{apiType:stageMode,buildOption:{strictMode:{caseSensitiveCheck:true,useNormalizedOHMUrl:true}}}这里启用了大小写敏感检查和规范化 OHM URL这是 HarmonyOS 6.1 后的推荐实践。3.3 模块声明module.json5{module:{name:entry,type:entry,mainElement:EntryAbility,deviceTypes:[phone],pages:$profile:main_pages,abilities:[{name:EntryAbility,srcEntry:./ets/entryability/EntryAbility.ets,exported:true,skills:[{entities:[entity.system.home],actions:[ohos.want.action.home]}]}],extensionAbilities:[{name:EntryBackupAbility,srcEntry:./ets/entrybackupability/EntryBackupAbility.ets,type:backup,exported:false}]}}重点理解type: entry标识这是主入口模块一个应用只有一个skills配置系统意图Want过滤entity.system.homeohos.want.action.home表示这是一个桌面启动应用extensionAbilities扩展能力这里注册了一个备份恢复扩展3.4 页面路由配置resources/base/profile/main_pages.json{src:[pages/Index,pages/AddHabit,pages/HabitDetail,pages/Statistics,pages/Settings]}所有页面必须在此注册这是 ArkTS 路由系统的要求。我们的「习惯大师」共有 5 个页面页面功能Index首页今日进度 习惯列表 打卡AddHabit添加新习惯HabitDetail习惯详情 日历视图Statistics统计分析 趋势图Settings设置与数据管理四、构建配置体系4.1 应用级 build-profile.json5{app:{products:[{name:default,signingConfig:default,targetSdkVersion:6.1.1(24),compatibleSdkVersion:6.1.0(23),runtimeOS:HarmonyOS}],buildModeSet:[{name:debug},{name:release}]},modules:[{name:entry,srcPath:./entry,targets:[{name:default,applyToProducts:[default]}]}]}4.2 Hvigor 构建配置{ modelVersion: 6.1.1, execution: { daemon: true, // 启用守护进程编译 incremental: true, // 增量编译 parallel: true, // 并行编译 typeCheck: false // 关闭类型检查加快构建 } }⚠️ 开发阶段建议typeCheck: false以加速热重载发布前再开启。五、资源管理机制5.1 color 资源{color:[{name:primary,value:#6C5CE7},{name:primary_dark,value:#5A4BD1},{name:bg_page,value:#F0F4F8},{name:card_bg,value:#FFFFFF},{name:text_primary,value:#2D3436},{name:text_secondary,value:#636E72},{name:completed,value:#00B894},{name:incomplete,value:#DFE6E9}]}通过$r(app.color.primary)引用方便全局统一换肤。5.2 深色主题适配resources/dark/element/color.json{color:[{name:start_window_background,value:#000000}]}鸿蒙原生支持自动匹配深色模式资源无需代码判断。只需在dark/目录下定义同名资源即可覆盖。六、Ability 生命周期EntryAbility.etsimport{AbilityConstant,UIAbility,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;import{HabitManager}from../model/DataManager;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{HabitManager.init(this.context);// 初始化数据管理器}onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,testTag,Failed: %{public}s,JSON.stringify(err));}});}}生命周期要点onCreate应用启动时调用在此完成全局初始化如数据管理器onWindowStageCreate窗口创建后加载首屏页面onForeground/onBackground前后台切换回调七、实践要点总结命名规范$r()资源引用是 ArkTS 推荐的国际化/主题化方案硬编码颜色值应尽量避免module.json5 中的 skills要启动应用必须配置entity.system.homeohos.want.action.home页面注册新增页面后必须在main_pages.json注册否则路由会失败增量编译Hvigor 默认启用增量编译首次构建较慢后续热重载极快八、下篇预告下一篇我们将深入数据模型与持久化层设计内容包括ArkTS 枚举与接口定义Preferences 轻量级数据库的使用Manager 单例模式设计复杂数据结构的序列化/反序列化 下一篇数据模型与持久化层设计本文所有代码片段均来自真实鸿蒙 NEXT 项目「习惯大师」你可以对照源码阅读效果更佳。