【HarmonyOS/OpenHarmony】能力增强：面向全场景扩展的项目配置清单

前言 🌟

如果一个 OpenHarmony 项目未来想走向全场景扩展，不能只盯着页面代码。应用级配置、模块配置、设备类型、构建版本、资源目录、页面注册、日志和安全检查，都需要提前梳理。

当前项目还没有实现完整全场景能力，但它已经有不少基础配置文件，非常适合整理成一份“面向全场景扩展的项目配置清单”。

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

清单一：应用身份配置 app.json5 📦

文件位置：

AppScope/app.json5

当前核心配置：

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

检查点：

1. 包名是否稳定。
2. 应用名称是否走资源引用。
3. 图标是否走媒体资源。
4. 版本号是否便于后续迭代。
5. vendor 是否仍是示例值。

当前项目中 vendor 还是 example，说明还处于基础工程阶段。后续正式化时可以替换为真实信息。

清单二：模块与设备配置 module.json5 📱

文件位置：

entry/src/main/module.json5

关键配置：

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

检查点：

1. 主入口 Ability 是否明确。
2. 当前设备类型是否符合实际项目。
3. 页面 profile 是否引用正确。
4. 扩展 Ability 是否按需配置。
5. 不需要对外暴露的能力是否设置边界。

当前项目只配置了 phone。因此它目前不是多设备应用，而是手机端基础应用。全场景扩展要从这里开始评估。

清单三：页面注册 main_pages.json ✅

文件位置：

entry/src/main/resources/base/profile/main_pages.json

当前配置：

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

检查点：

1. 页面路径是否正确。
2. EntryAbility 中 loadContent 路径是否一致。
3. 新增页面后是否同步注册。
4. 页面命名是否稳定。

当前项目只有 pages/Index 一个页面，适合作为最小页面链路案例。

清单四：构建版本 build-profile.json5 ⚙️

根目录构建配置包括：

"targetSdkVersion": "6.1.0(23)",
"compatibleSdkVersion": "6.0.2(22)",
"runtimeOS": "HarmonyOS"

检查点：

1. 目标 SDK 是否符合开发需求。
2. 兼容 SDK 是否和 API 使用匹配。
3. 运行系统是否明确。
4. strictMode 是否开启必要检查。
5. debug / release 构建模式是否清楚。

全场景扩展时，SDK 版本和 API 支持范围非常重要。不能只写代码，还要确认能力是否被目标版本支持。

清单五：资源分层 resources 🎨

当前项目已有：

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

检查点：

1. 文案是否资源化。
2. 字号是否资源化。
3. 颜色是否资源化。
4. 深色场景是否有基础覆盖。
5. 图标是否统一管理。

当前资源数量不多，但已经有分层基础。后续多场景视觉适配，可以继续扩展资源 token。

清单六：入口 Ability 与日志 🔍

主 Ability 中有：

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

检查点：

1. 页面加载失败是否有日志。
2. 生命周期是否有基础日志。
3. 日志是否避免输出敏感信息。
4. 错误信息是否便于定位问题。

全场景扩展时，入口问题更难排查。基础日志能帮助定位运行链路。

清单七：安全与质量配置 🔐

当前项目有：

code-linter.json5
entry/obfuscation-rules.txt

code-linter.json5 中包含安全规则，例如：

"@security/no-unsafe-aes": "error",
"@security/no-unsafe-hash": "error"

检查点：

1. ETS 文件是否纳入检查。
2. 安全规则是否启用。
3. 测试和 mock 目录是否合理忽略。
4. release 混淆配置是否明确。
5. 混淆是否需要在发布前开启。

当前项目有安全检查基础，但没有完整安全体系。写文章时要保持这个边界。

如何使用这份清单？🧭

这份清单适合在两个阶段使用。

第一，写文章时使用。每写到一个全场景相关观点，都回到项目文件中找依据。例如讲设备范围，就看 deviceTypes；讲入口链路，就看 EntryAbility 和 main_pages.json；讲视觉一致性，就看 resources。

第二，后续开发时使用。每次想扩展新能力，都先判断它会影响哪个层次：应用配置、模块配置、页面注册、资源、构建、日志还是安全检查。这样可以避免所有改动都堆在页面里。

对当前项目来说，这份清单最大的作用不是证明能力已经完整，而是帮助确认还差哪些基础能力。

面向全场景扩展的真实结论 📌

当前项目适合说：

项目具备全场景扩展的基础工程配置。

当前项目只是基础工程，具备配置、入口、资源、构建、安全检查等基础，但没有真正形成多设备协同体验。把这个边界讲清楚，文章会更可信。

后续扩展路线 🚀

如果后续继续做，可以按这个顺序：

1. 先完善手机端页面体验。
2. 再抽取通用资源和组件。
3. 再考虑不同屏幕尺寸布局。
4. 再研究更多设备类型支持。
5. 最后结合官方能力做跨设备体验。

这样会比一开始硬写全场景能力更真实，也更容易落地。

总结 🌈

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

面向全场景扩展，当前项目可以检查的配置包括：

1. app.json5
2. module.json5
3. main_pages.json
4. build-profile.json5
5. resources 资源目录
6. EntryAbility.ets
7. code-linter.json5
8. obfuscation-rules.txt

这些配置不会直接等于全场景能力，但它们是全场景扩展前必须打好的基础。工程底座越清楚，后续做多设备、多场景、多入口体验时就越稳。