【HarmonyOS/OpenHarmony】创新体验：从应用入口到页面加载理解全场景应用基础链路

前言 🌟

全场景应用不是只有设备协同这一层。对任何 HarmonyOS / OpenHarmony 应用来说，想要在更多场景中稳定运行，首先要有清晰的应用入口链路。

当前项目的入口链路非常典型：应用配置声明入口，模块配置声明 Ability，EntryAbility 创建窗口，最后加载 pages/Index 首页。

本文基于当前项目真实代码，梳理从应用入口到页面加载的基础链路，并说明它为什么是理解全场景应用的起点。

本文对应四大主题中的 创新体验。

应用级入口：app.json5 🧩

当前项目的应用配置在：

AppScope/app.json5

核心内容包括：

"bundleName": "xiao.hong.shu8",
"versionName": "1.0.0",
"icon": "$media:layered_image",
"label": "$string:app_name"

这部分定义的是应用身份。用户看到应用图标和应用名称时，背后就和这些配置有关。

全场景应用也需要统一身份。无论后续是否支持更多设备，应用包名、图标、名称、版本信息都应该保持清晰。

模块入口：module.json5 📦

当前项目的模块配置中声明：

"mainElement": "EntryAbility",
"deviceTypes": [
  "phone"
],
"pages": "$profile:main_pages"

这说明当前模块的主入口是 EntryAbility，当前设备类型是 phone，页面列表来自 main_pages。

这里要特别注意：当前项目只声明了手机设备，不是完整多设备应用。本文讨论的是入口链路基础，而不是已经实现全场景流转。

Ability 入口：EntryAbility.ets ⚙️

主 Ability 位于：

entry/src/main/ets/entryability/EntryAbility.ets

其中最关键的是：

onWindowStageCreate(windowStage: window.WindowStage): void {
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (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.');
  });
}

这段代码完成了窗口创建后的页面加载。

从链路上看：

EntryAbility
  -> onWindowStageCreate
  -> loadContent('pages/Index')
  -> Index 页面

如果这个链路不清楚，后续做更多页面、更多设备或更多入口场景时就容易混乱。

页面注册：main_pages.json ✅

当前页面注册文件是：

{
  "src": [
    "pages/Index"
  ]
}

它和 loadContent('pages/Index') 对应起来。也就是说，项目中首页路径在配置和代码中保持一致。

全场景应用可能会有更多页面，但无论页面多少，注册和加载链路都必须清晰。当前项目只有一个首页，正好适合讲清楚最小链路。

页面展示：Index.ets 📱

首页代码位于：

entry/src/main/ets/pages/Index.ets

核心代码如下：

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    RelativeContainer() {
      Text(this.message)
        .onClick(() => {
          this.message = 'Welcome';
        })
    }
    .height('100%')
    .width('100%')
  }
}

当前页面很简单，但已经具备入口页面的基本结构：

1. @Entry。
2. @Component。
3. @State。
4. build()。
5. 交互事件。

这说明页面层已经能响应状态变化。后续如果做全场景适配，可以在这个基础上继续扩展布局和交互。

日志让入口链路可观察 🔍

当前项目在 EntryAbility 中保留了生命周期日志：

hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');

这些日志虽然简单，但对入口链路很有帮助。后续如果入口场景更多，页面加载路径也更复杂，基础日志可以帮助判断问题发生在 Ability 创建、窗口创建，还是页面加载阶段。

当前日志没有输出用户隐私数据，主要是流程状态。这种写法比较适合基础项目。

从入口链路看全场景基础 🧭

可以把当前项目的基础链路总结为：

app.json5
  -> 应用身份
module.json5
  -> 模块入口与设备类型
EntryAbility.ets
  -> 生命周期与窗口加载
main_pages.json
  -> 页面注册
Index.ets
  -> 页面展示与交互

这条链路虽然简单，但非常关键。

如果未来扩展更多设备、更多页面或更多入口场景，仍然要围绕这条链路展开。比如：

1. 不同设备是否进入同一个首页？
2. 页面是否根据设备调整布局？
3. 资源是否根据场景切换？
4. 日志是否能定位入口问题？
5. 页面注册是否保持清晰？

当前项目的真实边界 📌

当前项目没有实现完整跨端系统能力，也没有形成多设备体验闭环。

当前项目实现的是：

1. 应用入口配置。
2. 模块入口配置。
3. Ability 生命周期。
4. 首页加载。
5. 基础页面交互。

当前项目没有接入更高级的跨端系统能力，因此本文只把它作为入口链路案例。这样定位更真实，也更适合当前工程状态。

因此，这篇文章更适合写“全场景应用基础链路”，而不是“全场景能力实战”。

为什么这也属于创新体验？🚀

创新体验的底层是稳定链路。一个应用如果连入口、加载、页面注册都不清楚，就很难扩展到更多场景。

当前项目通过最小代码展示了从应用入口到页面展示的完整路径。它不炫，但真实。理解这条路径之后，再学习更多 HarmonyOS 全场景能力，会更容易知道能力应该接在哪一层。

总结 🌈

这篇文章对应 创新体验 方向。

当前项目没有实现完整全场景能力，但它有一条清晰的应用入口链路：

app.json5 -> module.json5 -> EntryAbility -> main_pages -> Index

全场景应用不是从高级能力开始的，而是从稳定入口、清晰页面加载和合理工程结构开始的。当前项目虽然基础，但正适合用来理解这条链路。