HarmonyOS Interface (WindowStage) 使用指南从入门到实战摘要WindowStage是 HarmonyOS 应用窗口管理的核心调度者负责管理应用的生命周期、页面加载和多窗口协调。本文基于 HarmonyOS NEXT开发实践系统讲解WindowStage接口的核心方法、生命周期回调和完整示例代码帮助开发者掌握应用窗口阶段的控制能力。效果一、WindowStage 接口概述WindowStage代表应用的窗口阶段是 UIAbility 与窗口系统之间的桥梁。每个 UIAbility 在onWindowStageCreate回调中接收一个WindowStage实例通过它可以加载应用页面内容获取主窗口实例创建应用子窗口监听窗口事件管理窗口布局与全屏模式1.1 导入方式import{window}fromkit.ArkUI;1.2 获取 WindowStage 实例WindowStage实例由系统在 UIAbility 生命周期中自动创建并传入开发者无需手动创建exportdefaultclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{// 此处获取 windowStage 实例}}二、生命周期回调2.1 onWindowStageCreate当应用窗口阶段创建时触发是初始化窗口和加载页面的关键入口。onWindowStageCreate(windowStage:window.WindowStage):void{hilog.info(0x0000,app,窗口阶段已创建);// 1. 加载主页面windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,app,加载失败: %{public}s,JSON.stringify(err));return;}hilog.info(0x0000,app,页面加载成功);});}2.2 onWindowStageDestroy当应用窗口阶段销毁时触发用于释放窗口相关资源。onWindowStageDestroy():void{hilog.info(0x0000,app,窗口阶段已销毁);// 清理资源}2.3 完整生命周期流程UIAbility.onCreate() ↓ UIAbility.onWindowStageCreate(windowStage) ← 窗口阶段创建 ↓ windowStage.loadContent(pages/Index) ← 加载页面 ↓ 页面 aboutToAppear() → build() ← 页面渲染 ↓ UIAbility.onForeground() ← 应用进入前台 ↓ UIAbility.onBackground() ← 应用进入后台 ↓ UIAbility.onWindowStageDestroy() ← 窗口阶段销毁 ↓ UIAbility.onDestroy() ← Ability销毁三、核心方法详解3.1 loadContent(path, callback)加载应用主页面内容是onWindowStageCreate中最核心的调用。windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,app,加载失败: %{public}s,JSON.stringify(err));return;}// 页面加载成功后的初始化操作});参数说明path页面路由地址对应main_pages.json中配置的页面路径callback加载完成回调err.code为 0 表示成功重要提示loadContent必须在getMainWindowSync()等方法之前调用或者在其回调中执行后续操作。3.2 getMainWindowSync()同步获取应用主窗口实例。letmainWindow:window.WindowwindowStage.getMainWindowSync();获取主窗口后可以进行以下操作// 获取UI上下文letuiContextmainWindow.getUIContext();// 获取窗口属性letpropsmainWindow.getWindowProperties();letwindowIdprops.id;// 设置全屏mainWindow.setWindowLayoutFullScreen(true);// 获取避让区域letavoidAreamainWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);3.3 createSubWindow(name, callback)在当前窗口阶段创建应用子窗口。windowStage.createSubWindow(mySubWindow,(err,subWindow){if(err.code){hilog.error(0x0000,app,创建子窗口失败: %{public}s,err.message);return;}// 子窗口创建成功进行配置subWindow.setUIContent(subwindow/SubPage,(){subWindow.setWindowBackgroundColor(#00000000);});subWindow.moveWindowTo(0,300);subWindow.resize(200,200);subWindow.showWindow();});参数说明name子窗口名称用于后续通过window.findWindow(name)查找callback创建回调返回(err, subWindow)两个参数注意事项子窗口名称必须唯一子窗口默认不可见需调用showWindow()显示子窗口需要通过setUIContent设置加载页面3.4 getMainWindow()异步获取主窗口推荐使用getMainWindowSync替代。windowStage.getMainWindow((err,mainWindow){if(!err.code){// 使用主窗口}});3.5 getLastWindow(callback)获取当前应用内最上层的子窗口。windowStage.getLastWindow((err,topWindow){if(!err.code){hilog.info(0x0000,app,最上层窗口ID:${topWindow.getWindowProperties().id});}});3.6 setWindowLayoutFullScreen通过 WindowStage 设置全屏布局与通过 Window 设置效果一致。// 推荐在 loadContent 回调中通过主窗口设置letmainWindowwindowStage.getMainWindowSync();mainWindow.setWindowLayoutFullScreen(true);四、完整示例WindowStage 综合应用以下示例展示如何在onWindowStageCreate中完成窗口初始化、全屏设置、避让区域获取、全局上下文存储等操作。4.1 EntryAbility 完整实现import{AbilityConstant,ConfigurationConstant,UIAbility,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{window}fromkit.ArkUI;constDOMAIN0x0000;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(DOMAIN,app,Ability onCreate);}onDestroy():void{hilog.info(DOMAIN,app,Ability onDestroy);}onWindowStageCreate(windowStage:window.WindowStage):void{hilog.info(DOMAIN,app,onWindowStageCreate);// Step 1: 加载主页面windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(DOMAIN,app,加载失败: %{public}s,JSON.stringify(err));return;}hilog.info(DOMAIN,app,页面加载成功);// Step 2: 获取UI上下文并存储到AppStorageletmainWindowwindowStage.getMainWindowSync();letuiContextmainWindow.getUIContext();AppStorage.setOrCreate(uiContext,uiContext);// Step 3: 存储windowStage供页面使用AppStorage.setOrCreate(windowStage,windowStage);// Step 4: 存储主窗口IDAppStorage.setOrCreate(mainWindowId,mainWindow.getWindowProperties().id);// Step 5: 设置全屏布局mainWindow.setWindowLayoutFullScreen(true);// Step 6: 获取状态栏避让区域letsysAvoidAreamainWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);lettopRectHeightsysAvoidArea.topRect.height;AppStorage.setOrCreate(topRectHeight,topRectHeight);// Step 7: 获取导航条避让区域letnavAvoidAreamainWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);letbottomRectHeightnavAvoidArea.bottomRect.height;AppStorage.setOrCreate(bottomRectHeight,bottomRectHeight);});}onWindowStageDestroy():void{hilog.info(DOMAIN,app,onWindowStageDestroy);}onForeground():void{hilog.info(DOMAIN,app,onForeground);}onBackground():void{hilog.info(DOMAIN,app,onBackground);}}4.2 页面中使用 WindowStage 创建子窗口状态管理V2版本import{window}fromkit.ArkUI;import{hilog}fromkit.PerformanceAnalysisKit;EntryComponentV2struct Index{LocalwindowStage:window.WindowStageAppStorage.get(windowStage)aswindow.WindowStage;LocalisSubWindowCreated:booleanfalse;// 创建子窗口createSubWindow():void{if(this.isSubWindowCreated){hilog.info(0x0000,app,子窗口已创建);return;}this.windowStage.createSubWindow(demoSubWin,(err,subWin){if(err.code){hilog.error(0x0000,app,创建失败: %{public}s,err.message);return;}// 设置子窗口页面subWin.setUIContent(subwindow/SubPage,(){subWin.setWindowBackgroundColor(#00000000);});// 设置位置和大小letuiContextthis.windowStage.getMainWindowSync().getUIContext();subWin.moveWindowTo(0,300);subWin.resize(uiContext.vp2px(60),uiContext.vp2px(60));// 显示子窗口subWin.showWindow();this.isSubWindowCreatedtrue;});}// 销毁子窗口asyncdestroySubWindow():Promisevoid{try{letsubWinwindow.findWindow(demoSubWin);awaitsubWin.destroyWindow();this.isSubWindowCreatedfalse;}catch(err){hilog.error(0x0000,app,销毁失败: %{public}s,JSON.stringify(err));}}build(){Column({space:20}){Text(WindowStage 示例).fontSize(24).fontWeight(FontWeight.Bold)Button(this.isSubWindowCreated?销毁子窗口:创建子窗口).onClick((){if(this.isSubWindowCreated){this.destroySubWindow();}else{this.createSubWindow();}})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}五、WindowStage 与多窗口协调5.1 窗口焦点管理在多窗口场景下需要管理窗口焦点的切换// 将焦点从子窗口转移回主窗口setTimeout((){letsubIdwindow.findWindow(subWin).getWindowProperties().id;letmainIdwindowStage.getMainWindowSync().getWindowProperties().id;window.shiftAppWindowFocus(subId,mainId);},500);5.2 EventHub 事件通信通过eventHub实现 Ability 与页面之间的事件通信// EntryAbility 中发送事件onForeground():void{this.context.eventHub.emit(onForeground);}// 页面中监听事件aboutToAppear():void{letctxthis.getUIContext().getHostContext();ctx?.eventHub.on(onForeground,(){// 应用回到前台时的处理逻辑});}aboutToDisappear():void{letctxthis.getUIContext().getHostContext();ctx?.eventHub.off(onForeground);}5.3 通过 AppStorage 实现全局数据共享WindowStage相关的全局数据推荐通过AppStorage管理// 存储AppStorage.setOrCreate(windowStage,windowStage);AppStorage.setOrCreate(uiContext,uiContext);AppStorage.setOrCreate(topRectHeight,topRectHeight);AppStorage.setOrCreate(bottomRectHeight,bottomRectHeight);// 页面中读取StorageLink(windowStage)windowStage:window.WindowStage;StorageProp(topRectHeight)topRectHeight:number0;六、开发要点与最佳实践6.1 loadContent 回调中的初始化顺序loadContent 回调 ├── 1. 获取 UIContext 并存储 ├── 2. 存储 WindowStage ├── 3. 设置全屏布局 ├── 4. 获取避让区域高度 └── 5. 其他初始化操作顺序很重要必须先loadContent成功再获取主窗口进行后续设置。6.2 子窗口页面路由配置子窗口页面需要在main_pages.json中注册{src:[pages/Index,subwindow/SubPage]}6.3 避免重复创建子窗口// 创建前检查是否已存在try{letexistingwindow.findWindow(subWinName);// 已存在直接显示existing.showWindow();}catch(err){// 不存在创建新窗口windowStage.createSubWindow(subWinName,callback);}6.4 应用退出时清理子窗口onBackground():void{// 应用进入后台时可选择隐藏或销毁子窗口try{letsubWinwindow.findWindow(subWinName);subWin.hideWindow();}catch(err){// 子窗口不存在}}七、WindowStage 接口方法速查表方法说明异步/同步loadContent(path, callback)加载主页面内容回调getMainWindowSync()同步获取主窗口同步getMainWindow(callback)异步获取主窗口回调createSubWindow(name, callback)创建应用子窗口回调getLastWindow(callback)获取最上层子窗口回调setWindowLayoutFullScreen(fullScreen)设置全屏布局异步八、总结WindowStage是 HarmonyOS 应用窗口管理的调度中心开发者需要重点掌握生命周期管理理解onWindowStageCreate和onWindowStageDestroy的时机页面加载loadContent是所有窗口操作的起点主窗口获取getMainWindowSync获取主窗口后进行全屏、避让区域等设置子窗口创建createSubWindow实现应用内悬浮窗效果全局数据管理通过AppStorage在 Ability 和页面间共享窗口信息事件通信通过eventHub实现 Ability 与页面的松耦合通信状态管理V2使用ComponentV2Local替代 V1 装饰器与AppStorage.get()配合使用相关文档Interface (Window) 使用指南Interface (AVPlayer) 使用指南简约风格悬浮窗效果案例指南ArkTS 悬浮窗开发避坑指南