Stage模型揭秘：EntryAbility如何驱动首页加载

维度

内容

本章主题

EntryAbility 如何在 Stage 模型下把“留痕”带到首页

核心源码

EntryAbility.ets、main_pages.json、module.json5、WorkClockService.ets、Index.ets

阅读目标

看懂启动链路、配置职责和首页数据为什么能在启动后直接出现

先给结论在 Stage 模型里，真正的入口不是首页页面本身，而是 EntryAbility。EntryAbility 负责先 bootstrap，再 loadContent，首页只是最后被加载出来的那一页。

import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { WorkClockService } from 'dynamiclibrary';
import { Routes } from '../common/Routes';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
      WorkClockService.getInstance().bootstrap(this.context);
    } catch (err) {
      hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
    }
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent(Routes.MAIN_PAGE, (err) => {
      if (err.code) {
        hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
        return;
      }
      hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
    });
  }
}

阶段

关键动作

效果

onCreate

先切换颜色模式，再调用 WorkClockService.bootstrap()

服务层在首页出现之前完成准备

onWindowStageCreate

通过 Routes.MAIN_PAGE 加载首页

入口和页面路由保持统一

loadContent 失败

记录 hilog 日志

便于定位白屏或路由错误

bootstrap(context: common.UIAbilityContext): void {
  AppStorage.setOrCreate<number>(AppStorageKeys.WORKCLOCK_VERSION, 0);
  AppStorage.setOrCreate<string>(AppStorageKeys.MAIN_TAB, AppTabs.HOME);
  WorkClockRepository.initialize(context);

  const raw: string = WorkClockRepository.readState();
  if (raw.length > 0) {
    const state: WorkClockState = this.parseState(raw);
    this.records = state.records;
    this.watermarkTemplates = state.watermarkTemplates ?? WorkClockService.buildDefaultWatermarkTemplates();
    this.selectedWatermarkTemplateId = state.selectedWatermarkTemplateId ?? this.watermarkTemplates[0].id;
    this.categoryOptions = state.categoryOptions ?? WorkClockService.buildDefaultCategoryOptions();
    this.noteOptions = state.noteOptions ?? WorkClockService.buildDefaultNoteOptions();
    this.publishSelectedWatermarkSnapshot();
    this.bumpVersion();
    return;
  }

  this.publishSelectedWatermarkSnapshot();
  this.persist();
}

步骤

做什么

结果

初始化 AppStorage

写入 WORKCLOCK_VERSION 和 MAIN_TAB

首页和服务层有统一的轻量状态入口

读取持久化状态

从 WorkClockRepository 取回 JSON

已有记录和模板可以直接恢复

回填默认值

当本地没有数据时装入默认模板和分类

首次安装也不会空白

发布水印快照

把当前模板写回 AppStorage

水印页和拍照页能同步读取

这一段的关键bootstrap 不是“初始化一下就完了”，而是把首页需要的默认状态、模板快照和持久化入口一次性搭好。首页之所以能直接展示内容，是因为这一步已经先把底子铺好了。

{
  "src": [
    "pages/Index",
    "pages/FeatureCapturePage",
    "pages/FeatureVoicePage",
    "pages/FeatureWatermarkPage",
    "pages/FeatureProjectPage",
    "pages/FeatureRecordPage",
    "pages/FeatureCalendarPage",
    "pages/FeatureStatsPage",
    "pages/FeatureSettingsPage"
  ]
}

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "pages": "$profile:main_pages",
    "requestPermissions": [
      { "name": "ohos.permission.CAMERA", "reason": "$string:camera_permission_reason" },
      { "name": "ohos.permission.MICROPHONE", "reason": "$string:microphone_permission_reason" },
      { "name": "ohos.permission.APPROXIMATELY_LOCATION", "reason": "$string:location_permission_reason" },
      { "name": "ohos.permission.LOCATION", "reason": "$string:location_permission_reason" }
    ]
  }
}

配置项

作用

本章关注点

mainElement

指向入口 Ability

系统先找到 EntryAbility，再决定加载什么页面

pages

绑定页面清单

首页和功能页都从这里被注册

requestPermissions

声明运行权限

相机、麦克风和定位都在这里提前声明

skills / actions

支持桌面入口

保证桌面点击能够进入应用

export class AppStorageKeys {
  static readonly MAIN_TAB: string = 'main.tab';
  static readonly WORKCLOCK_VERSION: string = 'workclock.version';
  static readonly WATERMARK_TEMPLATE_ID: string = 'watermark.templateId';
  static readonly WATERMARK_CATEGORY: string = 'watermark.category';
  static readonly WATERMARK_TITLE: string = 'watermark.title';
  static readonly WATERMARK_NOTE: string = 'watermark.note';
  static readonly WATERMARK_ACCENT_COLOR: string = 'watermark.accentColor';
  static readonly WATERMARK_BACKGROUND_COLOR: string = 'watermark.backgroundColor';
}

@StorageLink(AppStorageKeys.WORKCLOCK_VERSION)
@Watch('handleWorkClockVersionChanged')
private workclockVersion: number = 0;

aboutToAppear(): void {
  this.refreshAllData(true);
}

onPageShow(): void {
  this.refreshAllData(false);
}

private refreshAllData(resetCalendarDate: boolean): void {
  const storedTab: string | undefined = AppStorage.get(AppStorageKeys.MAIN_TAB) as string | undefined;
  if (storedTab && storedTab.length > 0) {
    this.currentTab = storedTab;
  }

  this.overview = this.service.getOverviewSnapshot();
  this.actions = this.service.getHomeActions();
  this.records = this.service.getRecords();
  this.recentRecords = this.service.getRecentRecords();
  this.featureBullets = this.service.getFeatureBullets();
  this.techFeatures = this.service.getTechFeatures();
  this.usageScenes = this.service.getUsageScenes();
  this.settings = this.service.getSettings();
  this.syncCalendarDisplayDate(resetCalendarDate);
}

private bumpVersion(): void {
  const current: number | undefined = AppStorage.get(AppStorageKeys.WORKCLOCK_VERSION) as number | undefined;
  AppStorage.setOrCreate<number>(AppStorageKeys.WORKCLOCK_VERSION, (current ?? 0) + 1);
}

Key

写入方

读取方

MAIN_TAB

WorkClockService.bootstrap / Index.switchTab

Index.refreshAllData

WORKCLOCK_VERSION

WorkClockService.bumpVersion

Index.@StorageLink + @Watch

WATERMARK_TEMPLATE_ID

publishSelectedWatermarkSnapshot

水印页和拍照页

WATERMARK_TITLE / NOTE / COLOR

publishSelectedWatermarkSnapshot

水印编辑页预览和保存

一句话记住它AppStorage 不是数据库，它只负责让页面之间共享轻量状态；真正的业务数据仍然由服务层和本地存储负责。

步骤

检查点

完成后看到什么

查看 EntryAbility

确认 onCreate 与 onWindowStageCreate 的职责

知道应用为什么先进入入口再进入首页

查看 bootstrap

确认服务层在首页前完成初始化

本地数据和模板快照已经准备好

查看 Index

确认 @StorageLink 和 refreshAllData 的作用

首页切换和刷新都能跟着版本号走