HarmonyOS应用开发实战：猫猫大作战-在 HarmonyOS 应用中，冷启动是指用户从桌面点击图标到看到首屏内容的完整过程

前言

在 HarmonyOS 应用中，冷启动是指用户从桌面点击图标到看到首屏内容的完整过程。这个过程中的第一个回调就是onCreate——它在 UIAbility 实例首次创建时被触发，且在整个生命周期中仅执行一次。正确地使用onCreate管理启动参数、初始化全局状态、预加载配置数据，直接影响应用的启动速度和用户体验。

本文以「猫猫大作战」的EntryAbility为锚点，深入onCreate的参数解析、启动原因判断、全局数据初始化、与AppStorage/PersistenceV2的配合使用。

提示：本系列不讲 ArkTS 基础语法与环境搭建，假设你已跟完第 1–71 篇。本篇是阶段三第 72 篇。

一、onCreate 的作用与时机

1.1 调用时机

onCreate在 UIAbility 实例首次创建时被调用，系统会传入两个参数：

import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 整个生命周期只执行一次 } }

1.2 执行时序

用户点击桌面图标 ↓ AAFWK 创建 UIAbility 进程（如果进程不存在） ↓ 创建 UIAbility 实例 ↓ ▶ onCreate(want, launchParam) ← 在这里做初始化 ↓ onWindowStageCreate(windowStage) ↓ loadContent → 页面渲染 ↓ onForeground → 用户可见

关键特性：onCreate在整个 Ability 生命周期中只回调一次。如果 Ability 实例已存在（热启动），会调用onNewWant而非onCreate。

二、launchReason：启动原因判断

2.1 四种启动原因

launchParam.launchReason指示了当前 UIAbility 被启动的原因：

2.2 根据启动原因做差异化初始化

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { switch (launchParam.launchReason) { case AbilityConstant.LaunchReason.START_ABILITY: // 正常启动：加载完整 UI、初始化游戏引擎 hilog.info(DOMAIN, TAG, '正常启动'); this.initGameConfig(); break; case AbilityConstant.LaunchReason.CALL: // Call 启动：无需加载 UI，仅初始化后台服务 hilog.info(DOMAIN, TAG, 'Call 启动 — 后台模式'); break; case AbilityConstant.LaunchReason.CONTINUATION: // 跨端迁移：恢复之前的游戏状态 hilog.info(DOMAIN, TAG, '跨端迁移启动'); const restoredState = want.parameters?.['gameState']; if (restoredState) { AppStorage.setOrCreate('restoredState', restoredState); } break; case AbilityConstant.LaunchReason.APP_RECOVERY: // 应用恢复：恢复崩溃前的数据 hilog.info(DOMAIN, TAG, '应用恢复启动'); AppStorage.setOrCreate('isRecovery', true); break; default: break; } }

2.3 判断是否为首次启动

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { const isFirstLaunch = AppStorage.get<boolean>('isFirstLaunch') ?? true; if (isFirstLaunch) { // 首次启动：展示引导页、创建默认配置 AppStorage.setOrCreate('showGuide', true); AppStorage.setOrCreate('isFirstLaunch', false); } // 从 Want 参数中读取 DeepLink 目标页 const targetPage = want.parameters?.['targetPage']; if (targetPage) { AppStorage.setOrCreate('targetPage', targetPage); } }

三、Want 参数深度解析

3.1 Want 核心字段

3.2 在 onCreate 中读取参数

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 读取 bundleName 和 abilityName hilog.info(DOMAIN, TAG, `启动者: ${want.bundleName}`); hilog.info(DOMAIN, TAG, `目标: ${want.abilityName}`); // 读取 URI 参数 const uri = want.uri; if (uri && uri.startsWith('catscheme://')) { const url = new URL(uri); const id = url.searchParams.get('id'); if (id) { AppStorage.setOrCreate('deepLinkPlayerId', parseInt(id)); } } // 读取自定义 parameters const fromNotification = want.parameters?.['fromNotification']; if (fromNotification === true) { // 通过通知点击启动 AppStorage.setOrCreate('enterFrom', 'notification'); } }

3.3 通过 Want 传递复杂对象

// 发送方 let want: Want = { bundleName: 'com.maomaodazuozhan.game', abilityName: 'EntryAbility', parameters: { 'playerName': '猫猫侠', 'highScore': 99999, 'isNewRecord': true } }; startAbility(want); // 接收方（onCreate 中解析） onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { const playerName = want.parameters?.['playerName'] as string; const highScore = want.parameters?.['highScore'] as number; if (playerName) { AppStorage.setOrCreate('welcomePlayer', playerName); } if (highScore) { AppStorage.setOrCreate('shareHighScore', highScore); } }

四、全局状态初始化

4.1 使用 AppStorage 预置默认值

猫猫大作战在onCreate中需要初始化的全局状态：

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 初始化全局状态（仅当不存在时设置） AppStorage.setOrCreate('highScore', 0); AppStorage.setOrCreate('gameState', 'IDLE'); AppStorage.setOrCreate('soundEnabled', true); AppStorage.setOrCreate('vibrationEnabled', true); AppStorage.setOrCreate('lastPlayDate', ''); }

4.2 使用 PersistenceV2 持久化

如果需要跨冷启动保留数据，使用PersistenceV2：

import { PersistenceV2 } from '@kit.ArkData'; onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // PersistenceV2 自动从磁盘恢复数据到 AppStorageV2 // 无需手动读取，框架自动完成 // 检查是否从恢复模式启动 if (launchParam.launchReason === AbilityConstant.LaunchReason.APP_RECOVERY) { // 通知业务层使用恢复数据 AppStorage.setOrCreate('dataRecoveryMode', true); } }

4.3 数据初始化策略对比

五、项目实战：猫猫大作战的冷启动优化

5.1 当前的 onCreate 实现

当前项目EntryAbility.ets中的onCreate只做了日志记录：

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { hilog.info(DOMAIN, TAG, '%{public}s', 'Ability onCreate'); }

5.2 增强后的实现

import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; import { window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; const TAG = 'EntryAbility'; const DOMAIN = 0xFF00; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { hilog.info(DOMAIN, TAG, '=== Ability onCreate ==='); // 1. 记录启动原因用于后续分析 this.recordLaunchReason(launchParam); // 2. 解析启动参数 this.parseWantParameters(want); // 3. 初始化全局状态 this.initGlobalState(); // 4. 根据启动原因预加载数据 this.preloadByLaunchReason(launchParam); } private recordLaunchReason(launchParam: AbilityConstant.LaunchParam): void { const reasonMap: Record<number, string> = { 0: 'START_ABILITY', 1: 'CALL', 2: 'CONTINUATION', 3: 'APP_RECOVERY' }; hilog.info(DOMAIN, TAG, `启动原因: ${reasonMap[launchParam.launchReason] ?? '未知'}`); } private parseWantParameters(want: Want): void { // 检查是否有 DeepLink 参数 if (want.parameters) { for (const [key, value] of Object.entries(want.parameters)) { hilog.info(DOMAIN, TAG, `启动参数: ${key}=${JSON.stringify(value)}`); } } } private initGlobalState(): void { // 使用 AppStorage 设置全局默认值（仅初始化一次） AppStorage.setOrCreate('highScore', 0); AppStorage.setOrCreate('soundEnabled', true); AppStorage.setOrCreate('vibrationEnabled', true); AppStorage.setOrCreate('gameCount', 0); } private preloadByLaunchReason(launchParam: AbilityConstant.LaunchParam): void { if (launchParam.launchReason === AbilityConstant.LaunchReason.APP_RECOVERY) { // 恢复模式：延迟加载检查点 AppStorage.setOrCreate('recoveryMode', true); } } }

六、冷启动性能指标

6.1 性能目标

6.2 onCreate 中的耗时红线

// 🚫 错误：onCreate 中执行耗时操作 onCreate(want, launchParam): void { const data = await getDataFromNetwork(); // ❌ 网络请求 const config = JSON.parse(fs.readTextSync('config.json')); // ❌ 文件 IO const result = heavyComputation(); // ❌ 复杂计算 } // ✅ 正确：仅做轻量标记和初始化 onCreate(want, launchParam): void { AppStorage.setOrCreate('configLoaded', false); // ✅ 标记状态 // 实际加载交给页面级 aboutToAppear 或异步任务 }

七、常见踩坑

7.1 坑一：混淆 onCreate 与 aboutToAppear

// 🚫 错误：在 aboutToAppear 中读取启动参数（拿不到） aboutToAppear() { const want = /* 取不到！ */; } // ✅ 正确：在 onCreate 中将参数放入全局存储 onCreate(want, launchParam) { AppStorage.setOrCreate('targetPage', want.parameters?.['targetPage']); } // 然后在页面中通过 AppStorage 读取 aboutToAppear() { const target = AppStorage.get<string>('targetPage'); }

7.2 坑二：onCreate 中创建全局单例导致引用泄漏

// 🚫 错误：onCreate 中创建的单例持有 Ability 引用 onCreate(want, launchParam) { GlobalManager.getInstance().setAbility(this); // ❌ 持有引用 → 无法 GC } // ✅ 正确：使用 AppStorage 或事件总线通信 onCreate(want, launchParam) { AppStorage.setOrCreate('appInitialized', true); }

八、总结

onCreate是 UIAbility 的生命周期起点，执行正确的初始化策略能显著提升应用的启动速度和稳定性。

核心要点：

• onCreate在 Ability 生命周期中只执行一次，适合做全局初始化
• 通过launchParam.launchReason区分四种启动原因，做差异化初始化
• Want.parameters承载启动参数，通过AppStorage传递给页面层
• 禁止在onCreate中执行网络请求、文件 IO、复杂计算等耗时操作
• 全局状态初始化推荐使用AppStorage.setOrCreate()，持久化用PersistenceV2

下一篇预告：第 73 篇将深入loadContent— 首屏页面加载的完整链路与错误处理。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• UIAbility 生命周期官方文档
• Want 与 Ability 启动
• AppStorage 全局存储
• UIAbility 启动类型
• AbilityConstant.LaunchReason 参考
• 开源鸿蒙跨平台社区
• 第 71 篇：EntryAbility 入口
• 第 73 篇：loadContent 首屏绑定