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 { // 整个生命周期只执行一次 } }参数类型说明wantWant启动请求包含目标 Ability、参数、URI 等launchParamAbilityConstant.LaunchParam启动参数包含启动原因launchReason1.2 执行时序用户点击桌面图标 ↓ AAFWK 创建 UIAbility 进程如果进程不存在 ↓ 创建 UIAbility 实例 ↓ ▶ onCreate(want, launchParam) ← 在这里做初始化 ↓ onWindowStageCreate(windowStage) ↓ loadContent → 页面渲染 ↓ onForeground → 用户可见关键特性onCreate在整个 Ability 生命周期中只回调一次。如果 Ability 实例已存在热启动会调用onNewWant而非onCreate。二、launchReason启动原因判断2.1 四种启动原因launchParam.launchReason指示了当前 UIAbility 被启动的原因启动原因枚举值触发场景START_ABILITY0通过 startAbility 启动桌面图标、router/ Navigation 跳转CALL1通过 startAbilityByCall 启动后台启动、跨进程调用CONTINUATION2跨端迁移手机→平板、手机→折叠屏APP_RECOVERY3应用恢复应用异常崩溃后重启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.getboolean(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 核心字段字段类型说明deviceIdstring目标设备 ID跨端场景必填bundleNamestring目标应用的 bundleNameabilityNamestring目标 Ability 名称uristring统一资源标识符如catscheme://ranking?id123typestringMIME 类型如text/plainparametersRecordstring, Object自定义键值对参数flagsnumber启动模式标记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 持久化如果需要跨冷启动保留数据使用PersistenceV2import { 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: Recordnumber, 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回调作用域执行时机用途onCreateAbility 级应用进程启动时全局初始化、启动参数解析aboutToAppear页面级页面组件创建时页面数据加载、UI 状态设置// 错误在 aboutToAppear 中读取启动参数拿不到 aboutToAppear() { const want /* 取不到 */; } // ✅ 正确在 onCreate 中将参数放入全局存储 onCreate(want, launchParam) { AppStorage.setOrCreate(targetPage, want.parameters?.[targetPage]); } // 然后在页面中通过 AppStorage 读取 aboutToAppear() { const target AppStorage.getstring(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 首屏绑定