module.json5 Configuration File

A module-level configuration file provides the basic configuration of the module, information about the UIAbility and ExtensionAbility components, and permissions required during application running for the compilation tool, OS, and AppGallery. Each module must contain a module.json5 configuration file, which is stored in the project or module name/src/main/module.json5 directory, for example, entry/src/main/module.json5.

NOTE

Using the sample code in the actual project may cause a compilation failure. You need to configure the code as required. For example, if the resource file referenced by the $ symbol does not exist in the project, you need to manually add the resource file or replace it with the actual one.

In the configuration file, fields can be repeated. The last field is used.

Configuration File Example

This topic gives an overview of the module.json5 configuration file. To start with, let's go through an example of what this file contains.

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "tv",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "pages": "$profile:main_pages", // Resource configuration, pointing to the main_pages.json configuration file defined in the profile.
    "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", // Resource configuration, which points to the menu.json configuration file defined in the profile.
    "crossAppSharedConfig": "$profile:shared_config",
    // ...
  }
}

Tags in the Configuration File

As shown above, the module.json5 file contains several tags.

Table 1 Tags in the module.json5 file

deviceTypes

Table 2 deviceTypes

Example of the deviceTypes structure:

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

pages

The pages tag is a profile that represents information about specified pages.

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // Resource configuration, pointing to the main_pages.json configuration file defined in the profile.
    // ...
  }
}

Define the main_pages.json file under resources/base/profile in the development view. The file name (main_pages in this example) can be customized, but must be consistent with the information specified by the pages tag. The file lists the page information of the current application, including the route information and the window-related configuration.

Table 3 pages

Table 4 window

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

metadata

The metadata tag represents the custom metadata of the HAP. The tag value is an array and contains three subtags: name, value, and resource.

Table 5 metadata

{
  "module": {
    // ...
    "metadata": [
      // ...
      {
        "name": "pageConfig",
        "value": "main page config of application",
        "resource": "$profile:main_pages" // Resource configuration, pointing to the main_pages.json configuration file defined in the profile.
      }
    ],
    // ...
  }
}

abilities

The abilities tag represents the UIAbility configuration of the module, which is valid only for the current UIAbility component.

Table 6 abilities

Example of the abilities structure:

{
  // ...
    "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, // This tag is supported starting from 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

The skills tag represents the feature set of wants that can be received by the UIAbility or ExtensionAbility component.

For example, when downloading a PDF file in a browser, you can configure the skills tag to open the specified PDF file. For details, see Using startAbility to Start a File Application.

Table 7 skills

Table 8 uris

NOTE

The following tags of the string type cannot be configured using resource indexes ($string).

Example of the skills structure:

NOTE

The following example is a common configuration. Some components and modules are different in actual configuration. For details, see the corresponding document.

{
  // ...
    "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

The extensionAbilities tag represents the configuration of ExtensionAbilities, which is valid only for the current ExtensionAbility.

Table 9 extensionAbilities

Example of the extensionAbilities structure:

{
  // ...
    "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"
        ]
      }
    ],
    // ...
}

shortcuts

The shortcuts tag provides the shortcut information of an application. The value is an array and consists of four sub-attributes: shortcutId, label, icon, and wants.

The shortcut information is specified in metadata, where:

• name indicates the name of the shortcut, identified by ohos.ability.shortcuts.

• resource indicates where the resources of the shortcut are stored.

Table 10 Shortcuts

1. Configure the shortcuts_config.json file in /resources/base/profile/.

   {
     "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. In the abilities tag of the module.json5 file, configure the metadata tag for the UIAbility component to which a shortcut needs to be added so that the shortcut configuration file takes effect for the 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

The wants tag provides wants information for a shortcut.

Table 11 wants

Example of the wants tag:

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

distributionFilter

The distributionFilter tag defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when the application market distributes applications.

NOTE This tag is supported since API version 10. For API version 9 and earlier, the distroFilter tag is used.

• Application scenario: If a project has multiple entry-type modules and the values of deviceType configured for these modules overlap, you need to use this tag to distinguish the modules. In the following example, both entry-type modules support the tablet type, and therefore the distributionFilter tag is required.

  // Device types supported by entry1
  {
    "module": {
      "name": "entry1",
      "type": "entry",
      "deviceTypes": [
        "tv",
        "tablet"
      ],
      // ...
  }
  

  module.json5

  // Device types supported by entry2
  {
    "module": {
      "name": "entry2",
      "type": "entry",
      "deviceTypes": [
        "tv",
        "tablet"
      ],
      // ...
  }
  

  module.json5

• Configuration rule: This tag consists of four attributes, including screenShape, screenWindow, screenDensity, and countryCode. For details, see the following table.

  During distribution, a unique HAP is determined based on the mapping between deviceTypes and the preceding attributes.

  • When configuring this tag, include at least one of the attributes.
  • If any one or more attributes are set for one entry-type module, the same attributes must be set for all other entry-type modules.
  • The screenShape and screenWindow attributes are available only for lite wearables.

• Configuration: This tag must be configured in the /resources/base/profile directory and be referenced in the resource tag of metadata.

Table 12 distributionFilter

screenShape

Table 13 screenShape

screenWindow

Table 14 screenWindow

screenDensity

Table 15 screenDensity

countryCode

Table 16 countryCode

Example:

1. Configure the distributionFilter_config.json file (this file name is customizable) in resources/base/profile under the development view.

   {
     "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. Configure metadata in the module tag in the module.json5 file.

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

testRunner

The testRunner tag represents the supported test runner.

Table 17 testRunner

Example of the testRunner structure:

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

atomicService

The atomicService tag represents the atomic service configuration. It takes effect only when bundleType is set to atomicService in the app.json5 file.

Table 18 atomicService

Table 19 preloads

Example of the atomicService structure:

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

dependencies

The dependencies tag identifies the list of shared libraries that the module depends on when it is running.

Table 20 dependencies

Example of the dependencies structure:

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

proxyData

The proxyDatas tag provides the list of data proxies provided by the module. It can be configured only for entry and feature modules.

Table 21 proxyData

Example of the proxyData structure:

{
  "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

The routerMap tag represents the path to the routing table for the module.

The routerMap configuration file provides the routing table information of the module. The value of the routerMap tag is an array.

Table 22 routerMap

Example:

1. Define a routing table configuration file under resources/base/profile in the development view. The file name can be customized, for example, 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. Define the routerMap tag under module of the module.json5 file, set it to point to the defined routing table configuration file, for example, set it to "routerMap": "$profile:router_map".

data

The data tag is used to configure custom string data in the routing table.

Example of the data structure:

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

customData

The data tag represents custom data in the routing table.

The customData tag is used to configure custom data of any type.

Example of the customData structure:

{
  "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

The appEnvironments tag represents the application environment variables configured for the module.

Table 23 appEnvironments

Example of the appEnvironments structure:

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

hnpPackages

The hnpPackages tag provides information about the native software package contained in the application.

Table 24 hnpPackages

Example of the hnpPackages structure:

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

fileContextMenu

The fileContextMenu tag provides configuration options for the context menu (displayed upon right-clicking) of the current HAP. It is a profile that contains the context menu configuration registered by the application. This tag takes effect only on PCs/2-in-1 devices and can be configured only in entry modules.

Example of the fileContextMenu structure:

{
  "module": {
    // ...
    "fileContextMenu": "$profile:menu", // Resource configuration, which points to the menu.json configuration file defined in the profile.
    // ...
  }
}

Define the menu.json file under resources/base/profile in the development view. The file name (menu.json in this example) can be customized, but must be consistent with the information specified by the fileContextMenu tag. The file describes the items and response behavior of the context menu registered by the application.

The root node of the file is fileContextMenu, which is an object array and indicates the number of context menus registered by the current module. (The number must not exceed 5 per module and per application. If the number exceeds 5, only five random menus are parsed.)

Table 25 fileContextMenu

Table 26 menuContext

Example of the menu.json file in the resources/base/profile directory:

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

Response Behavior

After a context menu is registered, the More option of the menu, when clicked, displays a sublist of menu items specified in menuItem. After you click any of the items, the file manager starts the third-party application using startAbility by default. In addition to the bundle name and ability name of the third-party application, the following tags are also passed in parameter of want:

Table 27 parameter field in want

startWindow

This tag points to a profile resource and is used to define the configuration file start_window.json of the UIAbility startup page in resources/base/profile. If this tag is set, the startWindowIcon and startWindowBackground tags do not take effect.

NOTE

Since API version 20, this tag can be used to configure an enhanced starting window.

Table 28 startWindow

Example of the start_window.json file in the resources/base/profile directory:

{
  "startWindowType": "REQUIRED_SHOW",
  "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

The systemTheme tag points to a profile resource, which is used to specify the system theme configuration file used by the current application. This tag is supported since API version 20.

Example:

{
  "module": {
    // ...
    "systemTheme": "$profile:theme_config", // Resource configuration, which points to the theme_config.json configuration file defined in the profile.
  }
}

Define the theme_config.json configuration file in resources/base/profile. The file's base name can be customized but must be either theme_config or a name that starts with theme_config (e.g. theme_config_1). The configuration file specifies the system theme used by the current application, corresponding to the information specified by the systemTheme tag.

Table 29 theme_config.json

Example of the theme_config.json file in the resources/base/profile directory:

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

definePermissions

The definePermissions tag represents a set of permissions defined for the system resource HAP, which cannot be custom permissions. For details about how to define permissions, see the config.json file.

Table 30 definePermissions

Example of the definePermissions structure:

{
  "module": {
    // ...
    "definePermissions": [
      {
        "name": "ohos.permission.ACCESS_BLUETOOTH",
        "grantMode": "system_grant",
        "availableLevel": "system_core",
        "provisionEnable": true,
        "distributedSceneEnable": false,
        "label": "$string:EntryAbility_label"
      }
    ],
    // ...
  },
}

executableBinaryPaths

The executableBinaryPaths tag identifies the path of the executable binary file in the application.

Table 31 executableBinaryPaths

Example of the executableBinaryPaths structure:

{
  "module": {
    // ...
    "executableBinaryPaths": [
      {
        "path": "framework/test.bin"
      }
    ],
    // ...
  },
}