配置文件概述
本文以Stage模型为例，详细介绍了HarmonyOS NEXT应用的各种配置文件，这些配置文件会向编译工具、操作系统和应用市场提供应用的基本信息。
在基于Stage模型开发的应用项目代码下，都存在一个app.json5的配置文件、以及一个或者多个module.json5配置文件。
应用配置文件
app.json5配置文件
先通过一个示例，整体认识下app.json5配置文件。
{"app": {"bundleName": "com.application.myapplication","vendor": "example","versionCode": 1000000,"versionName": "1.0.0","icon": "$media:app_icon","label": "$string:app_name","description": "$string:description_application","minAPIVersion": 9,"targetAPIVersion": 9,"apiReleaseType": "Release","debug": false,"car": {"minAPIVersion": 8},"targetBundleName": "com.application.test","targetPriority": 50,"appEnvironments": [{"name":"name1","value": "value1"}],"maxChildProcess": 5},
}
app.json5配置文件主要包含一下内容：
- 应用的全局配置信息，包含应用的Bundle名称、开发厂商、版本号等基本信息。
- 特定设备类型的配置信息。
具体属性如下表：
| 属性名称 | 属性含义 | 数据类型 | 是否必填 |
|---|---|---|---|
bundleName | 标识应用的Bundle名称，用于标识应用的唯一性。命名规则如下 ： - 由字母、数字、下划线和符号“.”组成，且必须以字母开头。 - 字符串最小长度为7字节，最大长度为128字节。 - 推荐采用反域名形式命名（如 com.example.demo，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。对于随系统源码编译的应用，建议命名为com.ohos.demo形式，其中的ohos标识系统应用。 | string | 是 |
bundleType | 标识应用的Bundle类型，用于区分应用或者元服务。支持的取值如下： - app：当前Bundle为应用。 - atomicService：当前Bundle为元服务。 shared：当前Bundle为共享库应用，预留字段。 - appService：当前Bundle为系统级共享库应用，仅供系统应用使用。 | string | 否，默认值为app |
debug | 标识应用是否可调试。 - true：可以进行断点调试。 - false：不可以进行断点调试。 | Boolean | 否，默认值为false |
icon | 标识应用的图标，取值为图标资源文件的索引。 | string | 是 |
label | 标识应用的名称，取值为字符串资源的索引，字符串长度不超过63字节。 | string | 是 |
description | 标识应用的描述信息。取值为长度不超过255字节的字符串，内容为描述信息的字符串资源索引。 | string | 否，默认值为空 |
versionCode | 标识应用的版本号，取值为小于2^31的正整数。此数字仅用于确定某个版本是否比另一个版本更新，数值越大标识版本越高。 开发者可以将该值设置为任何正整数，但是必须确保应用的新版本都使用比旧版本更大的值。 | number | 是 |
versionName | 标识向用户展示的应用版本号。 取值为长度不超过127字节的字符串，仅由数字和点构成，推荐采用“A.B.C.D"四段式的形式。四段式推荐的含义如下所示。 第一段：主版本号/Major，范围0~99，重大修改的版本，如实现新的大功能或重大变化。 第二段：次版本号/Minor，范围0~99，表示实现较突出的特点，如新功能添加或大问题修复。 第三段：特性版本号/Feature，范围0~99，标识规划的新版本特性。 第四段：修订版本号/Parch，范围0~999，表示维护版本，如修复bug。 | string | 是 |
minCompatibleVersionCode | 标识应用能够兼容的最低历史版本号，用于应用跨设备兼容性判断，取值范围为0~2147483647。 | number | 否，默认值为versionCode标签的值。 |
minAPIVersion | 标识应用运行需要的SDK的API最小版本。取值范围为0~2147482647 | number | 应用编译构建时由build-profile.json5中的compatibleSdkVersion自动生成。 |
targetAPIVersion | 标识应用运行需要的API目标版本。取值范围为0~2147483647。 | number | 应用编译构建时由build-profile.json5中的compileSdkVersion自动生成。 |
apiReleaseType | 标识应用运行需要的API目标版本的类型，采用字符串类型表示。取值为”CaneryN"、“BetaN”或者“Release”，其中，N代表大于零的整数。 - Canary：受限发布的版本。 - Beta：公开发布的 Beta版本。- Release：公开发布的正式版本。 | string | 应用编译构建时根据当前使用的SDK的Stage自动生成。即便手动配置了取值，编译构建时也会被覆盖。 |
accessible | 标识应用是否能访问应用的安装目录，仅针对Stage模型的系统应用和预置应用生效。 | boolean | 否，默认值为false。 |
multiProjects | 标识当前工程是否支持多个工程的联合开发。 true：当前工程支持多个工程的联合开发。 - false：当前工程不支持多个工程的联合开发。 | 否，默认值为false。 | |
asanEnabled | 标识应用程序是否开启asan检测，用于辅助定位buffer越界造成的crash问题。- true：当前工程开启 asan检测。- false：当前工程不开启 asan检测。 | boolean | 否，默认值为false。 |
tablet | 标识对tablet设备做的特殊配置，可以配置的属性字段有minAPIVersion。如果使用该属性对tablet设备做了特殊配置，则应用在tablet设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | object | 否，默认值为app.json5公共区域配置的属性值。 |
tv | 标识对tv设备做的特殊配置，可以配置的属性字段有minAPIVersion。如果使用该属性对tv设备做了特殊配置，则应用在tv设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | object | 否，默认值为app.json5公共区域配置的属性值。 |
wearable | 标识对wearable设备做的特殊配置，可以配置的属性字段有minAPIVersion。如果使用该属性对wearable设备做了特殊配置，则应用在wearable设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | object | 否，默认值为app.json5公共区域配置的属性值。 |
car | 标识对car设备做的特殊配置，可以配置的属性字段有minAPIVersion。如果使用该属性对car设备做了特殊配置，则应用在car设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | object | 否，默认值为app.json5公共区域配置的属性值。 |
default | 标识对default设备做的特殊配置，可以配置的属性字段有minAPIVersion。如果使用该属性对default设备做了特殊配置，则应用在default设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | object | 否，默认值为app.json5公共区域配置的属性值。 |
targetBundleName | 标识当前包所指定的目标应用，标签值的取值规则和范围与bundleName标签一致。配置该字段的应用为具有overlay特征的应用 | string | 否，默认值为空。 |
targetPriority | 标识当前应用的优先级，取值范围为1~100。配置targetBundleName字段之后，才支持配置该字段。 | number | 否，默认值为1。 |
generateBuildHash | 标识当前应用的所有HAP和HSP是否由打包工具生成哈希值。该字段配置为true时，该应用下的所有HAP和HSP都会由打包工具生成对应的哈希值。系统OTA升级时，若应用的versionCode保持不变，可根据哈希值判断应用是否需要升级。说明：该字段仅对预置应用生效。 | boolean | 否，默认值为false。 |
GWPAsanEnabled | 标识应用程序是否开启GWP-asan堆内存检测工具，用于对内存越界、内存释放后使用等内存破坏问题进行分析。- true：当前工程开启 GWP-asan检测。- false：当前工程不开启 GWP-asan检测。 | boolean | 否，默认值为false。 |
appEnvironments | 标识当前模块配置的应用环境变量。 | Array | 否，默认值为空。 |
maxChildProcess | 标识当前应用自身可创建的子进程的最大个数，取值范围为0~512，0表示不限制，当应用有多个模块时，以entry模块的配置为准。 | number | 否，默认使用系统配置的默认值。 |
module.json5配置文件
先通过一个示例，整体认识下module.json5配置文件。
{"module": {"name": "entry","type": "entry","description": "$string:module_desc","mainElement": "EntryAbility","deviceTypes": ["tv","tablet"],"deliveryWithInstall": true,"installationFree": false,"pages": "$profile:main_pages","virtualMachine": "ark","metadata": [{"name": "string","value": "string","resource": "$profile:distributionFilter_config"}],"abilities": [{"name": "EntryAbility","srcEntry": "./ets/entryability/EntryAbility.ts","description": "$string:EntryAbility_desc","icon": "$media:icon","label": "$string:EntryAbility_label","startWindowIcon": "$media:icon","startWindowBackground": "$color:start_window_background","exported": true,"skills": [{"entities": ["entity.system.home"],"actions": ["ohos.want.action.home"]}]}],"requestPermissions": [{"name": "ohos.abilitydemo.permission.PROVIDER","reason": "$string:reason","usedScene": {"abilities": ["FormAbility"],"when": "inuse"}}]},"targetModuleName": "feature","targetPriority": 50,"isolationMode": "nonisolationFirst"
}
module.json5配置文件主要包含以下内容：
Module的基本配置信息，包含Module名称、类型、描述、支持的设备类型等基本信息。- 应用组件信息，包含UIAbility组件和ExtensionAbility组件的描述信息。
- 应用运行过程中所需的权限信息。
具体属性如下表：
| 属性名称 | 属性含义 | 数据类型 | 是否必输 |
|---|---|---|---|
name | 标识当前Module的名称，确保该名称在整个应用中唯一。取值为长度不超过31字节的字符串，不支持中文。应用升级时允许修改该名称，但需要应用适配Module相关数据目录的迁移 | string | 是 |
type | 标识当前Module的类型。支持的取值如下：- entry：应用的主模块。 - feature：应用的动态特性模块。 *- har*：静态共享包模块。 - shared：动态共享包模块。 | string | 是 |
srcEntry | 标识当前Module所对应的代码路径，取值为长度不超过127字节的字符串。 | string | 否，默认值为空。 |
description | 标识当前Module的描述信息，取值为长度不超过255字节的字符串，可以采用字符串资源索引格式。 | string | 否，默认值为空。 |
process | 标识当前Module的进程名，取值为长度不超过31字节的字符串。如果在HAP标签下配置了process，则该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。说明：仅支持系统应用配置，第三方应用配置不生效。 | string | 否，默认值为app.json5文件下app标签下的bundleName。 |
mainElement | 标识当前Module的入口UIAbility名称或者ExtensionAbility名称，取值为长度不超过255字节的字符串。 | string | 否，默认值为空。 |
deviceTypes | 标识当前Module可以运行在哪类设备上。 | Array | 是 |
deliveryWithInstall | 标识当前Module是否在用户主动安装的时候安装，即该Module对应的HAP是否跟随应用一起安装。- true：主动安装时安装。 - false：主动安装时不安装 | boolean | 是 |
installationFree | 标识当前Module是否支持免安装特性。- true：表示支持免安装特性，且符合免安装约束。 - false：表示不支持免安装特性。 说明：当 bundleType为元服务时，该字段需要配置为true。反之，该字段需要配置为false。 | boolean | 是 |
virtualMachine | 标识当前Module运行的目标虚拟机类型，仅供云端分发使用，如应用市场和分发中心。如果目标虚拟机类型为ArkTS引擎，则其值为“ark+版本号”。 | string | 该标签由IDE构建HAP的时候自动插入。 |
pages | 标识当前Module的profile资源，用于列举每个页面信息，取值为长度不超过255字节的字符串。 | string | 在有UIAbility的场景下，该标签必输。 |
metadata | 标识当前Module的自定义元信息，可通过资源引用的方式配置distributionFilter、shortcuts等信息。只对当前Module、UIAbility、ExtensionAbility生效。 | Array | 否，默认值为空。 |
abilities | 标识当前Module中UIAbility的配置信息，只对当前UIAbility生效。 | Array | 否，默认值为空。 |
extensionAbilities | 标识当前Module中ExtensionAbility的配置信息，只对当前ExtensionAbility生效。 | Array | 否，默认值为空。 |
definePermissions | 标识系统资源hap定义的权限，不支持应用自定义权限。 | Array | 否，默认值为空。 |
requestPermissions | 标识当前应用运行时需向系统申请的权限集合。 | Array | 否，默认值为空。 |
testRunner | 标识用于测试当前Mobule的测试框架的配置。 | object | 否，默认值为空。 |
atomicService | 标识当前应用是元服务时，有关元服务的相关配置。 | object | 否 |
dependencies | 标识当前模块运行时依赖的共享库列表。 | Array | 否，默认值为空。 |
targetModuleName | 标识当前包所指定的目标module，确保该名称在整个应用中唯一。取值为长度不超过31字节的字符串，不支持中文。配置该字段的Module具有overlay特性。仅在动态共享包(HSP)中适用。 | string | 否，默认值为空。 |
targetPriority | 标识当前Module的优先级，取值范围为1~100。配置targetModuleName字段之后才需要配置该字段。仅在动态共享包（HSP）中适用。 | Integer | 否，默认值为1。 |
proxyData | 标识当前Module提供的数据代理列表 | Array | 否，默认值为空。 |
isolationMode | 标识当前Module的多进程配置项。支持的取值如下：- nonisolationFirst：优先在非独立进程中进行。 - isolationFirst：优先在独立进程中运行。 - isolationOnly：只在独立进程中运行。 - nonisolationOnly：只在非独立进程中运行。 | string | 否，默认值为nonisolationFirst。 |
generateBuildHash | 标识当前HAP/HSP是否由打包工具生成哈希值。当配置为trrue时，如果系统OTA升级时应用versionCode保持不变，可根据哈希值判断应用是否需要升级。该字段仅在app.json5文件中的generateBuildHash字段为false时生效。说明：该字段仅对预置应用生效。 | boolean | 否，默认值为false。 |
compressNativeLibs | 标识libs库是否以压缩存储的方式打包到HAP。 - true：libs库以压缩方式存储。 - false：libs库以不压缩方式存储。 | boolean | 否，默认值为false。 |
libIsolation | 用于区分同应用不同HAP下的.so文件，以防止.so冲突。 - true：当前HAP的.so文件会存储在libs目录中以 Module命名的路径下。- false：当前HAP的.so文件会直接存储在libs目录下。 | string | 否，默认值为false。 |
fileContextMenu | 标识当前HAP的右键菜单配置项。取值为长度不超过255字节的字符串。 | string | 否，默认值为空。 |
querySchemes | 标识允许当前应用进行跳转查询的URL schemes，只允许entry类型模块配置，最多50个，每个字符串取值不超过128字节。 | Array | 否，默认值为空。 |
routerMap | 标识当前模块配置的路由表路径。取值为长度不超过255字节的字符串 | string | 否，默认值为空。 |
appEnvironments | 标识当前模块配置的应用环境变量，只允许entry和feature模块配置。 | Array | 否，默认值为空。 |
appStartup | 标识当前Module启动框架配置路径，仅在Entry中生效。 | string | 否，默认值为空。 |
资源配置文件
资源分类
应用开发中使用的各类资源文件，需要放入特定子目录中存储管理。资源目录的示例如下所示，base目录、限定词目录、rawfile目录、resfile目录称为资源目录，element、media、profile称之为资源组目录。
resources
|---base
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---en_US // 默认存在的目录，设备语言环境是美式英文时，优先匹配此目录下资源
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---zh_CN // 默认存在的目录，设备语言环境是简体中文时，优先匹配此目录下资源
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---en_GB-vertical-car-mdpi // 自定义限定词目录示例，由开发者创建
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---rawfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。
|---resfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。
)
