前言在 HarmonyOS 应用中WindowStage窗口舞台是连接 UIAbility 与页面的中间枢纽——它负责管理应用窗口的创建、显示、隐藏、销毁全周期并承载loadContent加载首屏页面。理解onWindowStageCreate回调的完整能力是写出流畅、健壮的 ArkUI 应用的基础。本文以「猫猫大作战」的EntryAbility为锚点深入onWindowStageCreate中的窗口事件订阅、窗口属性配置、多窗口适配以及 WindowStageEventType 六种状态变化。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–73 篇。本篇是阶段三第 74 篇。一、WindowStage 是什么1.1 角色定位UIAbility应用组件 │ │ 拥有 ▼ WindowStage窗口舞台 │ │ 包含 ▼ Window窗口—— 承载 UI 内容 │ │ 加载 ▼ ArkUI 页面Index.ets层级职责生命周期回调UIAbility应用组件的生命周期管理onCreate → onForeground → onBackground → onDestroyWindowStage窗口舞台的管理onWindowStageCreate → onWindowStageWillDestroy → onWindowStageDestroyWindow窗口属性与事件SHOWN / ACTIVE / INACTIVE / HIDDEN / RESUMED / PAUSED1.2 猫猫大作战中的 WindowStageimport { UIAbility, Want, AbilityConstant } from kit.AbilityKit; import { window } from kit.ArkUI; import { hilog } from kit.PerformanceAnalysisKit; export default class EntryAbility extends UIAbility { private windowStageObj: window.WindowStage | undefined undefined; onWindowStageCreate(windowStage: window.WindowStage): void { hilog.info(0xFF00, EntryAbility, onWindowStageCreate); this.windowStageObj windowStage; // 订阅窗口事件 windowStage.on(windowStageEvent, (data) { this.handleWindowStageEvent(data); }); // 加载首屏 windowStage.loadContent(pages/Index, (err) { if (err.code) { hilog.error(0xFF00, EntryAbility, 加载失败: %{public}s, JSON.stringify(err)); return; } hilog.info(0xFF00, EntryAbility, 首屏加载成功); }); } onWindowStageWillDestroy(windowStage: window.WindowStage): void { // 销毁前注销订阅 windowStage.off(windowStageEvent); this.windowStageObj undefined; } onWindowStageDestroy(): void { hilog.info(0xFF00, EntryAbility, onWindowStageDestroy); } }二、WindowStageEventType 六种状态2.1 状态枚举事件类型含义触发时机项目用途SHOWN窗口切到前台应用从后台回到前台恢复游戏引擎ACTIVE窗口获焦用户与窗口交互启动游戏定时器INACTIVE窗口失焦用户拉下通知栏暂停游戏HIDDEN窗口切到后台用户按 Home 键暂停游戏、释放资源RESUMED前台可交互窗口完全就绪继续游戏PAUSED前台不可交互窗口被部分遮挡降帧省电2.2 完整状态机┌─────────┐ │ SHOWN │ ← 窗口进入前台 └────┬────┘ │ ┌────▼────┐ ┌───│ ACTIVE │ ← 获焦 │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ RESUMED │ ← 可交互 │ └────┬────┘ │ │ INACTIVE ◄────┘ ← 失焦如通知栏下拉 │ │ ┌─────────┐ └──►│ PAUSED │ ← 前台不可交互 └────┬────┘ │ ┌────▼────┐ │ HIDDEN │ ← 完全进入后台 └─────────┘2.3 实战根据窗口事件控制游戏private handleWindowStageEvent(eventType: window.WindowStageEventType): void { switch (eventType) { case window.WindowStageEventType.SHOWN: hilog.info(0xFF00, EntryAbility, 窗口回到前台); // 通知游戏页面恢复 AppStorage.setOrCreate(windowState, foreground); break; case window.WindowStageEventType.ACTIVE: hilog.info(0xFF00, EntryAbility, 窗口获焦); break; case window.WindowStageEventType.INACTIVE: hilog.info(0xFF00, EntryAbility, 窗口失焦 — 暂停游戏); // 失焦时暂停防止操作继续 AppStorage.setOrCreate(windowState, inactive); AppStorage.setOrCreate(gamePausedBySystem, true); break; case window.WindowStageEventType.HIDDEN: hilog.info(0xFF00, EntryAbility, 窗口进入后台 — 释放资源); AppStorage.setOrCreate(windowState, background); break; case window.WindowStageEventType.RESUMED: hilog.info(0xFF00, EntryAbility, 前台可交互 — 继续游戏); break; case window.WindowStageEventType.PAUSED: hilog.info(0xFF00, EntryAbility, 前台不可交互 — 暂停动画); break; default: break; } }三、窗口属性配置3.1 获取 Window 对象通过windowStage.getMainWindow()获取Window对象配置窗口属性async onWindowStageCreate(windowStage: window.WindowStage): Promisevoid { try { const windowClass await windowStage.getMainWindow(); // 设置窗口全屏 windowClass.setWindowLayoutFullScreen(true); // 设置窗口背景色 windowClass.setWindowBackgroundColor(#E8F4F8); // 禁止窗口大小调整 windowClass.setWindowResizable(false); // 设置窗口是否保持常亮 windowClass.setWindowKeepScreenOn(true); hilog.info(0xFF00, EntryAbility, 窗口属性配置完成); } catch (err) { hilog.error(0xFF00, EntryAbility, 窗口配置失败: %{public}s, JSON.stringify(err)); } windowStage.loadContent(pages/Index); }3.2 常用窗口属性属性方法游戏场景用途全屏模式setWindowLayoutFullScreen(true)沉浸式游戏体验保持常亮setWindowKeepScreenOn(true)游戏过程中不锁屏背景色setWindowBackgroundColor(#E8F4F8)与应用主色调匹配允许调整setWindowResizable(false)固定棋盘布局横竖屏setWindowPreferredOrientation()锁定竖屏游戏3.3 窗口属性最佳实践async onWindowStageCreate(windowStage: window.WindowStage): Promisevoid { const windowClass await windowStage.getMainWindow(); // 锁定为竖屏 try { windowClass.setWindowPreferredOrientation( window.Orientation.PORTRAIT ); } catch { // 部分设备不支持锁定方向 } // 保持屏幕常亮 windowClass.setWindowKeepScreenOn(true); windowStage.loadContent(pages/Index); }四、onWindowStageWillDestroy 与资源释放4.1 与 onWindowStageDestroy 的区别应用退出流程 onWindowStageWillDestroy(windowStage) ├── WindowStage 仍然可用 ├── 在此注销窗口事件、释放窗口资源 └── 执行完毕后 WindowStage 被销毁 onWindowStageDestroy() └── WindowStage 已被销毁无法操作 └── 仅作为日志通知回调回调WindowStage 可用用途onWindowStageWillDestroy✅ 可用注销事件、释放资源onWindowStageDestroy❌ 不可用仅日志记录4.2 正确释放资源export default class EntryAbility extends UIAbility { private windowStageObj: window.WindowStage | undefined undefined; onWindowStageCreate(windowStage: window.WindowStage): void { this.windowStageObj windowStage; // 订阅窗口事件 windowStage.on(windowStageEvent, this.handleWindowStageEvent.bind(this)); windowStage.loadContent(pages/Index); } onWindowStageWillDestroy(windowStage: window.WindowStage): void { // ✅ 正确的释放位置WindowStage 还未销毁 try { windowStage.off(windowStageEvent); // 注销事件 this.windowStageObj undefined; // 释放引用 hilog.info(0xFF00, EntryAbility, 窗口资源已释放); } catch (err) { hilog.error(0xFF00, EntryAbility, 释放失败); } } onWindowStageDestroy(): void { // ❌ 此时 WindowStage 已销毁只能记录日志 hilog.info(0xFF00, EntryAbility, WindowStage 已销毁); } }五、多窗口与分屏适配5.1 窗口大小变化监听async onWindowStageCreate(windowStage: window.WindowStage): Promisevoid { const windowClass await windowStage.getMainWindow(); // 监听窗口大小变化 windowClass.on(windowSizeChange, (size: window.Size) { hilog.info(0xFF00, EntryAbility, 窗口大小变化: ${size.width}x${size.height}); // 根据窗口宽度判断布局模式 if (size.width 600) { AppStorage.setOrCreate(layoutMode, compact); } else if (size.width 840) { AppStorage.setOrCreate(layoutMode, medium); } else { AppStorage.setOrCreate(layoutMode, expanded); } }); windowStage.loadContent(pages/Index); }5.2 分屏/悬浮窗场景// 在分屏模式下窗口面积缩小可以做相应调整 windowClass.on(windowSizeChange, (size: window.Size) { if (size.width 400 || size.height 400) { // 极小窗口隐藏非核心 UI简化棋盘渲染 AppStorage.setOrCreate(simplifiedMode, true); } else { AppStorage.setOrCreate(simplifiedMode, false); } });六、WindowStage 与 UIAbility 的关联6.1 完整生命周期对照时序UIAbility 回调WindowStage 回调窗口状态①onCreate——②—onWindowStageCreateWindowStage 创建③——loadContent 加载页面④onForeground—窗口可见⑤—SHOWN / ACTIVE窗口获焦可交互⑥onBackgroundHIDDEN窗口进入后台⑦—onWindowStageWillDestroyWindowStage 即将销毁⑧—onWindowStageDestroyWindowStage 已销毁⑨onDestroy—UIAbility 销毁6.2 关键设计原则原则 1WindowStage 的事在 WindowStage 回调中完成 原则 2loadContent 必须在 onWindowStageCreate 中调用 原则 3窗口事件订阅必须在 onWindowStageWillDestroy 中注销 原则 4首屏路径必须与 main_pages.json 注册一致七、常见踩坑7.1 坑一在 onWindowStageDestroy 中操作窗口// 错误onWindowStageDestroy 中 WindowStage 已不可用 onWindowStageDestroy(): void { this.windowStageObj?.loadContent(pages/Other); // ❌ 会崩溃 } // ✅ 正确在 onWindowStageWillDestroy 中释放 onWindowStageWillDestroy(windowStage: window.WindowStage): void { windowStage.off(windowStageEvent); }7.2 坑二忘记注销窗口事件订阅onWindowStageCreate(windowStage) { windowStage.on(windowStageEvent, callback); // 注册了 // 但 onWindowStageWillDestroy 中忘记注销 → 内存泄漏 }八、总结onWindowStageCreate是 WindowStage 生命周期的起点它连接了 UIAbility 与 UI 页面。通过窗口事件订阅可以精确感知获焦/失焦、前台/后台切换配合窗口属性配置可以实现全屏、常亮、锁定横竖屏等游戏场景关键能力。核心要点onWindowStageCreate中订阅窗口事件、配置窗口属性、加载首屏页面六种窗口事件类型SHOWN/ACTIVE/INACTIVE/HIDDEN/RESUMED/PAUSEDonWindowStageWillDestroy中注销事件、释放资源windowStage.getMainWindow()获取 Window 对象配置窗口属性监听windowSizeChange适配分屏/多窗口下一篇预告第 75 篇将深入onForeground/onBackground— 前后台切换时如何暂停和恢复游戏。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源UIAbility 生命周期文档WindowStage API 参考窗口生命周期文档WindowStageEventType 枚举应用冷启动优化开源鸿蒙跨平台社区第 73 篇loadContent 首屏绑定第 75 篇onForeground/onBackground
