鸿蒙OS 配置文件的元素：从结构到实战
1. 引言
在鸿蒙OS（HarmonyOS）应用开发中，配置文件是连接应用代码与系统能力的桥梁。无论是应用的基础信息、模块声明，还是页面路由、权限申请，都需要通过配置文件来声明。理解配置文件的元素结构，是每一位鸿蒙开发者入门的第一步。
本文将从鸿蒙OS配置文件的整体结构出发，逐一拆解其中的核心元素，并结合丰富的代码实例，帮助你在实际项目中快速上手。
2. 配置文件概述
鸿蒙OS应用的配置文件主要分为两类：
- 应用级配置文件：通常为
app.json5，用于声明应用的全局信息，如应用名称、版本号、图标等。 - 模块级配置文件：通常为
module.json5，用于声明模块的详细信息，如入口页面、权限、能力等。
此外，还有用于页面路由的 main_pages.json，以及用于描述服务卡片、后台任务等的专项配置文件。本文重点讲解 app.json5 和 module.json5 中的核心元素。
3. 应用级配置文件 app.json5
app.json5 位于工程的 AppScope 目录下，是整个应用的“身份证”。它声明了应用的基本属性，系统在安装、运行应用时会读取这些信息。
3.1 基本结构
一个典型的 app.json5 文件如下所示：
{
"app": {
"bundleName": "com.example.myapplication",
"vendor": "example",
"versionCode": 1000000,
"versionName": "1.0.0",
"icon": "$media:app_icon",
"label": "$string:app_name"
}
}
3.2 核心元素解析
| 元素 | 类型 | 说明 |
|---|---|---|
bundleName | string | 应用包名，全局唯一，用于标识应用。 |
vendor | string | 应用供应商名称。 |
versionCode | number | 应用版本号（整数），用于版本比较和升级判断。 |
versionName | string | 应用版本名称，展示给用户看的版本号。 |
icon | string | 应用图标资源引用。 |
label | string | 应用名称资源引用。 |
其中，icon 和 label 通常使用资源引用方式，而不是直接写死字符串，这样便于多语言适配和资源管理。
4. 模块级配置文件 module.json5
module.json5 位于每个模块的 src/main/module.json5 路径下，描述了模块的能力和入口。一个模块可以包含多个 module 对象，但通常一个工程只有一个主模块。
4.1 基本结构
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone",
"tablet"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:icon",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
]
}
],
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]
}
}
4.2 核心元素解析
| 元素 | 类型 | 说明 |
|---|---|---|
name | string | 模块名称，同一应用内唯一。 |
type | string | 模块类型，如 entry（应用入口模块）、feature（功能模块）。 |
mainElement | string | 模块入口能力（Ability）名称。 |
deviceTypes | array | 支持的设备类型列表。 |
deliveryWithInstall | boolean | 是否随应用安装时一起交付。 |
installationFree | boolean | 是否支持免安装运行。 |
pages | string | 页面路由配置文件引用。 |
abilities | array | 模块内所有 Ability 的声明列表。 |
requestPermissions | array | 模块运行时需要的权限列表。 |
5. 页面路由配置文件 main_pages.json
main_pages.json 用于声明模块内的页面路由，是页面跳转的基础。它通常位于 src/main/resources/base/profile/main_pages.json。
{
"src": [
"pages/Index",
"pages/Detail",
"pages/About"
]
}
这里的 src 数组列出了所有页面组件的路径，路径相对于 src/main/ets 目录。页面跳转时，通过 router.pushUrl 传入对应的路径字符串即可。
6. 权限声明元素
在鸿蒙OS中，权限声明是配置文件的重要部分。权限分为系统权限和应用自定义权限，声明方式如下：
6.1 请求系统权限
"requestPermissions": [
{
"name": "ohos.permission.INTERNET",
"reason": "$string:reason_internet",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when": "inuse"
}
},
{
"name": "ohos.permission.CAMERA",
"reason": "$string:reason_camera",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when": "always"
}
}
]
6.2 声明自定义权限
如果应用需要暴露自定义能力给其他应用，可以在 module.json5 中声明自定义权限：
"requestPermissions": [
{
"name": "com.example.myapp.permission.START_MY_SERVICE",
"reason": "$string:reason_start_service",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when": "inuse"
}
}
]
同时，在提供能力的 Ability 中，通过 permissions 字段声明该能力需要的权限：
{
"name": "ServiceAbility",
"srcEntry": "./ets/serviceability/ServiceAbility.ets",
"permissions": [
"com.example.myapp.permission.START_MY_SERVICE"
]
}
7. 设备类型与分发元素
鸿蒙OS支持多种设备形态，通过 deviceTypes 字段声明模块支持的设备类型。常见的设备类型包括：
phone：手机tablet：平板tv：智慧屏wearable：智能穿戴car：车机
"deviceTypes": [
"phone",
"tablet",
"tv"
]
此外，deliveryWithInstall 和 installationFree 控制模块的分发方式：
deliveryWithInstall为true时，模块随应用安装时交付；为false时，模块按需下载。installationFree为true时，支持免安装运行，即用户无需安装即可使用。
8. 实战：完整配置示例
下面给出一个完整的实战配置示例，包含应用级和模块级配置，以及对应的页面路由和权限声明。
8.1 app.json5
{
"app": {
"bundleName": "com.example.healthapp",
"vendor": "example",
"versionCode": 2000000,
"versionName": "2.0.0",
"icon": "$media:app_icon",
"label": "$string:app_name"
}
}
8.2 module.json5
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "MainAbility",
"deviceTypes": [
"phone",
"tablet"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "MainAbility",
"srcEntry": "./ets/mainability/MainAbility.ets",
"description": "$string:MainAbility_desc",
"icon": "$media:icon",
"label": "$string:MainAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
]
},
{
"name": "HealthServiceAbility",
"srcEntry": "./ets/serviceability/HealthServiceAbility.ets",
"description": "$string:HealthService_desc",
"icon": "$media:icon",
"label": "$string:HealthService_label",
"exported": false,
"permissions": [
"com.example.healthapp.permission.READ_HEALTH_DATA"
]
}
],
"requestPermissions": [
{
"name": "ohos.permission.INTERNET",
"reason": "$string:reason_internet",
"usedScene": {
"abilities": [
"MainAbility"
],
"when": "inuse"
}
},
{
"name": "ohos.permission.HEALTH_DATA",
"reason": "$string:reason_health",
"usedScene": {
"abilities": [
"MainAbility"
],
"when": "always"
}
}
]
}
}
8.3 main_pages.json
{
"src": [
"pages/Index",
"pages/HealthData",
"pages/Settings"
]
}
9. 常见问题与注意事项
- bundleName 必须唯一：应用包名在鸿蒙生态中全局唯一，发布前务必确认不与已有应用冲突。
- 资源引用优先：
icon、label、description等字段尽量使用资源引用（如$string:app_name），便于多语言和主题适配。 - 权限最小化：只申请应用实际需要的权限，避免过度申请导致用户信任度下降。
- 版本号规范：
versionCode是整数且只能递增，versionName是展示字符串，两者需同步维护。 - 页面路径正确性：
main_pages.json中的路径必须与ets目录下的实际文件路径一致，否则运行时会报路由错误。
10. 总结
鸿蒙OS配置文件是应用开发的基石，app.json5 定义了应用的全局身份，module.json5 声明了模块的能力与入口，main_pages.json 则管理着页面路由。掌握这些核心元素的含义和用法，能够帮助你在开发中少走弯路，构建出结构清晰、分发合理的鸿蒙应用。
建议读者在创建新工程后，先通读一遍自动生成的配置文件，再结合本文的示例逐步修改，这样能更快地建立起对鸿蒙OS配置体系的整体认知。
讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。
更多推荐
1
0- 0
已为社区贡献2条内容
所有评论(0)