OpenHarmony应用开发-应用配置文件（Stage模型）

素年锦时静待君丶

发布于 2023-4-10 17:16

浏览

0收藏

版本：v3.2 Beta5

应用配置文件概述（Stage模型）

每个应用项目必须在项目的代码目录下加入配置文件，这些配置文件会向编译工具、操作系统和应用市场提供应用的基本信息。

在基于Stage模型开发的应用项目代码下，都存在一个app.json5及一个或多个module.json5这两种配置文件。

app.json5主要包含以下内容：

应用的全局配置信息，包含应用的包名、开发厂商、版本号等基本信息。
特定设备类型的配置信息。

module.json5主要包含以下内容：

Module的基本配置信息，例如Module名称、类型、描述、支持的设备类型等基本信息。
应用组件信息，包含UIAbility组件和ExtensionAbility组件的描述信息。
应用运行过程中所需的权限信息。

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",
    "distributedNotificationEnabled": true,
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "entityType": "media",
    "car": {
      "minAPIVersion": 8,
    }
  },
}

app.json5配置文件包含以下标签。

表1 app.json5文件配置标签说明

属性名称	含义	数据类型	是否可缺省
bundleName	标识应用的包名，用于标识应用的唯一性。该标签不可缺省。标签的值命名规则： - 字符串以字母、数字、下划线和符号“.”组成。 - 以字母开头。 - 最小长度7个字节，最大长度127个字节。推荐采用反域名形式命名（如com.example.demo，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。其中，随系统源码编译的应用建议命名为“com.ohos.demo”形式， ohos标识OpenHarmony系统应用。	字符串	该标签不可缺省。
debug	标识应用是否可调试，该标签由IDE编译构建时生成。 - true：可调试。 - false：不可调式。	布尔值	该标签可以缺省，缺省为false。
icon	标识应用的图标，标签值为图标资源文件的索引。	字符串	该标签不可缺省。
label	标识应用的名称，标签值为字符串资源的索引。	字符串	该标签不可缺省。
description	标识应用的描述信息，标签值是字符串类型（最大255个字节）或对描述内容的字符串资源索引。	字符串	该标签可缺省，缺省值为空。
vendor	标识对应用开发厂商的描述。该标签的值是字符串类型（最大255个字节）。	字符串	该标签可以缺省，缺省为空。
versionCode	标识应用的版本号，该标签值为32位非负整数。此数字仅用于确定某个版本是否比另一个版本更新，数值越大表示版本越高。开发者可以将该值设置为任何正整数，但是必须确保应用的新版本都使用比旧版本更大的值。该标签不可缺省，versionCode值应小于2^31次方。	数值	该标签不可缺省。
versionName	标识应用版本号的文字描述，用于向用户展示。该标签仅由数字和点构成，推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。第一段：主版本号/Major，范围0-99，重大修改的版本，如实现新的大功能或重大变化。第二段：次版本号/Minor，范围0-99，表示实现较突出的特点，如新功能添加或大问题修复。第三段：特性版本号/Feature，范围0-99，标识规划的新版本特性。第四段：修订版本号/Patch，范围0-999，表示维护版本，修复bug。标签最大字节长度为127。	字符串	该标签不可缺省。
minCompatibleVersionCode	标识应用能够兼容的最低历史版本号，用于跨设备兼容性判断。	数值	该标签可缺省，缺省值等于versionCode标签值。
minAPIVersion	标识应用运行需要的SDK的API最小版本。	数值	build-profile.json5中的compatibleSdkVersion生成。
targetAPIVersion	标识应用运行需要的API目标版本。	数值	build-profile.json5中的compileSdkVersion生成。
apiReleaseType	标识应用运行需要的API目标版本的类型，采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”，其中，N代表大于零的整数。 - Canary：受限发布的版本。 - Beta：公开发布的Beta版本。 - Release：公开发布的正式版本。该字段由DevEco Studio读取当前使用的SDK的Stage来生成。	字符串	该标签可缺省，由IDE生成并覆盖。
distributedNotificationEnabled	标识应用是否开启分布式通知，当开启分布式通知时，同一分布式组网下的两个设备(A和B)，当设备A收到一条消息时，设备B会收到一条分布式消息用于设备B的使用者去查看设备A的消息。 - true：开启。 - false：不开启。	布尔值	该标签可缺省，缺省值为false。
entityType	标识应用的类别，分别有： - game：游戏类。 - media：影音类。 - communication：社交通信类。 - news：新闻类。 - travel：出行类。 - utility：工具类。 - shopping：购物类。 - education：教育类。 - kids：少儿类。 - business：商务类。 - photography：拍摄类。 - unspecified：不属于上述的任何一类。	字符串	该标签可以缺省，缺省为unspecified。
multiProjects	标识当前工程是否支持多个工程的联合开发。 - true：当前工程支持多个工程的联合开发。 - false：当前工程不支持多个工程的联合开发。	布尔值	可缺省，缺省值为false。
tablet	标识对tablet设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。如果使用该属性对tablet设备做了特殊配置，则应用在tablet设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时tablet设备使用app.json5公共区域配置的属性值。
tv	标识对tv设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。如果使用该属性对tv设备做了特殊配置，则应用在tv设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时tv设备使用app.json5公共区域配置的属性值。
wearable	标识对wearable设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。如果使用该属性对wearable设备做了特殊配置，则应用在wearable设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时wearable设备使用app.json5公共区域配置的属性值。
car	标识对car设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。如果使用该属性对car设备做了特殊配置，则应用在car设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时car设备使用app.json5公共区域配置的属性值。
default	标识对default设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。如果使用该属性对default设备做了特殊配置，则应用在default设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。	对象	该标签可缺省，缺省时default设备使用app.json5公共区域配置的属性值。

module.json5配置文件

先通过一个示例，整体认识一下module.json5配置文件。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "virtualMachine": "ark",
    "metadata": [
      {
        "name": "string",
        "value": "string",
        "resource": "$profile:distrofilter_config"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntrance": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "visible": 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"
        }
      }
    ]
  }
}

module.json5配置文件包含以下标签。

表1 module.json5配置文件配置标签说明

属性名称	含义	数据类型	是否可缺省
name	标识当前Module的名称，标签值采用字符串表示（最大长度31个字节），该名称在整个应用要唯一。	字符串	该标签不可缺省。
type	标识当前Module的类型。类型有两种，分别： - entry：应用的主模块。 - feature：应用的动态特性模块。	字符串	该标签不可缺省。
srcEntrance	标识当前Module所对应的代码路径，标签值为字符串（最长为127字节）。	字符串	该标签可缺省，缺省值为空。
description	标识当前Module的描述信息，标签值是字符串类型（最长255字节）或对描述内容的字符串资源索引。	字符串	该标签可缺省，缺省值为空。
process	标识当前Module的进程名，标签值为字符串类型（最长为31个字节）。如果在HAP标签下配置了process，该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。说明： - 仅支持系统应用配置，三方应用配置不生效。	字符串	可缺省，缺省为app.json5文件下app标签下的bundleName。
mainElement	标识当前Module的入口UIAbility名称或者ExtensionAbility名称。标签最大字节长度为255。	字符串	该标签可缺省，缺省值为空。
deviceTypes	标识当前Module可以运行在哪类设备上，标签值采用字符串数组的表示。	字符串数组	该标签不可缺省，可以为空值。
deliveryWithInstall	标识当前Module是否在用户主动安装的时候安装，表示该Module对应的HAP是否跟随应用一起安装。 - true：主动安装时安装。 - false：主动安装时不安装。	布尔值	该标签不可缺省。
installationFree	标识当前Module是否支持免安装特性。 - true：表示支持免安装特性，且符合免安装约束。 - false：表示不支持免安装特性。说明： - 当应用的entry类型Module的该字段配置为true时，该应用的feature类型的该字段也需要配置为true。 - 当应用的entry类型Module的该字段配置为false时，该应用的feature类型的该字段根据业务需求配置true或false。	布尔值	该标签不可缺省。
virtualMachine	标识当前Module运行的目标虚拟机类型，供云端分发使用，如应用市场和分发中心。该标签值为字符串。如果目标虚拟机类型为ArkTS引擎，则其值为“ark+版本号”。	字符串	该标签由IDE构建HAP的时候自动插入。
uiSyntax（deprecated）	标识当前Module syntax定义该组件的语法类型。 - hml：标识该组件使用hml/css/js进行开发。 - ets：标识该组件使用ArkTS声明式语法进行开发。	字符串	该标签可缺省，默认值为hml，该标签从API9开始废弃。
pages	标识当前Module的profile资源，用于列举每个页面信息。该标签最大长度为255个字节。	字符串	在有UIAbility的场景下，该标签不可缺省。
metadata	标识当前Module的自定义元信息，标签值为数组类型，只对当前Module、UIAbility、ExtensionAbility生效。	对象数组	该标签可缺省，缺省值为空。
abilities	标识当前Module中UIAbility的配置信息，标签值为数组类型，只对当前UIAbility生效。	对象	该标签可缺省，缺省值为空。
extensionAbilities	标识当前Module中ExtensionAbility的配置信息，标签值为数组类型，只对当前ExtensionAbility生效。	对象	该标签可缺省，缺省值为空。
requestPermissions	标识当前应用运行时需向系统申请的权限集合。	对象	该标签可缺省，缺省值为空。
testRunner	标识当前Module用于支持对测试框架的配置。	对象	该标签可缺省，缺省值为空。

deviceTypes标签

表2 deviceType标签配置说明

设备类型	枚举值	说明
平板	tablet	-
智慧屏	tv	-
智能手表	wearable	系统能力较丰富的手表，具备电话功能。
车机	car	-
默认设备	default	能够使用全部系统能力的OpenHarmony设备。

deviceTypes示例：

{
  "module": {
    "name": "myHapName",
    "type": "feature",
    "deviceTypes" : [
       "tablet"
    ]
  }
}

pages标签

该标签是一个profile文件资源，用于指定描述页面信息的配置文件。

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // 通过profile下的资源文件配置
  }
}

在开发视图的resources/base/profile下面定义配置文件main_pages.json，其中文件名(main_pages)可自定义，需要和前文中pages标签指定的信息对应。配置文件中列举了当前应用组件中的页面信息，包含页面的路由信息和显示窗口相关的配置。

表3 pages配置文件标签说明

属性名称	含义	数据类型	是否可缺省
src	描述有关JavaScript模块中所有页面的路由信息，包括页面路径和页面名称。该值是一个字符串数组，其中每个元素表示一个页面，第一个元素表示主页。	字符串数组	该标签不可缺省。
window	用于定义与显示窗口相关的配置。	对象	该标签可缺省，缺省值为空。

表4 pages配置文件中的window标签说明

属性名称	含义	数据类型	是否可缺省
designWidth	标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。	数值	可缺省，缺省值为720px。
autoDesignWidth	标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。	布尔值	可缺省，缺省值为false。

{
  "src": [
    "pages/index/mainPage",
    "pages/second/payment",
    "pages/third/shopping_cart",
    "pages/four/owner"
  ],
  "window": {
    "designWidth": 720,
    "autoDesignWidth": false
  }
}

metadata标签

该标签标识HAP的自定义元信息，标签值为数组类型，包含name，value，resource三个子标签。

表5 metadata标签说明

属性名称	含义	数据类型	是否可缺省
name	该标签标识数据项的键名称，字符串类型（最大长度255字节）。	字符串	该标签可缺省，缺省值为空。
value	该标签标识数据项的值，标签值为字符串（最大长度255字节）。	字符串	该标签可缺省，缺省值为空。
resource	该标签标识定义用户自定义数据格式，标签值为标识该数据的资源的索引值。该标签最大字节长度为255字节。	字符串	该标签可缺省，缺省值为空。

{
  "module": {
    "metadata": [{
      "name": "module_metadata",
      "value": "a test demo for module metadata",
      "resource": "$profile:shortcuts_config",
    }],

    "abilities": [{
      "metadata": [{
        "name": "ability_metadata",
        "value": "a test demo for ability",
        "resource": "$profile:config_file"
      },
      {
        "name": "ability_metadata_2",
        "value": "a string test",
        "resource": "$profile:config_file"
      }],
    }],

    "extensionAbilities": [{
      "metadata": [{
        "name": "extensionAbility_metadata",
        "value": "a test for extensionAbility",
        "resource": "$profile:config_file"
      },
      {
        "name": "extensionAbility_metadata_2",
        "value": "a string test",
        "resource": "$profile:config_file"
      }],
    }]
  }
}

abilities标签

ablities标签描述UIAbility组件的配置信息，标签值为数组类型，该标签下的配置只对当前UIAbility生效。

表6 abilities标签说明

属性名称	含义	数据类型	是否可缺省
name	标识当前UIAbility组件的名称，该名称在整个应用要唯一，标签值采用字符串表示（最大长度127个字节）。	字符串	该标签不可缺省。
srcEntrance	该标签标识入口UIAbility的代码路径，标签值为字符串（最长为127字节）。	字符串	该标签不可缺省。
launchType	标识当前UIAbility组件的启动模式，可选标签值： - standard：标准实例模式，每次启动创建一个新的实例。 - singleton：单实例模式，仅第一次启动创建新实例。 - specified：指定实例模式，运行时由开发者决定是否创建新实例。	字符串	可缺省，该标签缺省为“singleton”。
description	标识当前UIAbility组件的描述信息，标签值是字符串类型（最长255字节）或对描述内容的资源索引，要求采用资源索引方式，以支持多语言。	字符串	该标签可缺省，缺省值为空。
icon	标识当前UIAbility组件的图标，标签值为图标资源文件的索引。	字符串	该标签可缺省，缺省值为空。如果UIAbility被配置为MainElement，该标签必须配置。
label	标识当前UIAbility组件对用户显示的名称，标签值配置为该名称的资源索引以支持多语言。如果UIAbility被配置当前Module的mainElement时，该标签必须配置，且应用内唯一。	字符串	该标签不可缺省。
permissions	标识当前UIAbility组件自定义的权限信息。当其他应用访问该UIAbility时，需要申请相应的权限信息。一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），取值为系统预定义的权限。	字符串数组	该标签可缺省，缺省值为空。
metadata	标识当前UIAbility组件的元信息。	对象数组	该标签可缺省，缺省值为空。
visible	标识当前UIAbility组件是否可以被其他应用调用。 - true：表示可以被其他应用调用。 - false：表示不可以被其他应用调用。	布尔值	该标签可缺省，缺省值为false。
continuable	标识当前UIAbility组件是否可以迁移。 - true：表示可以被迁移。 - false：表示不可以被迁移。	布尔值	该标签可缺省，缺省值为false。
skills	标识当前UIAbility组件或ExtensionAbility组件能够接收的Want的特征集，为数组格式。配置规则： - 对于Entry类型的HAP，OpenHarmony应用可以配置多个具有入口能力的skills标签（即配置了ohos.want.action.home和entity.system.home）。 - 对于Feature类型的HAP，只有OpenHarmony应用可以配置具有入口能力的skills标签，OpenHarmony服务不允许配置。	对象数组	该标签可缺省，缺省值为空。
backgroundModes	标识当前UIAbility组件的长时任务集合。指定用于满足特定类型的长时任务。长时任务类型有如下： - dataTransfer：通过网络/对端设备进行数据下载、备份、分享、传输等业务。 - audioPlayback：音频输出业务。 - audioRecording：音频输入业务。 - location：定位、导航业务。 - bluetoothInteraction：蓝牙扫描、连接、传输业务（穿戴）。 - multiDeviceConnection：多设备互联业务。 - wifiInteraction：Wi-Fi扫描、连接、传输业务（克隆多屏）。 - voip：音视频电话，VoIP业务。 - taskKeeping：计算业务。	字符串数组	该标签可缺省，缺省值为空。
startWindowIcon	标识当前UIAbility组件启动页面图标资源文件的索引。取值示例：$media:icon。该标签最大字节长度为255。	字符串	不可缺省。
startWindowBackground	标识当前UIAbility组件启动页面背景颜色资源文件的索引。取值示例：$color:red。改标签最大字节长度为255。	字符串	不可缺省。
removeMissionAfterTerminate	标识当前UIAbility组件销毁后是否从任务列表中移除任务，为布尔类型： - true表示销毁后移除任务。 - false表示销毁后不移除任务。	布尔值	该标签可缺省，缺省值为false。
orientation	标识当前UIAbility组件启动时的方向。该方向的取值范围包括： - unspecified：未指定方向，由系统自动判断显示方向。 - landscape：横屏。 - portrait：竖屏。 - landscape_inverted：反向横屏。 - portrait_inverted：反向竖屏。 - auto_rotation：随传感器旋转。 - auto_rotation_landscape：传感器横屏旋转，包括了横屏和反向横屏。 - auto_rotation_portrait：传感器竖屏旋转，包括了竖屏和反向竖屏。 - auto_rotation_restricted：传感器开关打开，方向可随传感器旋转。 - auto_rotation_landscape_restricted：传感器开关打开，方向可随传感器旋转为横屏，包括了横屏和反向横屏。 - auto_rotation_portrait_restricted：传感器开关打开，方向随可传感器旋转为竖屏，包括了横屏和反向横屏。 - locked：传感器开关关闭，方向锁定。	字符串	该标签可缺省，缺省值为unspecified。
supportWindowMode	标识当前UIAbility组件所支持的窗口模式，包含： - fullscreen：全屏模式。 - split：分屏模式。 - floating：悬浮窗模式。	字符串数组	该标签可缺省，缺省值为 [“fullscreen”, “split”, “floating”]。
priority	标识当前UIAbility组件的优先级，仅支持系统应用配置，三方应用配置不生效。隐式查询时，优先级越高，UIAbility在返回列表越靠前。该标签取值为integer类型，取值范围0-10。数值越大，优先级越高。	数值	该标签可缺省，缺省值为0。
maxWindowRatio	标识当前UIAbility组件支持的最大的宽高比。该标签最小取值为0。	数值	该标签可缺省，缺省值为平台支持的最大的宽高比。
minWindowRatio	标识当前UIAbility组件支持的最小的宽高比。该标签最小取值为0。	数值	该标签可缺省，缺省值为平台支持的最小的宽高比。
maxWindowWidth	标识当前UIAbility组件支持的最大的窗口宽度，宽度单位为vp。该标签最小取值为0，但不能小于minWindowWidth；最大取值不能超过平台支持的最大窗口宽度。窗口尺寸可以参考：约束与限制。	数值	该标签可缺省，缺省值为平台支持的最大的窗口宽度。
minWindowWidth	标识当前UIAbility组件支持的最小的窗口宽度, 宽度单位为vp。该标签最小取值为0，但不能小于平台支持的最小窗口宽度；最大取值不能大于maxWindowWidth。窗口尺寸可以参考：约束与限制。	数值	该标签可缺省，缺省值为平台支持的最小的窗口宽度。
maxWindowHeight	标识当前UIAbility组件支持的最大的窗口高度, 高度单位为vp。该标签最小取值为0，但不能小于minWindowHeight；最大取值不能超过平台支持的最大窗口高度。窗口尺寸可以参考：约束与限制。	数值	该标签可缺省，缺省值为平台支持的最大的窗口高度。
minWindowHeight	标识当前UIAbility组件支持的最小的窗口高度, 高度单位为vp。该标签最小取值为0，但不能小于平台支持的最小窗口高度；最大取值不能大于maxWindowHeight。窗口尺寸可以参考：约束与限制。	数值	该标签可缺省，缺省值为平台支持的最小的窗口高度。
excludeFromMissions	标识当前UIAbility组件是否在最近任务列表中显示。 - true：表示不在任务列表中显示。 - false：表示在任务列表中显示。说明： - 仅支持系统应用配置，三方应用配置不生效。	布尔值	该标签可缺省，缺省值为false。

abilities示例：

{
  "abilities": [{
    "name": "EntryAbility",
    "srcEntrance": "./ets/entryability/EntryAbility.ts",
    "launchType":"standard",
    "description": "$string:description_main_ability",
    "icon": "$media:icon",
    "label": "Login",
    "permissions": [],
    "metadata": [],
    "visible": true,
    "continuable": true,
    "skills": [{
      "actions": ["ohos.want.action.home"],
      "entities": ["entity.system.home"],
      "uris": []
    }],
    "backgroundModes": [
      "dataTransfer",
      "audioPlayback",
      "audioRecording",
      "location",
      "bluetoothInteraction",
      "multiDeviceConnection",
      "wifiInteraction",
      "voip",
      "taskKeeping"
    ],
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:red",
    "removeMissionAfterTerminate": true,
    "orientation": " ",
    "supportWindowMode": ["fullscreen", "split", "floating"],
    "maxWindowRatio": 3.5,
    "minWindowRatio": 0.5,
    "maxWindowWidth": 2560,
    "minWindowWidth": 1400,
    "maxWindowHeight": 300,
    "minWindowHeight": 200,
    "excludeFromMissions": false
  }]
}

skills标签

该标签标识UIAbility组件或者ExtensionAbility组件能够接收的Want的特征。

表7 skills标签说明

属性名称	含义	数据类型	是否可缺省
actions	标识能够接收的Want的Action值的集合，取值通常为系统预定义的action值，也允许自定义。	字符串数组	可缺省，缺省值为空。
entities	标识能够接收Want的Entity值的集合。	字符串数组	可缺省，缺省值为空。
uris	标识与Want中URI（Uniform Resource Identifier）相匹配的集合。	对象数组	可缺省，缺省值为空。

表8 uris对象内部结构说明

属性名称	含义	数据类型	是否可缺省
scheme	标识URI的协议名部分，常见的有http、https、file、ftp等。	字符串	uris中仅配置type时可以缺省，缺省值为空，否则不可缺省。
host	标识URI的主机地址部分，该字段要在schema存在时才有意义。常见的方式： - 域名方式，如example.com。 - IP地址方式，如10.10.10.1。	字符串	可缺省，缺省值为空。
port	标识URI的端口部分。如http默认端口为80，https默认端口是443，ftp默认端口是21。该字段要在schema和host都存在时才有意义。	字符串	可缺省，缺省值为空。
path \| pathStartWith \| pathRegex	标识URI的路径部分，path、pathStartWith和pathRegex配置时三选一。path标识URI与want中的路径部分全匹配，pathStartWith标识URI与want中的路径部分允许前缀匹配，pathRegex标识URI与want中的路径部分允许正则匹配。该字段要在schema和host都存在时才有意义。	字符串	可缺省，缺省值为空。
type	标识与Want相匹配的数据类型，使用MIME（Multipurpose Internet Mail Extensions）类型规范。可与schema同时配置，也可以单独配置。	字符串	可缺省，缺省值为空。

skills示例：

{
  "abilities": [
    {
      "skills": [
        {
          "actions": [
            "ohos.want.action.home"
          ],
          "entities": [
            "entity.system.home"
          ],
          "uris": [
            {
              "scheme":"http",
              "host":"example.com",
              "port":"80",
              "path":"path",
              "type": "text/*"
            }
          ]
        }
      ]
    }
  ]
}

extensionAbilities标签

描述extensionAbilities的配置信息，标签值为数组类型，该标签下的配置只对当前extensionAbilities生效。

表9 extensionAbilities标签说明

属性名称	含义	数据类型	是否可缺省
name	标识当前ExtensionAbility组件的名称，标签值最大长度为127个字节，该名称在整个应用要唯一。	字符串	该标签不可缺省。
srcEntrance	标识当前ExtensionAbility组件所对应的代码路径，标签值最大长度为127字节。	字符串	该标签不可缺省。
description	标识当前ExtensionAbility组件的描述，标签值最大长度为255字节，标签也可以是描述内容的资源索引，用于支持多语言。	字符串	该标签可缺省，缺省值为空。
icon	标识当前ExtensionAbility组件的图标，标签值为资源文件的索引。如果ExtensionAbility组件被配置为MainElement，该标签必须配置。	字符串	该标签可缺省，缺省值为空。
label	标识当前ExtensionAbility组件对用户显示的名称，标签值配置为该名称的资源索引以支持多语言。说明： - 如果ExtensionAbility被配置当前Module的mainElement时，该标签必须配置，且应用内唯一。	字符串	该标签不可缺省。
type	标识当前ExtensionAbility组件的类型，取值为： - form：卡片的ExtensionAbility。 - workScheduler：延时任务的ExtensionAbility。 - inputMethod：输入法的ExtensionAbility。 - service：后台运行的service组件。 - accessibility：辅助能力的ExtensionAbility。 - dataShare：数据共享的ExtensionAbility。 - fileShare：文件共享的ExtensionAbility。 - staticSubscriber：静态广播的ExtensionAbility。 - wallpaper：壁纸的ExtensionAbility。 - backup：数据备份的ExtensionAbility。 - window：该ExtensionAbility会在启动过程中创建一个window，为开发者提供界面开发。开发者开发出来的界面将通过abilityComponent控件组合到其他应用的窗口中。 - thumbnail：获取文件缩略图的ExtensionAbility，开发者可以对自定义文件类型的文件提供缩略。 - preview：该ExtensionAbility会将文件解析后在一个窗口中显示，开发者可以通过将此窗口组合到其他应用窗口中。说明： - 其中service和dataShare类型，仅支持系统应用配置，三方应用配置不生效。	字符串	该标签不可缺省。
permissions	标识当前ExtensionAbility组件自定义的权限信息。当其他应用访问该ExtensionAbility时，需要申请相应的权限信息。一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），可以是系统预定义的权限，也可以是该应用自定义的权限。如果是后者，需与defPermissions标签中定义的某个权限的name标签值一致。	字符串数组	该标签可缺省，缺省值为空。
uri	标识当前ExtensionAbility组件提供的数据URI，为字符数组类型（最大长度255），用反向域名的格式表示。说明： - 该标签在type为dataShare类型的ExtensionAbility时，不可缺省。	字符串	该标签可缺省，缺省值为空。
skills	标识当前ExtensionAbility组件能够接收的Want的特征集，为数组格式。配置规则：entry包可以配置多个具有入口能力的skills标签（配置了ohos.want.action.home和entity.system.home）的ExtensionAbility，其中第一个配置了skills标签的ExtensionAbility中的label和icon作为OpenHarmony服务或应用的label和icon。说明： - OpenHarmony服务的Feature包不能配置具有入口能力的skills标签。 - OpenHarmony应用的Feature包可以配置具有入口能力的skills标签。	数组	该标签可缺省，缺省值为空。
metadata	标识当前ExtensionAbility组件的元信息。	对象	该标签可缺省，缺省值为空。
visible	标识当前ExtensionAbility组件是否可以被其他应用调用，为布尔类型。 - true：表示可以被其他应用调用。 - false：表示不可以被其他应用调用。	布尔值	该标签可缺省，缺省值为false。

extensionAbilities示例：

{
  "extensionAbilities": [
    {
      "name": "FormName",
      "srcEntrance": "./form/MyForm.ts",
      "icon": "$media:icon",
      "label" : "$string:extension_name",
      "description": "$string:form_description",
      "type": "form",
      "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
      "readPermission": "",
      "writePermission": "",
      "visible": true,
      "uri":"scheme://authority/path/query",
      "skills": [{
        "actions": [],
        "entities": [],
        "uris": []
      }],
      "metadata": [
        {
          "name": "ohos.extension.form",
          "resource": "$profile:form_config",
        }
      ]
    }
  ]
}

requestPermissions标签

该标签标识应用运行时需向系统申请的权限集合。

说明：
在requestPermissions标签中配置的权限项将在应用级别生效，即该权限适用于整个应用程序。

表10 requestPermissions标签说明

属性	含义	类型	取值范围	默认值
name	必须，填写需要使用的权限名称。	字符串	自定义。	无。
reason	可选，当申请的权限为user_grant权限时此字段必填，用于描述申请权限的原因。说明： - 当申请的权限为user_grant权限时，如果未填写该字段则不允许在应用市场上架，并且需要进行多语种适配。	字符串	使用string类资源引用。格式为$string: ***。	空。
usedScene	可选，当申请的权限为user_grant权限时此字段必填。描述权限使用的场景由abilities和when组成。其中abilities可以配置为多个UIAbility组件，when表示调用时机。说明： - 默认为可选，当申请的权限为user_grant权限时，abilities标签必填，when标签可选。	abilities：UIAbility或者ExtensionAbility名称的字符串数组 when：字符串	abilities：UIAbility或者ExtensionAbility组件的名称。 when：inuse（使用时）、always（始终）。	abilities：空。 when：空。

requestPermissions示例：

{
  "module" : {
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "EntryFormAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

shortcuts标签

shortcuts标识应用的快捷方式信息。标签值为数组，最多可以配置四个快捷方式。其包含四个子标签shortcutId、label、icon、wants。

metadata中指定shortcut信息，其中：

name：指定shortcuts的名称。使用ohos.ability.shortcuts作为shortcuts信息的标识。
resource：指定shortcuts信息的资源位置。

表11 shortcuts标签说明

属性	含义	类型	默认值
shortcutId	标识快捷方式的ID。字符串的最大长度为63字节。	字符串	该标签不可缺省。
label	标识快捷方式的标签信息，即快捷方式对外显示的文字描述信息。取值可以是描述性内容，也可以是标识label的资源索引。字符串最大长度为255字节。	字符串	该标签可缺省，缺省值为空。
icon	标识快捷方式的图标，标签值为资源文件的索引。	字符串	该标签可缺省，缺省值为空。
wants	标识快捷方式内定义的目标wants信息集合，每个wants可配置bundleName和abilityName两个子标签。 bundleName：表示快捷方式的目标包名，字符串类型。 abilityName：表示快捷方式的目标组件名，字符串类型。	对象	该标签可缺省，缺省为空。

在/resource/base/profile/目录下配置shortcuts_config.json配置文件。

{
  "shortcuts": [
    {
      "shortcutId": "id_test1",
      "label": "$string:shortcut",
      "icon": "$media:aa_icon",
      "wants": [
        {
          "bundleName": "com.ohos.hello",
          "abilityName": "EntryAbility"
        }
      ]
    }
  ]
}

在module.json5配置文件的abilities标签中，针对需要添加快捷方式的UIAbility进行配置metadata标签，使shortcut配置文件对该UIAbility生效。

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntrance": "./ets/entryability/EntryAbility.ts",
        // ...
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ],
        "metadata": [
          {
            "name": "ohos.ability.shortcuts",
            "resource": "$profile:shortcuts_config"
          }
        ]
      }
    ]
  }
}

distroFilter标签

该标签下的子标签均为可选字段，在应用市场云端分发时做精准匹配使用，distroFilter用于定义HAP对应的细分设备规格的分发策略，以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Version、屏幕形状、屏幕尺寸、屏幕分辨率，设备的国家与地区码。在进行分发时，通过deviceType与这五个属性的匹配关系，唯一确定一个用于分发到设备的HAP。该标签需要配置在/resource/profile资源目录下。

表12 distroFilter标签配置说明

属性名称	含义	数据类型	是否可缺省
apiVersion	标识支持的apiVersion范围。	对象数组	该标签可缺省，缺省值为空。
screenShape	标识屏幕形状的支持策略。	对象数组	该标签可缺省，缺省值为空。
screenWindow	标识应用运行时窗口的分辨率支持策略。该字段仅支持对轻量级智能穿戴设备进行配置。	对象数组	该标签可缺省，缺省值为空。
screenDensity	标识屏幕的像素密度（dpi：Dot Per Inch）。该字段可选，如果配置了该字段，取值必须合法。该标签为字符串数组，字符串范围如下。 - sdpi：表示小规模的屏幕密度（Small-scale Dots per Inch），适用于dpi取值为(0,120]的设备。 - mdpi：表示中规模的屏幕密度（Medium-scale Dots Per Inch），适用于dpi取值为(120,160]的设备。 - ldpi：表示大规模的屏幕密度（Large-scale Dots Per Inch），适用于dpi取值为(160,240]的设备。 - xldpi：表示大规模的屏幕密度（Extra Large-scale Dots Per Inch），适用于dpi取值为(240,320]的设备。 - xxldpi：表示大规模的屏幕密度（Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(320，480]的设备。 - xxxldpi：表示大规模的屏幕密度（Extra Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(480, 640]的设备。	对象数组	该标签可缺省，缺省值为空。
countryCode	表示应用需要分发的国家地区码，具体值以ISO-3166-1标准为准。支持多个国家和地区枚举定义。	对象数组	该标签可缺省，缺省值为空。

表13 apiVersion标签说明

属性名称	含义	数据类型	是否可缺省
policy	标识该子属性取值规则。配置为“exclude”或“include”。 - exclude：表示需要排除的value属性。 - include：表示需要包含的value属性。	字符串	该标签不可缺省。
value	支持的取值为API Version存在的整数值，例如4、5、6。场景示例：某应用，针对相同设备型号，同时在网的为使用API 5和API 6开发的两个软件版本，则允许上架2个entry类型的安装包，分别支持到对应设备侧软件版本的分发。	数组	该标签不可缺省。

表14 screenShape对象的内部结构

属性名称	含义	数据类型	是否可缺省
policy	标识该子属性取值规则。配置为“exclude”或“include”。 - exclude：表示需要排除的value属性。 - include：表示需要包含的value属性。	字符串	该标签不可缺省。
value	支持的取值为circle（圆形）、rect（矩形）。场景示例：针对智能穿戴设备，可为圆形表盘和矩形表盘分别提供不同的HAP。	字符串数组	该标签不可缺省。

表15 screenWindow对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
policy	标识该子属性取值规则。配置为“exclude”或“include”。 - exclude：表示该字段取值不包含value枚举值匹配规则的匹配该属性。 - include：表示该字段取值满足value枚举值匹配规则的匹配该属性。	字符串	该标签不可缺省。
value	单个字符串的取值格式为“宽 * 高”，取值为整数像素值，例如“454 * 454”。	字符串数组	该标签不可缺省。

表16 screenDensity对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
policy	标识该子属性取值规则。配置为“exclude”或“include”。 - exclude：表示需要排除的value属性。 - include：表示需要包含的value属性。	字符串	该标签不可缺省。
value	该标签标识屏幕的像素密度（dpi :Dot Per Inch）。	字符串数组	该标签不可缺省。

表17 countryCode对象的内部结构说明

属性名称	含义	数据类型	是否可缺省
policy	标识该子属性取值规则。配置为“exclude”或“include”。 - exclude：表示需要排除的value属性。 - include：表示需要包含的value属性。	字符串	该标签不可缺省。
value	标识应用需要分发的国家地区码。	字符串数组	该标签不可缺省。

在开发视图的resources/base/profile下面定义配置文件distro_filter_config.json，文件名可以自定义。

{
  "distroFilter": {
    "apiVersion": {
      "policy": "include",
      "value": [
        3,
        4
      ]
    },
    "screenShape": {
      "policy": "include",
      "value": [
        "circle",
        "rect"
      ]
    },
    "screenWindow": {
      "policy": "include",
      "value": [
        "454*454",
        "466*466"
      ]
    },
    "screenDensity": {
      "policy": "exclude",
      "value": [
        "ldpi",
        "xldpi"
      ]
    },
    "countryCode": { // 支持中国和香港地区分发
      "policy": "include",
      "value": [
        "CN",
        "HK"
      ]
    }
  }
}

在module.json5配置文件的module标签中定义metadata信息。

{
  "module": {
    // ...
    "metadata": [
      {
        "name": "ohos.module.distro",
        "resource": "$profile:distro_filter_config",
      }
    ]
  }
}

testRunner标签

此标签用于支持对测试框架的配置。

表18 testRunner标签说明

属性名称	含义	数据类型	是否可缺省
name	标识测试框架对象名称。该标签最大字节长度为255个字节。	字符串	不可缺省。
srcPath	标识测试框架代码路径。该标签最大字节长度为255个字节。	字符串	不可缺省。

testRunner标签示例：

{
  "module": {
    // ...
    "testRunner": {
      "name": "myTestRunnerName",
      "srcPath": "etc/test/TestRunner.ts"
    }
  }
}

文章转载自：https://docs.openharmony.cn/pages/v3.2Beta/zh-cn/application-dev/quick-start/module-configuration-file.md/

分类

IDE

其他

标签

OpenHarmony

已于2023-4-10 17:16:03修改

51CTO

51CTO博客

51CTO学堂