【HarmonyOS/OpenHarmony】能力增强：StageMode 工程如何为多设备扩展打基础

前言 🌟

HarmonyOS / OpenHarmony 的全场景体验，离不开清晰的工程结构。很多人一提到多设备扩展，就会先想到复杂 API、分布式能力或跨端流转。但在真实项目里，第一步往往是工程结构是否清楚。

当前项目是一个 StageMode ArkTS 工程，虽然目前只面向 phone 设备，但它已经具备应用级配置、模块配置、Ability、页面和资源目录。这些结构并不等于已经实现多设备协同，但它们确实为后续扩展提供了基础。

本文对应四大主题中的 能力增强。

当前项目的 StageMode 基础结构 📦

当前项目主要结构包括：

AppScope/
entry/
build-profile.json5
oh-package.json5
hvigor/
code-linter.json5

其中 entry 模块下有：

entry/src/main/ets/entryability/EntryAbility.ets
entry/src/main/ets/pages/Index.ets
entry/src/main/resources/
entry/src/main/module.json5

这说明项目不是把所有内容都堆在一个文件里，而是按应用、模块、页面、资源做了基本拆分。

AppScope：应用级信息的统一入口 🧩

AppScope/app.json5 中包含：

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

这些配置属于应用级信息。无论后续是否扩展更多设备，应用名称、图标、包名、版本号都是基础身份。

如果未来做多设备适配，应用级信息仍然是统一入口。也就是说，全场景不是每个设备各搞一套，而是在统一应用身份下，针对不同设备做合理适配。

entry 模块：当前应用能力的承载者 📱

当前项目只有一个 entry 模块，它承担了主要运行能力：

1. 主 Ability。
2. 首页页面。
3. 资源文件。
4. 备份扩展。
5. 测试目录。

module.json5 中声明：

"type": "entry",
"mainElement": "EntryAbility",
"deviceTypes": [
  "phone"
]

这说明当前模块是入口模块，并且目前面向手机设备。

如果未来扩展多设备体验，可以继续基于这个模块演进，也可以根据项目规模拆分更多模块。但当前阶段，一个清晰的 entry 模块已经足够支撑基础开发。

Ability 与页面分离的价值 ⚙️

当前项目中，EntryAbility.ets 负责窗口和页面加载：

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

首页 UI 则在 Index.ets 中：

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

这种分离对多设备扩展很重要。Ability 负责入口和生命周期，页面负责 UI 展示。后续如果不同设备需要不同页面布局，可以优先调整页面层，而不必把所有逻辑塞进 Ability。

资源目录为多设备视觉适配留空间 🎨

当前项目资源目录包含：

resources/base/element/string.json
resources/base/element/float.json
resources/base/element/color.json
resources/dark/element/color.json
resources/base/media/layered_image.json

其中首页字号使用资源：

.fontSize($r('app.float.page_text_font_size'))

启动背景也使用资源：

"startWindowBackground": "$color:start_window_background"

这些写法说明项目已经不是完全硬编码视觉参数。对多设备扩展来说，资源化非常重要，因为不同设备、不同主题、不同显示环境可能需要不同视觉策略。

当前项目还没有完整多设备资源体系，但已经有资源化的基础。

StageMode 对扩展的意义 🚀

StageMode 工程结构的价值在于，它让应用能力、页面、资源、配置之间有清晰边界。

当前项目可以串成这样：

AppScope/app.json5
  -> 应用身份
entry/module.json5
  -> 模块能力
EntryAbility.ets
  -> 生命周期和页面加载
main_pages.json
  -> 页面注册
Index.ets
  -> UI 展示
resources
  -> 字符串、字号、颜色、图标

这条链路清楚以后，后续扩展多设备时就能知道该改哪里：

1. 设备范围看 module.json5。
2. 页面入口看 EntryAbility。
3. 页面展示看 Index.ets。
4. 视觉参数看 resources。
5. 构建目标看 build-profile.json5。

多设备扩展时不要打乱边界 ⚠️

如果未来项目要面向更多设备，最容易出现的问题是把所有适配逻辑都写进一个页面。比如在 Index.ets 里同时处理设备判断、页面布局、数据获取、资源切换和日志输出。短期看能跑，长期会很难维护。

更稳妥的方式是保持边界：

1. 设备声明仍然放在模块配置中。
2. 页面只负责展示和交互。
3. 资源变化交给资源目录。
4. 生命周期仍由 Ability 管理。
5. 构建和 SDK 范围交给 build-profile。

当前项目虽然小，但这些边界已经存在。继续扩展时应该沿着已有结构往前走，而不是把代码堆到一个文件里。

当前项目的真实边界 📌

需要明确：

当前项目还没有实现：

1. 多设备协同。
2. 跨设备流转。
3. 分布式数据同步。
4. 多端自适应 UI。
5. 全场景智慧生活能力。

当前项目具备的是：

1. StageMode 基础结构。
2. phone 设备配置。
3. Ability 和页面分离。
4. 资源化基础。
5. 构建和模块配置。

所以这篇文章要写“打基础”，不要写“已完成”。

当前结构对 CSDN 文章的价值 📝

这篇文章的亮点不是展示复杂功能，而是帮读者理解工程底座。对于很多刚接触 HarmonyOS / OpenHarmony 的开发者来说，目录结构比 API 本身更容易造成困惑。

通过当前项目，可以把 AppScope、entry、module.json5、EntryAbility、resources 串起来讲清楚。读者理解这些关系后，再去学习多设备适配，就不会只停留在“改一个字段”的层面。

后续可以怎样演进？✅

如果继续向多设备方向做，可以考虑：

1. 在页面层做响应式布局。
2. 扩展更多资源 token。
3. 根据设备类型设计不同信息密度。
4. 把公共组件抽离，方便多页面复用。
5. 结合官方文档逐步验证更多设备类型支持。

这些都可以在当前 StageMode 工程基础上逐步进行。

总结 🌈

这篇文章对应 能力增强 方向。

当前项目虽然还只是手机端基础应用，但 StageMode 工程结构已经让应用具备清晰边界。应用信息在 AppScope，模块能力在 module.json5，入口逻辑在 EntryAbility，页面 UI 在 Index.ets，视觉参数在资源目录。

全场景能力不是凭空出现的，它需要工程结构先站稳。当前项目的价值就在于：虽然功能简单，但结构清楚，后续继续扩展多设备体验时有明确落点。