HarmonyOS 实战教程（二）：UIAbility 生命周期与全局初始化 —— 以「柚兔自测量表」为例

一、UIAbility 是什么UIAbility 是 HarmonyOS 中应用的运行载体类似于 Android 的 Activity 或 iOS 的 UIViewController但粒度更粗——一个应用通常只有一个 UIAbility。它负责管理应用的生命周期、窗口创建和资源调度。MeCharts 应用中定义了EntryAbility作为整个应用的入口import{AbilityConstant,UIAbility,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{window}fromkit.ArkUI;import{WindowUtil}from../util/WindowUtil;import{PageContext}from../util/PageContext;import{IBestORMInit}fromibestservices/ibest-orm;import{relationalStore}fromkit.ArkData;constDOMAIN0x0000;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(DOMAIN,testTag,%{public}s,Ability onCreate);}onDestroy():void{hilog.info(DOMAIN,testTag,%{public}s,Ability onDestroy);}onWindowStageCreate(windowStage:window.WindowStage):void{// 初始化 IBest-ORM 数据库IBestORMInit(this.context,{name:meChart.db,securityLevel:relationalStore.SecurityLevel.S1})// 注册断点监听响应式布局WindowUtil.registerBreakPoint(windowStage);// 请求全屏布局WindowUtil.requestFullScreen(windowStage,this.context);// 初始化全局导航上下文AppStorage.setOrCreate(pageContext,newPageContext());// 加载主页面windowStage.loadContent(pages/Index,(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);}}二、生命周期回调详解2.1 onCreateonCreate在 Ability 创建时调用整个生命周期只调用一次。适合做轻量级初始化如读取传入的 Want 参数。onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(DOMAIN,testTag,%{public}s,Ability onCreate);}注意不要在onCreate中做耗时操作否则会影响应用启动速度。2.2 onWindowStageCreate核心回调这是最重要的回调窗口阶段创建后触发。MeCharts 在此完成了三项关键初始化1数据库初始化IBestORMInit(this.context,{name:meChart.db,securityLevel:relationalStore.SecurityLevel.S1})使用ibestservices/ibest-orm三方库初始化本地数据库。SecurityLevel.S1表示低安全级别适合存储非敏感数据如测评分数记录。2窗口与断点注册WindowUtil.registerBreakPoint(windowStage);WindowUtil.requestFullScreen(windowStage,this.context);registerBreakPoint监听窗口尺寸变化实现响应式布局的断点切换requestFullScreen设置全屏布局模式实现沉浸式体验3全局状态初始化AppStorage.setOrCreate(pageContext,newPageContext());AppStorage是 HarmonyOS 提供的全局状态管理器类似于全局单例。PageContext封装了导航栈NavPathStack所有页面共享同一个导航上下文。2.3 onForeground / onBackgroundonForeground():void{// 应用回到前台}onBackground():void{// 应用退到后台}适合在此处理资源释放与恢复。例如AI 聊天页面在后台时可以暂停轮询请求。2.4 生命周期流程图应用启动 → onCreate → onWindowStageCreate → onForeground ↓ 应用切到后台 ← onBackground ← 应用运行中 → onForeground → 应用回到前台 ↓ 应用销毁 → onBackground → onWindowStageDestroy → onDestroy三、全局状态管理AppStorageHarmonyOS 提供了AppStorage作为应用级的状态管理中心MeCharts 中用它管理多个全局状态3.1 PageContext —— 全局导航exportclassPageContextimplementsIPageContext{privatereadonlypathStack:NavPathStack;privatereturnCallback?:(data?:object)void;constructor(){this.pathStacknewNavPathStack();}publicopenPage(data:RouterParam,animated:booleantrue):void{this.returnCallbackdata.onReturn;this.pathStack.pushPath({name:data.routerName,param:data.param,},animated);}publicpopPage(animated:booleantrue,returnData?:object):void{if(this.returnCallback){this.returnCallback(returnData);this.returnCallbackundefined;}this.pathStack.pop(animated);}publicgetnavPathStack():NavPathStack{returnthis.pathStack;}}PageContext封装了NavPathStack的操作提供了统一的页面导航接口。所有页面通过AppStorage获取同一个实例privatepageContext:PageContextAppStorage.get(pageContext)asPageContext;3.2 GlobalInfoModel —— 全局设备信息ObservedexportclassGlobalInfoModel{publiccurrentBreakpoint:BreakpointTypeEnumBreakpointTypeEnum.MD;publicnaviIndicatorHeight:number0;publicstatusBarHeight:number0;publicdecorHeight:number0;publicdeviceHeight:number0;publicdeviceWidth:number0;}这个模型存储了设备相关的全局信息包括当前断点、状态栏高度、导航条高度等。在WindowUtil中初始化并持续更新constglobalInfoModel:GlobalInfoModelAppStorage.get(GlobalInfoModel)||newGlobalInfoModel();globalInfoModel.statusBarHeightpx2vp(systemAvoidArea.topRect.height);globalInfoModel.naviIndicatorHeightpx2vp(bottomArea.bottomRect.height);AppStorage.setOrCreate(GlobalInfoModel,globalInfoModel);在组件中通过StorageProp装饰器监听变化StorageProp(GlobalInfoModel)globalInfoModel:GlobalInfoModelAppStorage.get(GlobalInfoModel)!;3.3 AppStorage 的两种访问方式装饰器用途是否驱动 UI 刷新StorageProp单向绑定组件内只读是StorageLink双向绑定组件内可修改是AppStorage.get/set命令式访问否需手动触发四、沉浸式窗口管理MeCharts 实现了沉浸式全屏体验核心逻辑在WindowUtil中4.1 设置全屏布局publicstaticrequestFullScreen(windowStage:window.WindowStage,context:Context):void{windowStage.getMainWindow((err:BusinessError,data:window.Window){constwindowClass:window.Windowdata;try{constpromise:PromisevoidwindowClass.setWindowLayoutFullScreen(true);promise.then((){Logger.info(TAG,Succeeded in setting the window layout to full-screen mode.);});WindowUtil.getDeviceSize(context);}catch{Logger.error(TAG,Failed to set the window layout to full-screen mode.);}});}setWindowLayoutFullScreen(true)将窗口内容延伸到状态栏和导航条区域实现沉浸式效果。4.2 获取安全区域信息全屏布局后需要手动处理安全区域的避让publicstaticregisterBreakPoint(windowStage:window.WindowStage){windowStage.getMainWindow((err:BusinessError,data:window.Window){constglobalInfoModel:GlobalInfoModelAppStorage.get(GlobalInfoModel)||newGlobalInfoModel();// 获取状态栏高度constsystemAvoidArea:window.AvoidAreadata.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);globalInfoModel.statusBarHeightpx2vp(systemAvoidArea.topRect.height);// 获取底部导航条高度constbottomArea:window.AvoidAreadata.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);globalInfoModel.naviIndicatorHeightpx2vp(bottomArea.bottomRect.height);AppStorage.setOrCreate(GlobalInfoModel,globalInfoModel);// 监听窗口尺寸变化data.on(windowSizeChange,()WindowUtil.onWindowSizeChange(data));// 监听安全区域变化data.on(avoidAreaChange,(avoidAreaOption){if(avoidAreaOption.typewindow.AvoidAreaType.TYPE_SYSTEM||avoidAreaOption.typewindow.AvoidAreaType.TYPE_NAVIGATION_INDICATOR){WindowUtil.setAvoidArea(avoidAreaOption.type,avoidAreaOption.area);}});});}这段代码做了三件事获取安全区域尺寸读取状态栏和导航条的高度存储到GlobalInfoModel监听窗口变化适配折叠屏等场景下的尺寸变化监听安全区域变化适配键盘弹起等动态场景4.3 在组件中使用安全区域TopBar 组件中使用statusBarHeight作为顶部 paddingComponentV2exportstruct TopBar{privateglobalInfoModel:GlobalInfoModelAppStorage.get(GlobalInfoModel)||newGlobalInfoModel();ParamstatusBarHeight:numberthis.globalInfoModel.statusBarHeightbuild(){RelativeContainer(){// ... 标题栏内容}.padding({top:this.statusBarHeight,// 避开状态栏bottom:20,left:12,right:12})}}五、小结本篇深入讲解了 UIAbility 的生命周期管理和全局初始化策略。MeCharts 在onWindowStageCreate中集中完成了数据库初始化、窗口配置和全局状态创建为后续的 UI 渲染奠定了基础。下一篇将讲解 Navigation 导航体系与自定义 TabBar 的实现。