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

【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@Componentstruct Index {@Statemessage: 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，视觉参数在资源目录。

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