《鸿蒙原生应用开发实战》第一篇项目框架搭建与路由体系前言从零开始构建一个鸿蒙原生应用第一步就是搭好脚手架。本文将详细讲解如何基于 HarmonyOS Stage 模型从创建项目到完成路由体系的完整搭建。我们以「光遇·心境」App 为例这是一个沉浸式光感场景探索应用。本文将涵盖Stage 模型与 FA 模型的区别项目目录结构与配置文件Ability 的注册与生命周期沉浸式窗口配置状态栏/导航栏透明页面路由注册与跳转体系一、Stage 模型 vs FA 模型HarmonyOS 从 API 9 开始推荐使用 Stage 模型相比旧的 FA 模型Stage 模型有以下优势对比维度Stage 模型FA 模型组件化一个应用包含多个 Module以 Ability 为核心生命周期UIAbility ExtensionAbility 明确分工生命周期耦合较重窗口管理WindowStage 统一管理每个 Ability 各自管理后台任务ExtensionAbility 专职后台与前台 Ability 混在一起本项目配置build-profile.json5中指定了 stage 模式{ apiType: stageMode, buildOption: { resOptions: { copyCodeResource: { enable: false } } } }二、项目目录结构解析一个标准的 Stage 模型项目结构如下MyApplication/ ├── AppScope/ # 全局应用配置 │ ├── app.json5 # 应用级配置bundleName、版本号等 │ └── resources/ │ ├── base/element/ # 全局资源string.json │ └── media/ # 应用图标 ├── entry/ # 主模块 │ ├── src/main/ │ │ ├── ets/ │ │ │ ├── entryability/ # Ability 入口 │ │ │ ├── entrybackupability/ # 备份扩展能力 │ │ │ ├── model/ # 数据模型层 │ │ │ └── pages/ # 页面层 │ │ ├── module.json5 # 模块配置 │ │ └── resources/ # 模块资源 │ └── build-profile.json5 # 模块构建配置 ├── build-profile.json5 # 项目级构建配置 └── hvigor/ # 构建工具配置AppScope/app.json5 —— 应用的身份证{ app: { bundleName: com.example.myapplication, // 应用唯一标识 vendor: example, versionCode: 1000000, // 版本号整数 versionName: 1.0.0, // 展示给用户的版本 icon: $media:layered_image, // 应用图标 label: $string:app_name // 应用名称 } }⚠️注意事项app_name只需在AppScope中定义一次不可在entry模块的string.json中重复定义否则编译会报资源重复错误。三、Ability 注册与生命周期EntryAbility —— 应用的大门// entryability/EntryAbility.etsimport{AbilityConstant,UIAbility,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassEntryAbilityextendsUIAbility{// 1. Ability 创建时调用 —— 适合做全局初始化onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 设置颜色模式跟随系统this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);}// 2. WindowStage 创建 —— 这是最关键的生命周期方法onWindowStageCreate(windowStage:window.WindowStage):void{// 这里配置沉浸式窗口// ...// 加载首页windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,testTag,加载失败: %{public}s,JSON.stringify(err));}});}// 3. 前后台切换onForeground():void{/* 应用进入前台 */}onBackground():void{/* 应用进入后台 */}// 4. 销毁onDestroy():void{/* 释放资源 */}}module.json5 —— Ability 的注册地{ module: { name: entry, type: entry, // entry主模块, feature特性模块 mainElement: EntryAbility, // 入口 Ability deviceTypes: [phone], abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, exported: true, // 是否暴露给外部应用调用 skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] // 桌面图标启动 } ] } ], // 扩展 Ability —— 这里我们注册了备份能力 extensionAbilities: [ { name: EntryBackupAbility, srcEntry: ./ets/entrybackupability/EntryBackupAbility.ets, type: backup, // 备份恢复类型 exported: false } ] } }四、沉浸式窗口 —— 打造全屏无边框体验作为光感场景应用沉浸式体验是核心。我们需要让内容延伸到状态栏和导航栏区域。// EntryAbility.ets —— onWindowStageCreate 中的关键配置onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.getMainWindow((err,wnd){// 1. 启用全屏布局状态栏和导航栏区域也可绘制内容wnd.setWindowLayoutFullScreen(true,(err1){// 2. 设置状态栏和导航栏透明wnd.setWindowSystemBarProperties({statusBarColor:#00000000,// 完全透明navigationBarColor:#00000000,// 完全透明isStatusBarLightIcon:true,// 白色图标适配深色背景isNavigationBarLightIcon:true// 白色图标});// 3. 窗口背景透明避免白块闪烁wnd.setWindowBackgroundColor(#00000000);});});}实现效果状态栏不再是黑条或白条而是完全透明页面的渐变背景从屏幕顶部开始渲染底部导航栏同样透明页面内容铺满全屏页面中需要预留状态栏高度的占位build(){Column(){// 状态栏占位5%高度的空行让内容不被状态栏遮挡Row().height(5%).width(100%)// 实际内容...Scroll(){/* ... */}}}五、页面路由注册体系路由表配置在main_pages.json中注册所有页面路由{src:[pages/Index,// 首页pages/ScenePage,// 场景探索列表页pages/DetailPage,// 场景详情页pages/FavPage,// 收藏页pages/ProfilePage// 个人中心页]}路由规范API 23 下路由的导入和使用有严格规范// ✅ 正确的导入方式importrouterfromohos.router;// ❌ 错误方式API 23 不导出此路径// import router from kit.AbilityKit;// 页面跳转携带参数router.pushUrl({url:pages/DetailPage,params:{sceneId:1}});// 页面返回router.back();// 接收参数constparamsrouter.getParams()asRecordstring,Object;constidparams[sceneId]asnumber;路由体系总览Index首页 ├── push → ScenePage场景列表可携带 category 参数 │ └── push → DetailPage场景详情携带 sceneId ├── push → DetailPage每日推荐直接进入 ├── push → FavPage收藏页 └── push → ProfilePage个人中心这种星型路由结构非常清晰所有子页面都可以通过router.back()返回首页用户体验一致。六、构建配置说明API 版本配置build-profile.json5{ products: [ { name: default, targetSdkVersion: 6.1.1(24), // 目标 SDK compatibleSdkVersion: 6.1.0(23), // 兼容的最低 SDK runtimeOS: HarmonyOS, buildOption: { strictMode: { caseSensitiveCheck: true, useNormalizedOHMUrl: true // ArkTS 严格模式 } } } ] }构建命令hvigorw--modemodule-pmoduleentrydefault-pproductdefault\-prequiredDeviceTypephone assembleHap\--analyzenormal--parallel--incremental--daemon七、常见踩坑记录坑1app_name重复定义现象编译报错 “duplicate resource”原因同时在 AppScope 和 entry 模块中定义了app_name解决app_name只在AppScope/resources/base/element/string.json中定义坑2router 导入路径错误现象运行时崩溃 “Cannot find module”原因API 23 不支持kit.AbilityKit导出的 router解决统一使用import router from ohos.router坑3沉浸式窗口出现白底闪烁现象启动时背景短暂变白原因startWindowBackground未设置为深色解决在module.json5中将startWindowBackground设为$color:start_window_background在我们项目中是#1a1a2e总结本篇我们完成了✅ 理解 Stage 模型的核心概念✅ 项目目录结构与配置文件解析✅ Ability 生命周期与注册✅ 沉浸式窗口配置实战✅ 页面路由注册与跳转体系✅ 构建配置与常见踩坑记录项目的路由体系是整个应用的骨架下一篇我们将深入 ArkTS 数据模型设计看看如何优雅地管理应用的状态和数据流。下一篇预告ArkTS 数据模型与状态管理 —— State 装饰器、AppStorage 全局存储、数据流设计模式