这一章只看一件事：应用为什么能先把服务层准备好，再把首页稳稳地加载出来。

图 4-1 章首页封面：Stage 模型入口与首页加载链路

维度

内容

本章主题

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

核心源码

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

阅读目标

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

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

本章导读

这一章只看入口链路：EntryAbility 怎么把首页送到用户面前，main_pages.json 和 module.json5 又各自负责什么。

  • 看启动顺序怎么走。
  • 看首页为什么能一打开就有数据。
  • 看哪些配置决定首屏和路由。

入口链路理顺之后，再看首页的数据渲染就会自然很多。

一、Stage 模型下，真正的入口是 EntryAbility

在这个项目里，应用从桌面图标被点开之后，最先被系统调用的是 EntryAbility。它不是一个普通页面，而是负责把应用从“启动态”切换到“可见态”的第一道闸门。这个阶段如果没有把服务层和窗口链路准备好，首页就算能渲染出来，也只会是一张空壳。

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 日志

便于定位白屏或路由错误

图 4-2 启动链路：系统启动 -> EntryAbility -> bootstrap -> 首页

二、先 bootstrap，再 loadContent

EntryAbility.onCreate 里最关键的动作不是页面渲染，而是 WorkClockService.bootstrap。它把本地持久化数据、默认模板和 AppStorage 状态先准备好，再把首页交给 windowStage.loadContent。这样做的好处很直接：首页第一次进入时拿到的就是可用数据，而不是临时拼出来的默认壳。

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

三、main_pages.json 和 module.json5 各管一半

页面清单和 Ability 配置是两层职责。main_pages.json 只告诉系统哪些页面可以被加载，module.json5 则负责声明入口 Ability、权限和启动能力。两份文件各管一半，缺一块都不行。

{
  "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" }
    ]
  }
}

图 4-3 配置关系：main_pages.json、module.json5 与 EntryAbility 的分工

配置项

作用

本章关注点

mainElement

指向入口 Ability

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

pages

绑定页面清单

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

requestPermissions

声明运行权限

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

skills / actions

支持桌面入口

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

四、首页为什么一打开就有数据

首页不是自己去拉一份孤立的数据，而是通过 AppStorage 里的轻量状态和服务层的快照来渲染。WorkClockService 负责维护真实数据，Index 负责在页面生命周期里把这些数据读出来，再渲染成首页、记录和统计卡片。

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` 的初始化、`main_pages.json` 的页面清单、`module.json5` 的入口与权限声明。只要这三处同时对齐，首页才有机会在启动后稳稳落地。

阶段

关键动作

读者看到的结果

onCreate

先 bootstrap 服务层

本地数据和默认状态提前准备好

onWindowStageCreate

再 loadContent 主页面

首页被稳定装载到窗口中

main_pages.json

声明可加载页面

首页和功能页路由来源清晰

module.json5

声明入口和权限

相机、麦克风和定位链路更完整

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  this.context.getApplicationContext().setColorMode(
    ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET
  );
  WorkClockService.getInstance().bootstrap(this.context);
}

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;
    }
  });
}

很多真机问题看上去像页面问题，实际上是入口阶段没有把服务和窗口准备好。把启动链路写清楚，文章本身会更完整，读者在跑项目时也更容易知道“先查哪里、后查哪里”。

五、把启动链路和首页数据闭环合起来

这一段把第 4 章再往前推一步：EntryAbility 不只是把首页送出来，还要先把服务层和 AppStorage 的轻量状态准备好。这样首页打开时拿到的不是临时壳，而是一份已经可以直接渲染的快照。

从这个角度看，main_pages.json 和 module.json5 也不只是静态配置，而是启动链路能否稳稳落地的关键边界。只要入口、页面清单和权限声明对齐，首页就能沿着同一条数据链路继续工作。

图4-4 启动后的数据闭环：EntryAbility 先准备服务层，再把首页快照交给 Index。

启动阶段

代码

目的

EntryAbility.onCreate()

WorkClockService.bootstrap(context)

先把持久化和默认状态准备好

windowStage.loadContent()

Routes.MAIN_PAGE

把首页送到用户面前

Index.aboutToAppear()/onPageShow()

refreshAllData()

首页一打开就读到最新快照

WORKCLOCK_VERSION

AppStorage

记录变化后触发页面重绘

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  this.context.getApplicationContext().setColorMode(
    ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET
  );
  WorkClockService.getInstance().bootstrap(this.context);
}

private refreshAllData(resetCalendarDate: boolean): void {
  this.overview = this.service.getOverviewSnapshot();
  this.records = this.service.getRecords();
  this.recentRecords = this.service.getRecentRecords();
}

private handleWorkClockVersionChanged(): void {
  this.refreshAllData(false);
}

把这一层再压实一次，第四章就不只是“入口能打开”，而是“入口打开后马上就能看到可以继续往下跑的真实数据”。这也是留痕后面几章能够顺着写下去的前提。

六、本章小结

第四章把启动链路真正串了起来：EntryAbility 先做服务初始化，再加载首页；main_pages.json 和 module.json5 各自负责页面清单和入口配置；Index 通过 AppStorage 的版本号和主 Tab 状态，把服务层快照渲染成用户能看到的数据。这样一来，首页一打开就有内容，后面的拍照、录音和记录页也都能沿着同一套状态链路工作。

今日实操

步骤

检查点

完成后看到什么

查看 EntryAbility

确认 onCreate 与 onWindowStageCreate 的职责

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

查看 bootstrap

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

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

查看 Index

确认 @StorageLink 和 refreshAllData 的作用

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

如果你在真机上点开“留痕”，首页能够立刻看到卡片、记录和状态，说明这一章的链路已经跑通了。

# harmonyos
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

WalkingLab 组织入驻 AtomGit，释放高校智能体开源科研成果

avatar AtomGit开源社区
cover

全球首个！京东全栈开源JoyAI-VL-Interaction，让大模型从“一问一答”走向“边看边说”

avatar AtomGit开源社区
cover

海外动态代理行业彻底换代，AI 数据时代新标准已到来

avatar AtomGit开源社区