一、UIAbility 是什么在 HarmonyOS 应用开发中**UIAbility** 是承载 UI 界面的核心组件相当于 Android 的 Activity。一个应用可以有多个 UIAbility每个 UIAbility 独立管理自己的 UI 生命周期和窗口。该战旗项目只有一个 UIAbilityEntryAbility它是整个应用的启动入口。二、EntryAbility 完整代码解析import UIAbility from ohos.app.ability.UIAbility;import window from ohos.window;export default class EntryAbility extends UIAbility {// 窗口创建时调用onWindowStageCreate(windowStage: window.WindowStage) {// 设置窗口布局非全屏windowStage.getMainWindow().then((win) {win.setWindowLayoutFullScreen(false);});// 加载首页windowStage.loadContent(pages/Index, (err, data) {if (err.code) {console.error(Failed to load the content. Cause: JSON.stringify(err));return;}});}onWindowStageDestroy() {// 窗口销毁时释放 UI 相关资源}onForeground() {// 应用进入前台用户切换回来}onBackground() {// 应用进入后台用户按 Home 键}}三、UIAbility 生命周期状态机应用启动↓onCreate初始化↓onWindowStageCreate创建窗口↓onForeground前台运行 ←─────────┐↓ │用户按 Home 键 │↓ │onBackground后台 │↓ │用户切回应用 ────────────────────────┘↓onWindowStageDestroy销毁窗口↓onDestroy销毁各生命周期回调的职责| 回调 | 触发时机 | 建议操作 ||------|---------|---------|| onCreate | Ability 创建代码未展示| 初始化全局数据 || onWindowStageCreate | 窗口创建好可以加载页面 | 加载首页配置窗口 || onForeground | 应用从后台切换到前台 | 恢复游戏计时器、刷新数据 || onBackground | 应用进入后台 | 保存游戏进度、暂停动画 || onWindowStageDestroy | 窗口即将销毁 | 释放 Canvas、停止计时器 || onDestroy | Ability 销毁 | 释放所有资源 |四、加载首页loadContentwindowStage.loadContent(pages/Index, (err, data) {if (err.code) {console.error(Failed to load the content. Cause: JSON.stringify(err));return;}});loadContent 加载的路径 pages/Index 对应 entry/src/main/ets/pages/Index.ets框架自动解析路径和文件扩展名。错误处理模式这里使用了 HarmonyOS API 的标准错误处理模式——回调函数的第一个参数 err 包含错误信息。如果 err.code ! 0说明加载失败。// 更健壮的写法区分错误码if (err.code) {console.error(Error code: ${err.code}, message: ${err.message});return;}// 加载成功后的操作五、窗口全屏配置windowStage.getMainWindow().then((win) {win.setWindowLayoutFullScreen(false); // false 非全屏保留状态栏});setWindowLayoutFullScreen参数- true全屏布局UI 延伸到状态栏区域沉浸式- false普通布局状态栏不被遮挡对于游戏应用通常使用 true 实现沉浸式体验本游戏选择了 false 保留顶部状态栏方便看时间、信号等。Promise 链式调用windowStage.getMainWindow() // 返回 PromiseWindow.then((win) { // 获取窗口对象win.setWindowLayoutFullScreen(false); // 配置窗口});.then() 是 Promise 的链式处理getMainWindow() 是异步操作需要等待获取到窗口对象后再配置。六、module.json5 工程配置深度解析{module: {name: entry, // 模块名称HAP 包名type: entry, // 模块类型entry 入口模块description: Ancient Empire War Flag Game,mainElement: EntryAbility, // 默认启动的 AbilitydeviceTypes: [phone, tablet], // 支持的设备类型deliveryWithInstall: true, // 随应用安装时一同下载installationFree: false, // 不是免安装应用pages: $profile:main_pages, // 页面路由配置文件abilities: [{name: EntryAbility,srcEntry: ./ets/entryability/EntryAbility.ets, // 源文件路径description: $string:EntryAbility_desc, // 引用字符串资源icon: $media:icon,label: $string:EntryAbility_label,startWindowIcon: $media:icon, // 启动屏图标startWindowBackground: $color:start_window_background, // 启动屏背景色visible: true,orientation: unspecified // 屏幕方向不限制}]}}关键字段说明deviceTypesdeviceTypes: [phone, tablet]声明本应用支持手机和平板HarmonyOS 会根据设备类型调整部分行为如界面适配。orientationjson5orientation: unspecified // 跟随系统设置也可以设为- portrait — 强制竖屏- landscape — 强制横屏战棋游戏通常横屏更好更宽的地图视野可以考虑改为 landscape。资源引用语法| 语法 | 说明 | 资源文件 ||------|------|---------|| $string:name | 字符串资源 | element/string.json || $color:name | 颜色资源 | element/color.json || $media:name | 媒体资源 | resources/media/ || $profile:name | 配置文件 | resources/profile/ |## 七、页面路由配置// resources/base/profile/main_pages.json{src: [pages/Index.ets,pages/GamePage.ets]}**所有页面都必须在这里注册**否则 router.pushUrl({ url: pages/GamePage }) 会报错找不到页面。页面路径规则- 相对于 entry/src/main/ets/ 目录- 不需要写 .ets 扩展名写了也不报错八、资源文件管理string.json — 字符串资源{string: [{ name: EntryAbility_label, value: 远古帝国战旗 },{ name: EntryAbility_desc, value: Ancient Empire War Flag Game }]}EntryAbility_label 是应用在桌面显示的名称EntryAbility_desc 是应用描述。color.json — 颜色资源{color: [{ name: start_window_background, value: #F5DEB3 }]}start_window_background 是启动屏的背景色小麦色 #F5DEB3与游戏主题色一致减少启动时的视觉跳跃。九、HarmonyOS 应用分层模型应用App└── HAP 包module└── UIAbility应用窗口└── WindowStage窗口舞台└── PageArkUI 页面└── ComponentArkUI 组件从上到下依次- **App**应用标识对应 AppScope- **HAP 包**可独立安装的模块entry 是入口 HAP- **UIAbility**UI 容器管理页面栈- **Page**带 Entry 的组件一个页面一个文件- **Component**不带 Entry 的组件可复用的 UI 片段十、小结EntryAbility 虽然代码简短却是整个 HarmonyOS 应用的基石负责窗口创建、页面加载和生命周期管理。理解 UIAbility 的生命周期对于处理游戏暂停/恢复、资源管理至关重要。在实际游戏项目中应该在 onBackground 中保存游戏进度在 onForeground 中恢复给玩家提供完整的后台恢复体验。