module.json5 Configuration File

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": [
      "default",
      "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"
        }
      }
    ]
  }
}

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" : [
       "tablet"
    ]
  }
}

pages

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

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // Configured through the resource file 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 Tags in the pages configuration file

Table 4 window tag in the pages configuration file

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

metadata

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

Table 5 metadata

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

UIAbility configuration of the module, which is valid only for the current UIAbility component.

By default, application icons cannot be hidden from the home screen in OpenHarmony.

The OpenHarmony system imposes a strict rule on the presence of application icons. If no icon is configured in the HAP file of an application, the system uses the icon specified in the app.json file as the application icon and displays it on the home screen.

Touching this icon will direct the user to the application details screen in Settings, as shown in Figure 1.

To hide an application icon from the home screen, you must configure the AllowAppDesktopIconHide privilege. For details, see Application Privilege Configuration Guide.

Objectives:

This requirement on application icons is intended to prevent malicious applications from deliberately configuring no icon to block uninstallation attempts.

Setting the application icon to be displayed on the home screen:

Set icon, label, and skills under abilities in the module.json5 file. In addition, make sure the skills configuration contains ohos.want.action.home and entity.system.home.

{
  "module":{

    ...

    "abilities": [{
      "icon": "$media:icon",
      "label": "Login",
      "skills": [{
        "actions": ["ohos.want.action.home"],
        "entities": ["entity.system.home"],
        "uris": []
      }]
    }],
    ...

  }
}

Display rules of application icons and labels on the home screen:

• The HAP file contains UIAbility configuration.
  • The application icon on the home screen is set under abilities in the module.json5 file.
    • The application does not have the privilege to hide its icon from the home screen.
      • The application icon displayed on the home screen is the icon configured for the UIAbility.
      • The application label displayed on the home screen is the label configured for the UIAbility. If no label is configured, the bundle name is returned.
      • The name of the UIAbility is displayed.
      • When the user touches the home screen icon, the home screen of the UIAbility is displayed.
    • The application has the privilege to hide its icon from the home screen.
      • The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen.
  • The application icon on the home screen is not set under abilities in the module.json5 file.
    • The application does not have the privilege to hide its icon from the home screen.
      • The application icon displayed on the home screen is the icon specified under app. (The icon field in the app.json file is mandatory.)
      • The application label displayed on the home screen is the label specified under app. (The label field in the app.json file is mandatory.)
      • Touching the application icon on the home screen will direct the user to the application details screen shown in Figure 1.
    • The application has the privilege to hide its icon from the home screen.
      • The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen.
• The HAP file does not contain UIAbility configuration.
  • The application does not have the privilege to hide its icon from the home screen.
    • The application icon displayed on the home screen is the icon specified under app. (The icon field in the app.json file is mandatory.)
    • The application label displayed on the home screen is the label specified under app. (The label field in the app.json file is mandatory.)
    • Touching the application icon on the home screen will direct the user to the application details screen shown in Figure 1.
  • The application has the privilege to hide its icon from the home screen.
    • The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen.
      
      

Figure 1 Application details screen

Table 6 abilities

Example of the abilities structure:

{
  "abilities": [{
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ts",
    "launchType":"singleton",
    "description": "$string:description_main_ability",
    "icon": "$media:icon",
    "label": "Login",
    "permissions": [],
    "metadata": [],
    "exported": 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

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

Table 7 skills

Table 8 Internal structure of the uris tag

Example of the skills structure:

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

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": "./form/MyForm.ts",
      "icon": "$media:icon",
      "label" : "$string:extension_name",
      "description": "$string:form_description",
      "type": "form",
      "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
      "readPermission": "",
      "writePermission": "",
      "exported": true,
      "uri":"scheme://authority/path/query",
      "skills": [{
        "actions": [],
        "entities": [],
        "uris": []
      }],
      "metadata": [
        {
          "name": "ohos.extension.form",
          "resource": "$profile:form_config",
        }
      ]
    }
  ]
}

requestPermissions

The requestPermissions tag represents a set of permissions that the application needs to request from the system for running correctly.

NOTE

• The permission settings configured in the requestPermissions tag apply to the entire application.
• If your application needs to subscribe to an event published by itself and the permissions required for accessing the application are set in the permissions tag under extensionAbilities, then the application must register the related permissions in the requestPermissions tag to receive the event.

Table 10 requestPermissions

Example of the requestPermissions structure:

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

shortcuts

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

The shortcut information is identified 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 11 shortcuts

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

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

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.ts",
           // ...
           "skills": [
             {
               "entities": [
                 "entity.system.home"
               ],
               "actions": [
                 "ohos.want.action.home"
               ]
             }
           ],
           "metadata": [
             {
               "name": "ohos.ability.shortcuts",
               "resource": "$profile:shortcuts_config"
             }
           ]
         }
       ]
     }
   }
   

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. Distribution rules cover the following factors: screen shape, screen size, screen resolution, and country/region code. During distribution, a unique HAP is determined based on the mapping between deviceType and these five factors. This tag must be configured in the /resource/profile resource directory. Its sub-tags are optional.

Table 12 distributionFilter

Table 13 Internal structure of the screenShape tag

Table 14 Internal structure of the screenWindow tag

Table 15 Internal structure of the screenDensity tag

Table 16 Internal structure of the countryCode tag

Configure the distro_filter_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": {// Distribution to the Chinese mainland and Hong Kong, China is supported.
      "policy": "include",
      "value": [
        "CN",
        "HK"
      ]
    }
  }
}

Configure metadata in the module tag in the module.json5 file.

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

testRunner

The testRunner tag represents the supported test runner.

Table 17 Internal structure of the testRunner tag

Example of the testRunner structure:

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

atomicService

The atomicService tag represents the atomic service configuration. It is available only when bundleType is set to atomicService in the app.json file.

Table 18 Internal structure of the atomicService tag

Example of the atomicService structure:

{
  "module": {
    "atomicService": {
      "preloads":[
        {
          "moduleName":"feature"
        }
      ]
    }
  }
}

preloads

The preloads tag represents a list of modules to pre-load in an atomic service.

Table 19 Internal structure of the preloads tag

Example of the preloads structure:

{
  "module": {
    "atomicService": {
      "preloads":[
        {
          "moduleName":"feature"
        }
      ]
    }
  }
}

dependencies

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

Table 20 Internal structure of the dependencies tag

Example of the dependencies structure:

{
  "module": {
    "dependencies": [
      {
        "moduleName": "library"
      }
    ]
  }
}