HarmonyOS应用配置文件与资源组织深度解析
一、应用程序包结构概述
HarmonyOS应用以APP Pack形式发布，它由一个或多个HAP以及描述每个HAP属性的pack.info组成。HAP是Ability的部署包，可分为entry和feature两种类型。
Entry类型的HAP是应用的主模块，一个应用中对于同一设备类型必须有且只有一个entry类型的HAP，可独立安装运行。Feature类型的HAP是应用的动态特性模块，一个APP可以包含一个或多个feature类型的HAP，也可以不含。
二、配置文件详解
2.1 配置文件层次结构
每个HAP的根目录下都存在配置文件，文件内容主要涵盖以下三个方面：
- 应用全局配置信息：包含应用的包名、生产厂商、版本号等基本信息
- 设备特定配置：包含应用在具体设备上的配置信息
- 模块配置信息：包含每个Ability必须定义的基本属性
2.2 app.json5与module.json5对比
在API 12中，HarmonyOS使用app.json5和module.json5替代传统的config.json文件。这两种配置文件的分工如下：
| 配置文件 | 存放位置 | 主要功能 |
|---|---|---|
| app.json5 | AppScope目录下 | 声明应用的全局配置信息，如应用Bundle名称、应用版本号等 |
| module.json5 | 各Module的src/main目录下 | 声明Module基本信息、支持的设备类型、所含的组件信息等 |
app.json5示例配置：
{
"app": {
"bundleName": "com.example.myapp",
"vendor": "example",
"version": {
"code": 1,
"name": "1.0.0"
},
"apiVersion": {
"compatible": 12,
"target": 12,
"releaseType": "Release"
}
}
}
module.json5示例配置：
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"deviceTypes": [
"phone",
"tablet"
],
"distro": {
"deliveryWithInstall": true,
"moduleName": "entry",
"moduleType": "entry"
},
"abilities": [
{
"name": "MainAbility",
"srcEntry": "./ets/entryability/MainAbility.ets",
"description": "$string:mainability_desc",
"icon": "$media:icon",
"label": "$string:app_name",
"startWindowIcon": "$media:icon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
]
}
]
}
}
三、资源文件管理
3.1 资源目录结构
应用的资源文件统一存放于resources目录下，包括base目录与限定词目录。资源目录采用两级结构组织：
一级子目录：
- base目录：默认存在，当没有匹配的限定词目录时自动引用
- rawfile目录：支持自定义子目录，资源不编译直接打包
二级资源目录示例：
resources
|---base
| |---element // 元素资源（字符串、颜色等）
| |---media // 媒体资源
| |---profile // 原始文件资源
|---rawfile // 原生资源目录
3.2 资源限定词规则
限定词目录由一个或多个表征应用场景或设备特征的限定词组合而成，组合顺序为：移动国家码和移动网络码-语言*文字*国家或地区-横竖屏-设备类型-颜色模式-屏幕密度。
限定词配置示例：
// 在module.json5中配置支持设备
"deviceTypes": [
"phone",
"tablet",
"car",
"wearable"
]
3.3 资源访问方式
在代码中访问资源需要使用$r方法：
// 访问字符串资源
Text($r('app.string.hello_world'))
// 访问图片资源
Image($r('app.media.app_icon'))
// 访问尺寸资源
.width($r('app.float.element_size'))
四、模块化工程配置
4.1 三层工程结构
官方推荐采用"三层工程结构"，实现代码的高效组织和复用：
- common层（公共能力层）：包含工具库、公共配置、通用常量等基础能力
- features层（业务模块层）：各业务模块，高内聚低耦合，供products层选择性引用
- products层（产品定制层）：针对不同设备形态的入口模块
4.2 模块依赖管理
在HarmonyOS工程中，使用oh-package.json5文件管理依赖：
引用本地模块：
{
"dependencies": {
"@ohos/utils": "file:../common/utils"
}
}
引用OHPM仓库三方包：
{
"dependencies": {
"@ohos/lottie": "^2.0.12"
}
}
也可以通过命令行添加依赖：
ohpm install @ohos/lottie
五、实战：多设备适配配置
5.1 多设备布局适配
利用资源限定词为不同设备提供差异化布局：
phone设备布局（/base/layout/main_page.xml）：
<DirectionalLayout
xmlns:ohos="http://schemas.huawei.com/res/ohos"
ohos:width="match_parent"
ohos:height="match_parent"
ohos:orientation="vertical">
<!-- 手机端单列布局 -->
</DirectionalLayout>
tablet设备布局（/tablet/layout/main_page.xml）：
<DirectionalLayout
xmlns:ohos="http://schemas.huawei.com/res/ohos"
ohos:width="match_parent"
ohos:height="match_parent"
ohos:orientation="horizontal">
<!-- 平板端双列布局 -->
</DirectionalLayout>
5.2 配置文件合并规则
当应用模块引用HAR时，在编译构建HAP时需要将HAP的配置文件与HAR的配置文件合并。合并规则如下：
- HAP的优先级总是高于HAR
- 当HAP依赖多个HAR时，先加载的HAR优先级高于后加载的HAR
- 合并冲突时按照优先级顺序解决
六、编译与发布配置
6.1 编译过程文件变化
从开发态到编译态，Module中的文件会发生如下变更：
- ets目录：ArkTS源码编译生成.abc文件
- resources目录：AppScope目录下的资源文件会合入到Module下面的资源目录
- 配置文件：app.json5字段会合入到module.json5中，生成最终的module.json
6.2 发布包结构
应用发布上架时，Bundle打包为.app文件（App Pack），同时生成pack.info文件。pack.info描述了App Pack中每个HAP和HSP的属性。
总结
正确的配置和资源管理是HarmonyOS应用开发的基础。通过合理使用配置文件和资源限定词，可以高效实现多设备适配。三层工程结构和模块化依赖管理为大型项目开发提供了良好的可维护性基础。
需要参加鸿蒙认证的请点击 鸿蒙认证链接
浙公网安备 33010602011771号