鸿蒙OS开发文档鸿蒙OS 配置文件的元素

2024-02-25 开发教程鸿蒙OS开发文档匿名 30℃

此部分提供“config.json”文件中所有属性的详细解释。

配置文件的内部结构

应用的配置文件“config.json”中由“app”、“deviceConfig”和“module”三个部分组成，缺一不可。配置文件的内部结构说明参见表1。

表1 配置文件的内部结构说明

属性名称	含义	数据类型	是否可缺省
[app]	表示应用的全局配置信息。同一个应用的不同 HAP 包的“`app`”配置必须保持一致。	对象	否
[deviceConfig]	表示应用在具体设备上的配置信息。	对象	否
[module]	表示 HAP 包的配置信息。该标签下的配置只对当前 HAP 包生效。	对象	否

app对象的内部结构

app对象包含应用的全局配置信息，内部结构说明参见表2。

表2 app对象的内部结构说明

属性名称	子属性名称	含义	数据类型	是否可缺省
`bundleName`	-	表示应用的包名，用于标识应用的唯一性。采用反域名形式的字符串表示（例如，`com.huawei.himusic`）。建议第一级为域名后缀“`com`”，第二级为厂商/个人名，第三级为应用名，也可以采用多级。支持的字符串长度为`7~127`字节。	字符串	否
`vendor`	-	表示对应用开发厂商的描述。字符串长度不超过255字节。	字符串	可缺省，缺省值为空。
`version`	-	表示应用的版本信息。	对象	否
`code`	表示应用的版本号，仅用于 HarmonyOS 管理该应用，对用户不可见。取值为大于零的整数。	数值	否
`name`	表示应用的版本号，用于向用户呈现。取值可以自定义。	字符串	否
`apiVersion`	-	表示应用依赖的 HarmonyOS 的 API 版本。	对象	否
`compatible`	表示应用运行需要的API最小版本。取值为大于零的整数。	数值	否
`target`	表示应用运行需要的 API 目标版本。取值为大于零的整数。	数值	可缺省，缺省值为应用所在设备的当前 API 版本。

app示例：

"app": {
    "bundleName": "com.huawei.hiworld.example",
    "vendor": "huawei",
    "version": {
        "code": 2,
        "name": "2.0"
    }
    "apiVersion": {
        "compatible": 3,
        "target": 3
    }
}

deviceConfig对象的内部结构

deviceConfig包含在具体设备上的应用配置信息，可以包含default、car、tv、wearable、liteWearable、smartVision等属性。default标签内的配置是适用于所有设备通用，其他设备类型如果有特殊的需求，则需要在该设备类型的标签下进行配置。内部结构说明参见表3。

表3 deviceConfig对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`default`	表示所有设备通用的应用配置信息。	对象	否
`car`	表示车机特有的应用配置信息。	对象	可缺省，缺省为空。
`tv`	表示智慧屏特有的应用配置信息。	对象	可缺省，缺省为空。
`wearable`	表示智能穿戴特有的应用配置信息。	对象	可缺省，缺省为空。
`liteWearable`	表示轻量级智能穿戴特有的应用配置信息。	对象	可缺省，缺省为空。
`smartVision`	表示智能摄像头特有的应用配置信息。	对象	可缺省，缺省为空。

default、car、tv、wearable、liteWearable、smartVision等对象的内部结构说明，可参见表4。

表4 default/car/tv/wearable等对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`process`	表示应用或者 Ability 的进程名。如果在“`deviceConfig`”标签下配置了“`process`”标签，则该应用的所有 Ability 都运行在这个进程中。如果在“`abilities`”标签下也为某个 Ability 配置了“`process`”标签，则该 Ability 就运行在这个进程中。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省为应用的软件包名。
`directLaunch`	表示应用是否支持在设备未解锁状态直接启动。如果配置为“`true`”，则表示应用支持在设备未解锁状态下启动。使用场景举例：应用支持在设备未解锁情况下接听来电。该标签仅适用于智慧屏、智能穿戴、车机。	布尔类型	可缺省，缺省为`false`。
`supportBackup`	表示应用是否支持备份和恢复。如果配置为“`false`”，则不支持为该应用执行备份或恢复操作。该标签仅适用于智慧屏、智能穿戴、车机。	布尔类型	可缺省，缺省为`false`。
`compressNativeLibs`	表示`libs`库是否以压缩存储的方式打包到 HAP 包。如果配置为“`false`”，则`libs`库以不压缩的方式存储，HAP 包在安装时无需解压`libs`，运行时会直接从 HAP 内加载`libs`库。该标签仅适用于智慧屏、智能穿戴、车机。	布尔类型	可缺省，缺省为`true`。
[`network`]	表示网络安全性配置。该标签允许应用通过配置文件的安全声明来自定义其网络安全，无需修改应用代码。	对象	可缺省，缺省为空。

表5 network对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`usesCleartext`	表示是否允许应用使用明文网络流量（例如，明文 HTTP）。默认值为“`false`”。 `true`：允许应用使用明文流量的请求。 `false`：拒绝应用使用明文流量的请求。	布尔类型	可缺省，缺省为空。
[`securityConfig`]	表示应用的网络安全配置信息。	对象	可缺省，缺省为空。

表6 securityConfig对象的内部结构说明

属性名称	子属性名称	含义	数据类型	是否可缺省
`domainSettings`	-	表示自定义的网域范围的安全配置，支持多层嵌套，即一个`domainSettings`对象中允许嵌套更小网域范围的`domainSettings`对象。	对象	可缺省，缺省为空。
`cleartextPermitted`	表示自定义的网域范围内是否允许明文流量传输。当`useCleartext`和`securityConfig`同时存在时，自定义网域是否允许明文流量传输以`cleartextPermitted`的取值为准。 - `true`：允许明文流量传输。 - false：拒绝明文流量传输。	布尔类型
`domains`	表示域名配置信息，包含两个参数：`subDomains`和`name`。 `subDomains`（布尔类型）：表示是否包含子域名。如果为 “`true`”，此网域规则将与相应网域及所有子网域（包括子网域的子网域）匹配。否则，该规则仅适用于精确匹配项。 `name`（字符串）：表示域名名称。	对象数组	否

deviceConfig示例：

"deviceConfig": {
    "default": {
        "process": "com.huawei.hiworld.example",
        "directLaunch": false,
        "supportBackup": false,
        "network": {
            "usesCleartext": true,
            "securityConfig": {
                "domainSettings": {
                    "cleartextPermitted": true,
                    "domains": [
                        {
                            "subDomains": true,
                            "name": "example.ohos.com"
                        }
                    ]
                }
            }
        }
    }
}

module对象的内部结构

module对象包含 HAP 包的配置信息，内部结构说明参见表7。

表7 module对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`package`	表示 HAP 的包结构名称，在应用内应保证唯一性。采用反向域名格式（建议与 HAP 的工程目录保持一致）。字符串长度不超过 127字节。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	否
`name`	表示 HAP 的类名。采用反向域名方式表示，前缀需要与同级的 `package`标签指定的包名一致，也可采用“.”开头的命名方式。字符串长度不超过 255字节。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	否
`description`	表示 HAP 的描述信息。字符串长度不超过 255字节。如果字符串超出长度或者需要支持多语言，可以采用资源索引的方式添加描述内容。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省值为空。
`supportedModes`	表示应用支持的运行模式。当前只定义了驾驶模式（drive）。该标签仅适用于车机。	字符串数组	可缺省，缺省值为空。
`deviceType`	表示允许 Ability 运行的设备类型。系统预定义的设备类型包括：tv（智慧屏）、car（车机）、wearable（智能穿戴）、liteWearable（轻量级智能穿戴）等。	字符串数组	否
[`distro`]	表示 HAP 发布的具体描述。该标签仅适用于智慧屏、智能穿戴、车机。	对象	否
[`abilities`]	表示当前模块内的所有 Ability。采用对象数组格式，其中每个元素表示一个 Ability 对象。	对象数组	可缺省，缺省值为空。
[`js`]	表示基于 JS UI 框架开发的 JS 模块集合，其中的每个元素代表一个 JS 模块的信息。	对象	可缺省，缺省值为空。
[`shortcuts`]	表示应用的快捷方式信息。采用对象数组格式，其中的每个元素表示一个快捷方式对象。	对象数组	可缺省，缺省值为空。
`defPermissions`	表示应用定义的权限。应用调用者必须申请这些权限，才能正常调用该应用。	对象数组	可缺省，缺省值为空。
`reqPermissions`	表示应用运行时向系统申请的权限。	对象数组	可缺省，缺省值为空。

module示例：

"module": {
    "package": "com.example.myapplication.entry",
    "name": ".MyOHOSAbilityPackage",
    "description": "$string:description_application",
    "supportedModes": [
        "drive"
    ],
    "deviceType": [
        "car"
    ],
    "distro": {
        "deliveryWithInstall": true,
        "moduleName": "ohos_entry",
        "moduleType": "entry"
    },
    "abilities": [
        ...
    ],
    "shortcuts": [
        ...
    ],
    "js": [
        ...
    ],
    "reqPermissions": [
        ...
    ],
    "defPermissions": [
        ...
    ]
}

表8 distro对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`deliveryWithInstall`	表示当前 HAP 是否在支持随应用安装。 `true`：支持随应用安装。 `false`：不支持随应用安装。	布尔类型	否
`moduleName`	表示当前 HAP 的名称。	字符串	否
`moduleType`	表示当前 HAP 的类型，包括两种类型：`entry`和`feature`。	字符串	否

distro示例：

"distro": {
    "deliveryWithInstall": true,
    "moduleName": "ohos_entry",
    "moduleType": "entry"
}

表9 abilities对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`name`	表示 Ability 名称。取值可采用反向域名方式表示，由包名和类名组成，如“`com.example.myapplication.MainAbility`”；也可采用“`.`”开头的类名方式表示，如“`.MainAbility`”。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	否
`description`	表示对 Ability 的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。	字符串	可缺省，缺省值为空。
`icon`	表示 Ability 图标资源文件的索引。取值示例：`$media:ability_icon`。如果在该 Ability 的“`skills`”属性中，“`actions`”的取值包含 “`action.system.home`”，“`entities`”取值中包含“`entity.system.home`”，则该 Ability 的`icon`将同时作为应用的`icon`。如果存在多个符合条件的 Ability，则取位置靠前的 Ability 的`icon`作为应用的`icon`。	字符串	可缺省，缺省值为空。
`label`	表示 Ability 对用户显示的名称。取值可以是 Ability 名称，也可以是对该名称的资源索引，以支持多语言。如果在该 Ability 的“`skills`”属性中，“`actions`”的取值包含 “`action.system.home`”，“`entities`”取值中包含“`entity.system.home`”，则该 Ability 的`label`将同时作为应用的`label`。如果存在多个符合条件的 Ability，则取位置靠前的 Ability 的`label`作为应用的`label`。	字符串	可缺省，缺省值为空。
`uri`	表示 Ability 的统一资源标识符。格式为[`scheme:`] [`//authority`] [`path`] [`?query`] [`#fragment`]	字符串	可缺省，对于data类型的Ability不可缺省。
`launchType`	表示 Ability 的启动模式，支持“`standard`”和“`singleton`”两种模式： `standard`：表示该 Ability 可以有多实例。“`standard`”模式适用于大多数应用场景。 `singleton`：表示该 Ability 只可以有一个实例。例如，具有全局唯一性的呼叫来电界面即采用“`singleton`”模式。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省值为standard。
`visible`	表示 Ability 是否可以被其他应用调用。 `true`：可以被其他应用调用。 `false`：不能被其他应用调用。	布尔类型	可缺省，缺省值为false。
`permissions`	表示其他应用的 Ability 调用此 Ability 时需要申请的权限。通常采用反向域名格式，取值可以是系统预定义的权限，也可以是开发者自定义的权限。如果是自定义权限，取值必须与“defPermissions”标签中定义的某个权限的“`name`”标签值一致。	字符串数组	可缺省，缺省值为空。
[`skills`]	表示 Ability 能够接收的 Intent 的特征。	对象数组	可缺省，缺省值为空。
`deviceCapability`	表示 Ability 运行时要求设备具有的能力，采用字符串数组的格式表示。	字符串数组	可缺省，缺省值为空。
`type`	表示 Ability 的类型。取值范围如下： `page`：表示基于 `Page`模板开发的 `FA`，用于提供与用户交互的能力。 `service`：表示基于 `Service`模板开发的`PA`，用于提供后台运行任务的能力。 `data`：表示基于 `Data`模板开发的 `PA`，用于对外部提供统一的数据访问抽象。	字符串	否
`formEnabled`	表示 FA 类型的 Ability 是否提供卡片（`form`）能力。该标签仅适用于`page`类型的 Ability。 `true`：提供卡片能力。 `false`：不提供卡片能力。	布尔类型	可缺省，缺省值为false。
[`form`]	表示 AbilityForm 的属性。该标签仅当“`formEnabled`”为“`true`”时，才能生效。	对象	可缺省，缺省值为空。
`orientation`	表示该 Ability 的显示模式。该标签仅适用于`page`类型的 Ability。取值范围如下： `unspecified`：由系统自动判断显示方向。 `landscape`：横屏模式。 `portrait`：竖屏模式。 `followRecent`：跟随栈中最近的应用。	字符串	可缺省，缺省值为unspecified。
`backgroundModes`	表示后台服务的类型，可以为一个服务配置多个后台服务类型。该标签仅适用于`service`类型的 Ability。取值范围如下： `dataTransfer`：通过网络/对端设备进行数据下载、备份、分享、传输等业务。 `audioPlayback`：音频输出业务。 `audioRecording`：音频输入业务。 `pictureInPicture`：画中画、小窗口播放视频业务。 `voip`：音视频电话、VOIP 业务。 `location`：定位、导航业务。 `bluetoothInteraction`：蓝牙扫描、连接、传输业务。 `wifiInteraction`：WLAN 扫描、连接、传输业务。 `screenFetch`：录屏、截屏业务。	字符串数组	可缺省，缺省值为空。
`readPermission`	表示读取 Ability 的数据所需的权限。该标签仅适用于`data`类型的 Ability。取值为长度不超过 255字节的字符串。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省为空。
`writePermission`	表示向 Ability 写数据所需的权限。该标签仅适用于`data`类型的 Ability。取值为长度不超过 255字节的字符串。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省为空。
`directLaunch`	表示 Ability 是否支持在设备未解锁状态直接启动。如果配置为“`true`”，则表示 Ability 支持在设备未解锁状态下启动。如果“`deviceConfig`”和“`abilities`”中同时配置了“`directLaunch`”，则采用 Ability 对应的取值；如果同时未配置，则采用系统默认值。	布尔值	可缺省，缺省为false。
`configChanges`	表示 Ability 关注的系统配置集合。当已关注的配置发生变更后，Ability 会收到`onConfigurationUpdated`回调。取值范围：`locale`：表示语言区域发生变更。 `layout`：表示屏幕布局发生变更。 `fontSize`：表示字号发生变更。 `orientation`：表示屏幕方向发生变更。 `density`：表示显示密度发生变更。	字符串数组	可缺省，缺省为空。
`mission`	表示Ability指定的任务栈。该标签仅适用于page类型的Ability。默认情况下应用中所有Ability同属一个任务栈。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省为应用的包名。
`targetAbility`	表示当前 Ability 重用的目标 Ability。该标签仅适用于`page`类型的 Ability。如果配置了`targetAbility`属性，则当前 Ability（即别名 Ability）的属性中仅“`name`”、“`icon`”、“`label`”、“`visible`”、“`permissions`”、“`skills`”生效，其它属性均沿用`targetAbility`中的属性值。目标 Ability 必须与别名 Ability 在同一应用中，且在配置文件中目标 Ability 必须在别名之前进行声明。该标签仅适用于智慧屏、智能穿戴、车机。	字符串	可缺省，缺省值为空。表示当前 Ability 不是一个别名 Ability。
`multiUserShared`	表示 Ability 是否支持多用户状态进行共享，该标签仅适用于`data`类型的 Ability。配置为“`true`”时，表示在多用户下只有一份存储数据。需要注意的是，该属性会使`visible`属性失效。该标签仅适用于智慧屏、智能穿戴、车机。	布尔类型	可缺省，缺省值为`false`。
`supportPipMode`	表示 Ability 是否支持用户进入 PIP 模式（用于在在页面最上层悬浮小窗口，俗称“画中画”，常见于视频播放等场景）。该标签仅适用于`page`类型的 Ability。该标签仅适用于智慧屏、智能穿戴、车机。	布尔类型	可缺省，缺省值为`false`。

abilities示例：

"abilities": [
    {
        "name": ".MainAbility",
        "description": "$string:description_main_ability",
        "icon": "$media:hiworld.png",
        "label": "HiMusic",
        "type": "page",
        "formEnabled": false,
        "launchType": "standard",
        "orientation": "unspecified",
        "permissions": [
        ],
        "visible": false,
        "skills": [
            {
                "actions": [
                    "action.system.home"
                ],
                "entities": [
                    "entity.system.home"
                ]
            }
        ],
        "configChanges": [
            "locale",
            "layout",
            "fontSize",
            "orientation"
        ],
        "directLaunch": false,
        "process": "string",
        "backgroundModes": [
            "dataTransfer",
            "audioPlayback",
            "audioRecording",
            "pictureInPicture",
            "voip",
            "location",
            "bluetoothInteraction",
            "wifiInteraction",
            "screenFetch"
        ],
    }
]

表10 skills对象的内部结构说明

属性名称	子属性名称	含义	数据类型	是否可缺省
`actions`	-	表示能够接收的 Intent 的`action`值，可以包含一个或多个`action`。取值通常为系统预定义的`action`值，详见《API 参考》中的`ohos.aafwk.content.Intent`类。	字符串数组	可缺省，缺省值为空。
`entities`	-	表示能够接收的 Intent 的 Ability 的类别（如视频、桌面应用等），可以包含一个或多个`entity`。取值通常为系统预定义的类别，详见《API 参考》中的`ohos.aafwk.content.Intent`类，也可以自定义。	字符串数组	可缺省，缺省值为空。
`uris`	-	表示能够接收的`Intent`的`uri`，可以包含一个或者多个`uri`。	对象数组	可缺省，缺省值为空。
`scheme`	表示`uri`的`scheme`值。	字符串	不可缺省。
`host`	表示`uri`的`host`值。	字符串	可缺省，缺省值为空。
`port`	表示`uri`的`port`值。	字符串	可缺省，缺省值为空。
`path`	表示`uri`的`path`值。	字符串	可缺省，缺省值为空。
`type`	表示`uri`的`type`值。	字符串	可缺省，缺省值为空。

skills示例：

"skills": [
    {
        "actions": [
            "action.system.home"
        ],
        "entities": [
            "entity.system.home"
        ],
        "uris": [
            {
                 "scheme": "http",
                 "host": "www.xxx.com",
                 "port": "8080",
                 "path": "query/student/name",
                 "type": "text"
             }
         ]
    }
]

表11 form对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
`formEntity`	表示`AbilityForm`支持的显示方式，当前支持的位置包括： `homeScreen`：以桌面图标显示。 `searchbox`：在全局搜索显示。	字符串数组	可缺省，缺省值为空。
`minHeight`	表示`AbilityForm`缩放时能达到的最小高度，单位：像素。	数值	可缺省，缺省值为`0`。
`defaultHeight`	表示`AbilityForm`的默认高度，单位：像素。`Form`使用方应当根据该值为 `Form`申请相应高度的容器布局。	数值	可缺省，缺省值为`0`。
`minWidth`	表示`AbilityForm`缩放时能达到的最小宽度，单位：像素。	数值	可缺省，缺省值为`0`。
`defaultWidth`	表示`AbilityForm`的默认宽度，单位：像素。 `Form`使用方应当根据该值为`Form`申请相应宽度的容器布局。	数值	可缺省，缺省值为`0`。

form示例：

"form": {
    "formEntity": [
        "homeScreen",
        "searchbox"
    ],
    "minHeight": 100,
    "maxHeight": 200,
    "minWidth": 100,
    "maxWidth": 200
}

表12 js对象的内部结构说明

属性名称	子属性名称	含义	数据类型	是否可缺省
`name`	-	表示 JS Module 的名字。该标签不可缺省，默认值为`default`。	字符串	否
`pages`	-	表示 JS Module 的页面用于列举 JS Module 中每个页面的路由信息[`页面路径+页面名称`]。该标签不可缺省，取值为数组，数组第一个元素代表 JS FA 首页。	数组	否
`window`	-	用于定义与显示窗口相关的配置。该标签仅适用于智慧屏、智能穿戴、车机。	对象	可缺省。
`designWidth`	表示页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。	数值	可缺省，缺省值为`750px`。
`autoDesignWidth`	表示页面设计基准宽度是否自动计算。当配置为`true`时，`designWidth`将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。	布尔类型	可缺省，缺省值为`false`。

js示例：

"js": [
    {
        "name": "default",
        "pages": [
            "pages/index/index",
            "pages/detail/detail"
        ],
        "window": {
            "designWidth": 750,
            "autoDesignWidth": false
        }
    }
]

属性名称	子属性名称	含义	数据类型	是否可缺省
`shortcutId`	-	表示快捷方式的 ID。字符串的最大长度为 63字节。	字符串	否
`label`	-	表示快捷方式的标签信息，即快捷方式对外显示的文字描述信息。取值可以是描述性内容，也可以是标识`label`的资源索引。字符串最大长度为 63字节。	字符串	可缺省，缺省为空。
`intents`	-	表示快捷方式内定义的目标`intent`信息集合，每个`intent`可配置两个子标签，`targetClass`, `targetBundle`。	-	可缺省，缺省为空。
`targetClass`	表示快捷方式目标类名。	字符串	可缺省，缺省值为空。
`targetBundle`	表示快捷方式目标 Ability 所在应用的包名。	字符串	可缺省，缺省值为空。

示例：

"shortcuts": [
    {
        "shortcutId": "id",
        "label": "$string:shortcut",
        "intents": [
            {
                "targetBundle": "com.huawei.hiworld.himusic",
                "targetClass": "com.huawei.hiworld.himusic.entry.MainAbility"
            }
        ]
    }
]

上一节：鸿蒙OS 应用配置文件简介

下一节：鸿蒙OS 配置文件示例

"鸿蒙OS开发文档"的目录

鸿蒙OS开发文档 鸿蒙OS 配置文件的元素

配置文件的内部结构

app对象的内部结构

deviceConfig对象的内部结构

module对象的内部结构

鸿蒙OS开发文档鸿蒙OS 配置文件的元素