文章配图：在 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启动参数，包含启动原因 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_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.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 核心字段

字段类型说明
deviceIdstring目标设备 ID（跨端场景必填）
bundleNamestring目标应用的 bundleName
abilityNamestring目标 Ability 名称
uristring统一资源标识符（如 catscheme://ranking?id=123）
typestringMIME 类型（如 text/plain）
parametersRecord<string, 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 持久化

如果需要跨冷启动保留数据，使用 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

回调作用域执行时机用途
onCreateAbility 级应用进程启动时全局初始化、启动参数解析
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 — 首屏页面加载的完整链路与错误处理。

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

相关资源：

# 鸿蒙
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

【开发者故事】这款小众穿戴应用，凭什么让7成用户天天打开 ？

avatar HarmonyOS开发者社区
cover

灯光模拟HarmonyOS应用实战-38-近光与转向灯为何不能同时表达：用正交LampState替代单一lightState

avatar HarmonyOS开发者社区
cover

灯光模拟HarmonyOS应用实战-37-转向灯要求保持3秒却点击即判正确：用持续状态门禁校验实操动作

avatar HarmonyOS开发者社区