当前位置：首页 > news >正文

HarmonyOS应用配置文件与资源组织深度解析

news 2025/11/9 14:23:21

一、应用程序包结构概述

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）：

<DirectionalLayoutxmlns: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）：

<DirectionalLayoutxmlns:ohos="http://schemas.huawei.com/res/ohos"ohos:width="match_parent"ohos:height="match_parent"ohos:orientation="horizontal"><!-- 平板端双列布局 -->
</DirectionalLayout>