玩转HarmonyOS NEXT之配置文件篇

配置文件概述

本文以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文件中。文件名可自定义。

配置文件概述

应用配置文件

app.json5配置文件

module.json5配置文件

资源配置文件

资源分类

相关推荐

最近更新

热门阅读

`app.json5`配置文件

`module.json5`配置文件