module.json5配置文件

配置文件示例

通过一个示例，整体了解module.json5配置文件。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "tv",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "pages": "$profile:main_pages", // 资源配置，指向profile下面定义的配置文件main_pages.json
    "appStartup": "$profile:app_startup_config",
    "metadata": [
      {
        "name": "string",
        "value": "string",
        "resource": "$profile:distributionFilter_config"
      },
      // ...
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindow": "$profile:start_window",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          // ...
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ],
        // ...
        "continueType": [
          "continueType1"
        ],
        "continueBundleName": [
          "com.example.myapplication1",
          "com.example.myapplication2"
        ],
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.ACCESS_BLUETOOTH",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ],
    "querySchemes": [
      "app1Scheme",
      "app2Scheme"
    ],
    "routerMap": "$profile:router_map",
    "appEnvironments": [
      {
        "name": "name1",
        "value": "value1"
      }
    ],
    "fileContextMenu": "$profile:menu", // 资源配置，指向profile下面定义的配置文件menu.json
    "crossAppSharedConfig": "$profile:shared_config",
    "skillProfiles": [
      {
        "name": "my-skill",
        "abilityName": "EntryAbility",
        "srcEntries": [
          "../../my-skill/scripts/Test.ets"
        ],
        "permissions": []
      }
    ],
    // ...
  }
}

配置文件标签

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

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

deviceTypes标签

表2 deviceTypes标签说明

deviceTypes示例：

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

pages标签

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

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // 资源配置，指向profile下面定义的配置文件main_pages.json
    // ...
  }
}

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

表3 pages标签说明

表4 window标签说明

{
  "src": [
    "pages/Index"
  ],
  "window": {
    "designWidth": 720,
    "autoDesignWidth": false
  }
}

metadata标签

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

表5 metadata标签说明

{
  "module": {
    // ...
    "metadata": [
      // ...
      {
        "name": "pageConfig",
        "value": "main page config of application",
        "resource": "$profile:main_pages" // 资源配置，指向profile下面定义的配置文件main_pages.json
      }
    ],
    // ...
  }
}

abilities标签

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

表6 abilities标签说明

abilities示例：

{
  // ...
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "launchType": "singleton",
        "description": "$string:description_main_ability",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "permissions": [],
        "metadata": [],
        "exported": true,
        "continuable": true,
        "skills": [
          {
            "actions": [
              "ohos.want.action.home"
            ],
            "entities": [
              "entity.system.home"
            ],
            "uris": []
          }
        ],
        "backgroundModes": [
          "dataTransfer"
        ],
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:red",
        "removeMissionAfterTerminate": true,
        "allowSelfRedirect": true,  // 从API version 23开始，支持该标签
        "orientation": "$string:orientation",
        "supportWindowMode": [
          "fullscreen",
          "split",
          "floating"
        ],
        "maxWindowRatio": 3.5,
        "minWindowRatio": 0.5,
        "maxWindowWidth": 2560,
        "minWindowWidth": 1400,
        "maxWindowHeight": 300,
        "minWindowHeight": 200,
        "excludeFromMissions": false,
        "preferMultiWindowOrientation": "default",
        "isolationProcess": false,
        "continueType": [
          "continueType1",
          "continueType2"
        ],
        "continueBundleName": [
          "com.example.myapplication1",
          "com.example.myapplication2"
        ],
        "process": ":processTag"
      }
    ],
    // ...
}

skills标签

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

例如：在浏览器中下载PDF文件时，可以通过配置skills标签选择并打开该PDF文件。详情请参考拉起文件处理类应用。

表7 skills标签说明

表8 uris标签说明

skills示例：

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

extensionAbilities标签

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

表9 extensionAbilities标签说明

extensionAbilities示例：

{
  // ...
    "extensionAbilities": [
      {
        "name": "FormName",
        "srcEntry": "./ets/form/MyForm.ets",
        "icon": "$media:icon",
        "label" : "$string:extension_name",
        "description": "$string:form_description",
        "type": "form",
        "permissions": ["ohos.permission.ACCESS_BLUETOOTH"],
        "exported": true,
        "uri":"scheme://authority/path/query",
        "skills": [{
          "actions": [],
          "entities": [],
          "uris": [],
          "permissions": []
        }],
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config",
          }
        ],
        "extensionProcessMode": "instance",
        "dataGroupIds": [
          "testGroupId1"
        ]
      }
    ],
    // ...
}

type标签

标识当前ExtensionAbility组件的类型，支持的取值如下：

shortcuts标签

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

metadata中指定shortcut信息，其中：

• name：指定shortcuts的名称，使用ohos.ability.shortcuts作为shortcuts信息的标识。

• resource：指定shortcuts信息的资源位置。

表10 shortcuts标签说明

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

   {
     "shortcuts": [
       {
         "shortcutId": "id_test1",
         "label": "$string:shortcut",
         "icon": "$media:aa_icon",
         "visible": true,
         "wants": [
           {
             "bundleName": "com.ohos.hello",
             "moduleName": "entry",
             "abilityName": "EntryAbility",
             "parameters": {
               "testKey": "testValue"
             }
           }
         ]
       }
     ]
   }

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

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

   module.json5

wants标签

此标签用于标识快捷方式内定义的目标wants信息集合。

表11 wants标签说明

wants标签示例：

{
  "wants": [
    {
      "bundleName": "com.ohos.hello",
      "moduleName": "entry",
      "abilityName": "EntryAbility",
      "parameters": {
        "testKey": "testValue"
      }
    }
  ]
}

distributionFilter标签

该标签用于定义HAP对应的细分设备规格的分发策略，以便在应用市场进行云端分发应用包时做精准匹配。

• 适用场景： 当一个工程中存在多个Entry，且多个Entry配置的deviceTypes存在交集时，则需要通过该标签进行区分。比如下面的两个Entry都支持tablet类型，就需要通过该标签进行区分。

  // entry1支持的设备类型
  {
    "module": {
      "name": "entry1",
      "type": "entry",
      "deviceTypes": [
        "tv",
        "tablet"
      ],
      // ...
    }
  }

  module.json5

  // entry2支持的设备类型
  {
    "module": {
      "name": "entry2",
      "type": "entry",
      "deviceTypes": [
        "tv",
        "tablet"
      ],
      // ...
    }
  }

  module.json5

• 配置规则： 该标签支持配置四个属性，包括屏幕形状(screenShape)、窗口分辨率(screenWindow)、屏幕像素密度(screenDensity )、设备所在国家与地区(countryCode)。详见下表。

  在分发应用包时，通过deviceTypes与这四个属性的匹配关系，唯一确定一个用于分发到设备的HAP。

  • 如果需要配置该标签，则至少包含一个属性。
  • 如果一个Entry中配置了任意一个或多个属性，则其他Entry也必须包含相同的属性。
  • screenShape和screenWindow属性仅适用于轻量级智能穿戴设备。

• 配置方式： 该标签需要配置在/resources/base/profile资源目录下，并在metadata的resource标签中引用。

表12 distributionFilter标签配置说明

screenShape标签

表13 screenShape标签说明

screenWindow标签

表14 screenWindow标签说明

screenDensity标签

表15 screenDensity标签说明

countryCode标签

表16 countryCode标签说明

示例如下：

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

   {
     "distributionFilter": {
       "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"
         ]
       }
     }
   }

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

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

testRunner标签

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

表17 testRunner标签说明

testRunner标签示例：

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

atomicService标签

此标签用于支持对元服务的配置。此标签仅在app.json5中将bundleType设置为atomicService时生效。

表18 atomicService标签说明

表19 preloads标签说明

atomicService标签示例：

{
  "module": {
    // ...
    "atomicService": {
      "preloads":[
        {
          "moduleName":"feature"
        }
      ],
      "resizeable": true
    },
    // ...
  }
}

dependencies标签

此标签标识模块运行时依赖的共享库列表。

表20 dependencies标签说明

dependencies标签示例：

{
  "module": {
    // ...
    "dependencies": [
      {
        "bundleName":"com.share.library",
        "moduleName": "library",
        "versionCode": 10001
      }
    ],
    // ...
  }
}

proxyData标签

此标签标识模块提供的数据代理列表，仅限entry和feature配置。

表21 proxyData标签说明

proxyData标签示例：

{
  "module": {
    // ...
    "proxyData": [
      {
        "uri":"datashareproxy://ohos.app.hap.myapplication/event/Meeting",
        "requiredReadPermission": "ohos.permission.SYSTEM_FLOAT_WINDOW",
        "requiredWritePermission": "ohos.permission.SYSTEM_FLOAT_WINDOW",
        "metadata": {
          "name": "datashare_metadata",
          "resource": "$profile:datashare"
        }
      }
    ],
    // ...
  }
}

routerMap标签

此标签标识模块配置的路由表的路径。

routerMap配置文件描述模块的路由表信息，routerMap标签的值为数组类型。

表22 routerMap标签说明

示例如下：

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

   {
     "routerMap": [
       {
         "name": "DynamicPage1",
         "pageSourceFile": "src/main/ets/pages/pageOne.ets",
         "buildFunction": "myFunction",
         "customData": {
           "stringKey": "data1",
           "numberKey": 123,
           "booleanKey": true,
           "objectKey": {
             "name": "test"
           },
           "arrayKey": [
             {
               "id": 123
             }
           ]
         }
       },
       {
         "name": "DynamicPage2",
         "pageSourceFile": "src/main/ets/pages/pageTwo.ets",
         "buildFunction": "myBuilder",
         "data": {
           "key1": "data1",
           "key2": "data2"
         }
       }
     ]
   }

2. 在module.json5配置文件的module标签中定义routerMap标签，指向定义的路由表配置文件，例如："routerMap": "$profile:router_map"。

data标签

此标签用于支持在路由表中配置自定义的字符串数据。

data标签示例：

{
  "routerMap": [
    {
      "name": "DynamicPage",
      "pageSourceFile": "src/main/ets/pages/pageOne.ets",
      "buildFunction": "myBuilder",
      "data": {
        "key1": "data1",
        "key2": "data2"
      }
    }
  ]
}

customData标签

此标签用于支持在路由表中配置自定义数据。

customData对象内部，可以配置任意类型的自定义数据。

customData标签示例：

{
  "routerMap": [
    {
      "name": "DynamicPage",
      "pageSourceFile": "src/main/ets/pages/pageOne.ets",
      "buildFunction": "myBuilder",
      "customData": {
        "stringKey": "data1",
        "numberKey": 123,
        "booleanKey": true,
        "objectKey": {
          "name": "test"
        },
        "arrayKey": [
          {
            "id": 123
          }
        ]
      }
    }
  ]
}

appEnvironments标签

此标签标识模块配置的应用环境变量。

表23 appEnvironments标签说明

appEnvironments标签示例：

{
  "module": {
    // ...
    "appEnvironments": [
      {
        "name": "name1",
        "value": "value1"
      }
    ],
    // ...
  }
}

hnpPackages标签

该标签标识应用包含的Native软件包信息。

表24 hnpPackages标签说明

hnpPackages示例：

{
  "module": {
    // ...
    "hnpPackages": [
      {
        "package": "hnpsample.hnp",
        "type": "public",
        "independentSign": true
      }
    ],
    // ...
  },
}

fileContextMenu标签

该标签标识当前HAP的右键菜单配置项，是一个profile文件资源，用于指定描述应用注册右键菜单配置文件。仅在PC/2in1设备上生效。仅允许在entry类型模块中配置。

fileContextMenu标签示例

{
  "module": {
    // ...
    "fileContextMenu": "$profile:menu", // 资源配置，指向profile下面定义的配置文件menu.json
    // ...
  }
}

在开发视图的resources/base/profile下面定义配置文件menu.json，其中文件名“menu.json”可自定义，需要和fileContextMenu标签指定的信息对应。配置文件中描述了当前应用注册的右键菜单的项目和响应行为。

配置文件根节点名称为fileContextMenu，为对象数组，标识当前module注册右键菜单的数量。（单模块和单应用注册数量不能超过5个，配置超过数量当前只解析随机5个）

表25 fileContextMenu标签配置说明

表26 menuContext标签配置说明

resources/base/profile路径下的menu.json资源文件示例如下：

{
  "fileContextMenu": [
    {
      "abilityName": "EntryAbility",
      "menuItem": "$string:module_desc",
      "menuHandler": "openCompress",
      "menuContext": [
        {
          "menuKind": 0
        },
        {
          "menuKind": 1,
          "menuRule": "both",
          "fileSupportType": [
            ".rar",
            ".zip"
          ],
          "fileNotSupportType": [
            ""
          ]
        },
        {
          "menuKind": 2,
          "menuRule": "single"
        },
        {
          "menuKind": 3
        }
      ]
    }
  ]
}

响应行为

应用进行右键扩展菜单注册后，在文件管理器通过右键操作拉起菜单，该菜单中会有“更多”选项。单击“更多”选项后，会出现注册后的menuItem列表，单击任意一个选项后，文件管理器默认通过startAbility的方式拉起三方应用，除了指定三方应用的包名和ability名之外，want中的parameter中，也会传入如下标签：

表27 want中parameter标签说明

startWindow标签

该标签指向一个profile文件资源，用于指定UIAbility组件启动页面的配置文件，在开发视图的resources/base/profile下面定义配置文件start_window.json，如果配置了该标签，startWindowIcon和startWindowBackground标签将不生效。

说明：

从API version 19开始，支持使用该字段配置增强启动页。

表28 startWindow标签配置说明

resources/base/profile路径下的start_window.json资源文件示例如下：

{
  "startWindowType": "REQUIRED_SHOW",
  "startWindowColorModeType": "FOLLOW_SYSTEM",
  "startWindowAppIcon": "$media:start_window_app_icon",
  "startWindowIllustration": "$media:start_window_illustration",
  "startWindowBrandingImage": "$media:start_window_branding_image",
  "startWindowBackgroundColor": "$color:start_window_back_ground_color",
  "startWindowBackgroundImage": "$media:start_window_back_ground_image",
  "startWindowBackgroundImageFit": "Cover"
}

systemTheme标签

该标签指向一个profile文件资源，用于指定当前应用使用的系统主题配置文件。从API version 20开始，支持该标签。

systemTheme标签示例：

{
  "module": {
    // ...
    "systemTheme": "$profile:theme_config", // 资源配置，指向profile下面定义的配置文件theme_config.json
  }
}

在开发视图的resources/base/profile下面定义配置文件theme_config.json，其中文件名“theme_config.json”可自定义为“theme_config”开头文件名，例如"theme_config"、"theme_config_1"。需要和systemTheme标签指定的信息对应。配置文件中标识当前应用使用的系统主题。

表29 theme_config.json配置说明

resources/base/profile路径下的theme_config.json资源文件示例如下：

{
  "systemTheme": "$ohos:theme:ohos_theme"
}

requiredDeviceFeatures标签

表30 requiredDeviceFeatures标签说明

requiredDeviceFeatures示例：

{
  "module": {
    "requiredDeviceFeatures": {
      "phone": [
        "large_screen"
      ],
      "2in1": [
        "paint"
      ]
    },
  }
}

executableBinaryPaths标签

标识应用内可执行二进制文件的路径信息，仅在PC/2in1设备上生效。从API version 24开始，支持该标签。

表31 executableBinaryPaths标签说明

executableBinaryPaths示例：

{
  "module": {
    // ...
    "executableBinaryPaths": [
      {
        "path": "libs/arm64-v8a/test.bin"
      }
    ],
    // ...
  },
}

skillProfiles标签

从API版本26.0.0开始，新增skillProfiles标签。该标签标识当前模块的技能配置信息，用于定义AI代理的技能能力。通过定义技能，应用可以将AI代理的能力暴露给系统或其他应用，使其能够被其他应用发现和调用。仅type取值为entry、feature、shared、skill的模块配置该标签生效。

表32 skillProfiles标签说明

skillProfiles标签示例：

{
  "module": {
    // ...
    "skillProfiles": [
      {
        "name": "my-skill",
        "abilityName": "EntryAbility",
        "srcEntries": [
          "../../my-skill/scripts/Test.ets"
        ],
        "permissions": []
      }
    ],
    // ...
  }
}