文章目录前言一、UIAbility 是什么二、EntryAbility 源码解析三、生命周期调用顺序3.1 应用冷启动首次打开3.2 应用退到后台3.3 应用从后台回到前台3.4 应用被销毁四、onCreate应用初始化4.1 Want 是什么4.2 setColorMode强制亮色模式五、onWindowStageCreate最重要的初始化时机5.1 设置全屏沉浸式5.2 读取安全区域高度5.3 监听安全区域变化5.4 加载主页面六、onForeground 和 onBackground七、生命周期方法对比Android vs HarmonyOS总结前言每个 HarmonyOS 应用都有一个心脏叫做UIAbility。应用的启动、进入前台、退到后台、被销毁全都通过 UIAbility 的生命周期回调来管理。项目里的EntryAbility.ets就是这个心脏的实现。这篇文章我们把它从头到尾解析清楚让你彻底搞懂 HarmonyOS 应用是怎么活起来的。项目预览一、UIAbility 是什么在 HarmonyOS 中Ability是应用的基本功能单元分两种类型作用UIAbility有 UI 界面的功能单元我们用这个ExtensionAbility后台服务、输入法等无 UI 的扩展功能每个 HarmonyOS 应用至少有一个UIAbility。对于简单的应用通常只有一个EntryAbility复杂的应用可能有多个 Ability类似 Android 的多 Activity但用法上更像多个窗口。一句话UIAbility 是应用窗口的管理者页面Page在 UIAbility 内部运行。二、EntryAbility 源码解析完整的EntryAbility.ets// entry/src/main/ets/entryability/EntryAbility.etsimport{AbilityConstant,ConfigurationConstant,UIAbility,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{window}fromkit.ArkUI;import{BusinessError}fromkit.BasicServicesKit;constDOMAIN0x0000;exportdefaultclassEntryAbilityextendsUIAbility{// ① 应用创建时调用只调用一次onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 强制设置亮色模式this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);hilog.info(DOMAIN,testTag,%{public}s,Ability onCreate);}// ② 应用销毁时调用onDestroy():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onDestroy);}// ③ 窗口创建时调用做初始化配置onWindowStageCreate(windowStage:window.WindowStage):void{// 设置全屏沉浸式布局letwindowClass:window.WindowwindowStage.getMainWindowSync();windowClass.setWindowLayoutFullScreen(true).then((){hilog.info(0x0000,testTag,Succeeded in setting the window layout to full-screen mode.);});// 获取并存储安全区域高度letavoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);AppStorage.setOrCreate(bottomRectHeight,avoidArea.bottomRect.height);avoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);AppStorage.setOrCreate(topRectHeight,avoidArea.topRect.height);// 监听安全区域变化windowClass.on(avoidAreaChange,(data){if(data.typewindow.AvoidAreaType.TYPE_SYSTEM){AppStorage.setOrCreate(topRectHeight,data.area.topRect.height);}elseif(data.typewindow.AvoidAreaType.TYPE_NAVIGATION_INDICATOR){AppStorage.setOrCreate(bottomRectHeight,data.area.bottomRect.height);}});// 加载主页面windowStage.loadContent(pages/MainPage,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load the content. Cause: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,testTag,Succeeded in loading the content.);});}// ④ 窗口销毁时调用onWindowStageDestroy():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onWindowStageDestroy);}// ⑤ 应用进入前台时调用onForeground():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onForeground);}// ⑥ 应用切到后台时调用onBackground():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onBackground);}}三、生命周期调用顺序3.1 应用冷启动首次打开onCreate(want, launchParam) ↓ onWindowStageCreate(windowStage) ↓ [页面加载loadContent(pages/MainPage)] ↓ onForeground() ↓ [用户使用应用...]3.2 应用退到后台[用户按Home键或切换应用] ↓ onBackground() ↓ [应用在后台存活但可能被系统回收]3.3 应用从后台回到前台[用户重新打开应用] ↓ onForeground() ↓ [应用恢复不再调用 onCreate]3.4 应用被销毁[系统回收 或 用户强制退出] ↓ onWindowStageDestroy() ↓ onDestroy()四、onCreate应用初始化onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 设置应用颜色模式为亮色this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);hilog.info(DOMAIN,testTag,%{public}s,Ability onCreate);}4.1 Want 是什么Want是 HarmonyOS 中用于描述启动意图的对象类似 Android 的Intent。它包含interfaceWant{bundleName?:string;// 应用包名abilityName?:string;// 目标 Ability 名称parameters?:Recordstring,Object;// 携带的自定义参数action?:string;// 动作类型// ... 更多字段}通过want.parameters可以接收其他应用或系统传递过来的数据。4.2 setColorMode强制亮色模式this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);这一行把整个应用强制设置为亮色模式即使用户手机开了暗色模式这个 App 也不跟着变暗。为什么这样做因为地图类应用通常有精心设计的配色方案贸然跟随系统暗色模式可能导致 UI 不协调。这是一个主动的设计决策。五、onWindowStageCreate最重要的初始化时机onWindowStageCreate是整个生命周期中最繁忙的方法承担三项核心工作5.1 设置全屏沉浸式letwindowClass:window.WindowwindowStage.getMainWindowSync();windowClass.setWindowLayoutFullScreen(true);setWindowLayoutFullScreen(true)让 UI 内容延伸到状态栏和导航栏下方实现沉浸式效果。这也意味着我们需要手动处理安全区域避免内容被遮挡。5.2 读取安全区域高度// 导航栏高度letavoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);letbottomRectHeightavoidArea.bottomRect.height;AppStorage.setOrCreate(bottomRectHeight,bottomRectHeight);// 状态栏高度avoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);lettopRectHeightavoidArea.topRect.height;AppStorage.setOrCreate(topRectHeight,topRectHeight);获取顶部状态栏和底部导航条的实际高度单位px存入全局AppStorage后续页面用StorageProp取出来用于给内容区域设置对应的 padding避免内容被系统 UI 遮挡。5.3 监听安全区域变化windowClass.on(avoidAreaChange,(data){if(data.typewindow.AvoidAreaType.TYPE_SYSTEM){AppStorage.setOrCreate(topRectHeight,data.area.topRect.height);}elseif(data.typewindow.AvoidAreaType.TYPE_NAVIGATION_INDICATOR){AppStorage.setOrCreate(bottomRectHeight,data.area.bottomRect.height);}});为什么要监听变化因为折叠屏展开/折叠时状态栏高度会变横竖屏切换时安全区域也会变键盘弹出时导航条高度可能变化用监听器动态更新保证AppStorage里的值始终是最新的。5.4 加载主页面windowStage.loadContent(pages/MainPage,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load the content. Cause: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,testTag,Succeeded in loading the content.);});这是最后一步告诉窗口加载pages/MainPage这个页面作为主页面。pages/MainPage对应的是entry/src/main/ets/pages/MainPage.ets不需要写.ets后缀。六、onForeground 和 onBackground这两个回调一般用于onForeground():void{// 应用进入前台时执行// 常见场景// - 恢复网络连接// - 重新开始定位// - 刷新数据}onBackground():void{// 应用切到后台时执行// 常见场景// - 暂停视频播放// - 保存未完成的状态// - 停止耗电操作}这个项目的onForeground和onBackground只有日志因为项目功能简单地图和定位的生命周期由系统自动管理。七、生命周期方法对比Android vs HarmonyOSHarmonyOSUIAbilityAndroidActivity触发时机onCreateonCreate首次创建onWindowStageCreateonStart/onResume之间窗口就绪onForegroundonResume进入前台onBackgroundonPause/onStop进入后台onWindowStageDestroyonStop窗口销毁onDestroyonDestroy彻底销毁总结EntryAbility.ets做了三件重要的事onCreate锁定亮色模式onWindowStageCreate设置全屏沉浸、读取并监听安全区域高度、加载主页面onForeground/onBackground处理前后台切换本项目只记日志整个应用的启动流程是onCreate→onWindowStageCreate设置全屏、存安全区域高度、加载页面→onForeground用户开始使用。下一篇详细讲沉浸式全屏布局——为什么要全屏怎么处理状态栏遮挡问题。
【HarmonyOS实战】 UIAbility生命周期：应用是怎么“活“起来的？
文章目录前言一、UIAbility 是什么二、EntryAbility 源码解析三、生命周期调用顺序3.1 应用冷启动首次打开3.2 应用退到后台3.3 应用从后台回到前台3.4 应用被销毁四、onCreate应用初始化4.1 Want 是什么4.2 setColorMode强制亮色模式五、onWindowStageCreate最重要的初始化时机5.1 设置全屏沉浸式5.2 读取安全区域高度5.3 监听安全区域变化5.4 加载主页面六、onForeground 和 onBackground七、生命周期方法对比Android vs HarmonyOS总结前言每个 HarmonyOS 应用都有一个心脏叫做UIAbility。应用的启动、进入前台、退到后台、被销毁全都通过 UIAbility 的生命周期回调来管理。项目里的EntryAbility.ets就是这个心脏的实现。这篇文章我们把它从头到尾解析清楚让你彻底搞懂 HarmonyOS 应用是怎么活起来的。项目预览一、UIAbility 是什么在 HarmonyOS 中Ability是应用的基本功能单元分两种类型作用UIAbility有 UI 界面的功能单元我们用这个ExtensionAbility后台服务、输入法等无 UI 的扩展功能每个 HarmonyOS 应用至少有一个UIAbility。对于简单的应用通常只有一个EntryAbility复杂的应用可能有多个 Ability类似 Android 的多 Activity但用法上更像多个窗口。一句话UIAbility 是应用窗口的管理者页面Page在 UIAbility 内部运行。二、EntryAbility 源码解析完整的EntryAbility.ets// entry/src/main/ets/entryability/EntryAbility.etsimport{AbilityConstant,ConfigurationConstant,UIAbility,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{window}fromkit.ArkUI;import{BusinessError}fromkit.BasicServicesKit;constDOMAIN0x0000;exportdefaultclassEntryAbilityextendsUIAbility{// ① 应用创建时调用只调用一次onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 强制设置亮色模式this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);hilog.info(DOMAIN,testTag,%{public}s,Ability onCreate);}// ② 应用销毁时调用onDestroy():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onDestroy);}// ③ 窗口创建时调用做初始化配置onWindowStageCreate(windowStage:window.WindowStage):void{// 设置全屏沉浸式布局letwindowClass:window.WindowwindowStage.getMainWindowSync();windowClass.setWindowLayoutFullScreen(true).then((){hilog.info(0x0000,testTag,Succeeded in setting the window layout to full-screen mode.);});// 获取并存储安全区域高度letavoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);AppStorage.setOrCreate(bottomRectHeight,avoidArea.bottomRect.height);avoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);AppStorage.setOrCreate(topRectHeight,avoidArea.topRect.height);// 监听安全区域变化windowClass.on(avoidAreaChange,(data){if(data.typewindow.AvoidAreaType.TYPE_SYSTEM){AppStorage.setOrCreate(topRectHeight,data.area.topRect.height);}elseif(data.typewindow.AvoidAreaType.TYPE_NAVIGATION_INDICATOR){AppStorage.setOrCreate(bottomRectHeight,data.area.bottomRect.height);}});// 加载主页面windowStage.loadContent(pages/MainPage,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load the content. Cause: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,testTag,Succeeded in loading the content.);});}// ④ 窗口销毁时调用onWindowStageDestroy():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onWindowStageDestroy);}// ⑤ 应用进入前台时调用onForeground():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onForeground);}// ⑥ 应用切到后台时调用onBackground():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onBackground);}}三、生命周期调用顺序3.1 应用冷启动首次打开onCreate(want, launchParam) ↓ onWindowStageCreate(windowStage) ↓ [页面加载loadContent(pages/MainPage)] ↓ onForeground() ↓ [用户使用应用...]3.2 应用退到后台[用户按Home键或切换应用] ↓ onBackground() ↓ [应用在后台存活但可能被系统回收]3.3 应用从后台回到前台[用户重新打开应用] ↓ onForeground() ↓ [应用恢复不再调用 onCreate]3.4 应用被销毁[系统回收 或 用户强制退出] ↓ onWindowStageDestroy() ↓ onDestroy()四、onCreate应用初始化onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 设置应用颜色模式为亮色this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);hilog.info(DOMAIN,testTag,%{public}s,Ability onCreate);}4.1 Want 是什么Want是 HarmonyOS 中用于描述启动意图的对象类似 Android 的Intent。它包含interfaceWant{bundleName?:string;// 应用包名abilityName?:string;// 目标 Ability 名称parameters?:Recordstring,Object;// 携带的自定义参数action?:string;// 动作类型// ... 更多字段}通过want.parameters可以接收其他应用或系统传递过来的数据。4.2 setColorMode强制亮色模式this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);这一行把整个应用强制设置为亮色模式即使用户手机开了暗色模式这个 App 也不跟着变暗。为什么这样做因为地图类应用通常有精心设计的配色方案贸然跟随系统暗色模式可能导致 UI 不协调。这是一个主动的设计决策。五、onWindowStageCreate最重要的初始化时机onWindowStageCreate是整个生命周期中最繁忙的方法承担三项核心工作5.1 设置全屏沉浸式letwindowClass:window.WindowwindowStage.getMainWindowSync();windowClass.setWindowLayoutFullScreen(true);setWindowLayoutFullScreen(true)让 UI 内容延伸到状态栏和导航栏下方实现沉浸式效果。这也意味着我们需要手动处理安全区域避免内容被遮挡。5.2 读取安全区域高度// 导航栏高度letavoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);letbottomRectHeightavoidArea.bottomRect.height;AppStorage.setOrCreate(bottomRectHeight,bottomRectHeight);// 状态栏高度avoidAreawindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);lettopRectHeightavoidArea.topRect.height;AppStorage.setOrCreate(topRectHeight,topRectHeight);获取顶部状态栏和底部导航条的实际高度单位px存入全局AppStorage后续页面用StorageProp取出来用于给内容区域设置对应的 padding避免内容被系统 UI 遮挡。5.3 监听安全区域变化windowClass.on(avoidAreaChange,(data){if(data.typewindow.AvoidAreaType.TYPE_SYSTEM){AppStorage.setOrCreate(topRectHeight,data.area.topRect.height);}elseif(data.typewindow.AvoidAreaType.TYPE_NAVIGATION_INDICATOR){AppStorage.setOrCreate(bottomRectHeight,data.area.bottomRect.height);}});为什么要监听变化因为折叠屏展开/折叠时状态栏高度会变横竖屏切换时安全区域也会变键盘弹出时导航条高度可能变化用监听器动态更新保证AppStorage里的值始终是最新的。5.4 加载主页面windowStage.loadContent(pages/MainPage,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load the content. Cause: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,testTag,Succeeded in loading the content.);});这是最后一步告诉窗口加载pages/MainPage这个页面作为主页面。pages/MainPage对应的是entry/src/main/ets/pages/MainPage.ets不需要写.ets后缀。六、onForeground 和 onBackground这两个回调一般用于onForeground():void{// 应用进入前台时执行// 常见场景// - 恢复网络连接// - 重新开始定位// - 刷新数据}onBackground():void{// 应用切到后台时执行// 常见场景// - 暂停视频播放// - 保存未完成的状态// - 停止耗电操作}这个项目的onForeground和onBackground只有日志因为项目功能简单地图和定位的生命周期由系统自动管理。七、生命周期方法对比Android vs HarmonyOSHarmonyOSUIAbilityAndroidActivity触发时机onCreateonCreate首次创建onWindowStageCreateonStart/onResume之间窗口就绪onForegroundonResume进入前台onBackgroundonPause/onStop进入后台onWindowStageDestroyonStop窗口销毁onDestroyonDestroy彻底销毁总结EntryAbility.ets做了三件重要的事onCreate锁定亮色模式onWindowStageCreate设置全屏沉浸、读取并监听安全区域高度、加载主页面onForeground/onBackground处理前后台切换本项目只记日志整个应用的启动流程是onCreate→onWindowStageCreate设置全屏、存安全区域高度、加载页面→onForeground用户开始使用。下一篇详细讲沉浸式全屏布局——为什么要全屏怎么处理状态栏遮挡问题。
