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 { // 整个生命周期只执行一次 } }| 参数 | 类型 | 说明 |
|---|---|---|
want | Want | 启动请求，包含目标 Ability、参数、URI 等 |
launchParam | AbilityConstant.LaunchParam | 启动参数，包含启动原因launchReason |
1.2 执行时序
用户点击桌面图标 ↓ AAFWK 创建 UIAbility 进程（如果进程不存在） ↓ 创建 UIAbility 实例 ↓ ▶ onCreate(want, launchParam) ← 在这里做初始化 ↓ onWindowStageCreate(windowStage) ↓ loadContent → 页面渲染 ↓ onForeground → 用户可见关键特性：
onCreate在整个 Ability 生命周期中只回调一次。如果 Ability 实例已存在（热启动），会调用onNewWant而非onCreate。
二、launchReason：启动原因判断
2.1 四种启动原因
launchParam.launchReason指示了当前 UIAbility 被启动的原因：
| 启动原因 | 枚举值 | 触发场景 |
|---|---|---|
START_ABILITY | 0 | 通过 startAbility 启动（桌面图标、router/ Navigation 跳转） |
CALL | 1 | 通过 startAbilityByCall 启动（后台启动、跨进程调用） |
CONTINUATION | 2 | 跨端迁移（手机→平板、手机→折叠屏） |
APP_RECOVERY | 3 | 应用恢复（应用异常崩溃后重启） |
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 核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
deviceId | string | 目标设备 ID（跨端场景必填） |
bundleName | string | 目标应用的 bundleName |
abilityName | string | 目标 Ability 名称 |
uri | string | 统一资源标识符（如catscheme://ranking?id=123） |
type | string | MIME 类型（如text/plain） |
parameters | Record<string, Object> | 自定义键值对参数 |
flags | number | 启动模式标记 |
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 数据初始化策略对比
| 方式 | 持久化 | 作用域 | 推荐用途 |
|---|---|---|---|
AppStorage.setOrCreate() | ❌ 不持久 | 全局 | 临时启动参数、开关状态 |
PersistenceV2自动恢复 | ✅ 自动 | 全局 | 用户设置、高分记录 |
Preferences手动读写 | ✅ 手动 | 全局 | 复杂配置、自定义数据 |
LocalStorage | ❌ 不持久 | 页面级 | 页面间共享数据 |
五、项目实战：猫猫大作战的冷启动优化
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 性能目标
| 指标 | 目标值 | 验收标准 |
|---|---|---|
| onCreate 执行耗时 | < 5ms | 纯标记和初始化，无 IO |
| 首帧渲染时间 | < 1s | 从点击图标到用户看到内容 |
| 可交互时间 | < 1.5s | 页面渲染完成 + 动画就绪 |
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
| 回调 | 作用域 | 执行时机 | 用途 |
|---|---|---|---|
onCreate | Ability 级 | 应用进程启动时 | 全局初始化、启动参数解析 |
aboutToAppear | 页面级 | 页面组件创建时 | 页面数据加载、UI 状态设置 |
// 🚫 错误：在 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 首屏绑定