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.ets",
        "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"
        }
      }
    ]
  },
  "targetModuleName": "feature",
  "targetPriority": 50
}

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

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: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,
    "unclearableMission": 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. For details about how to request permissions, see Applying for Permissions.

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

1. 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"
             }
           ]
         }
       ]
     }
   }

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": [
      {
        "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 |Name |Description |Data Type|Initial Value Allowed| |———–|——————————|——–|———-| |uri|URI of the data proxy. The URIs configured for different data proxies must be unique and must be in the datashareproxy://Current application package name/xxx format.|String|No| |requiredReadPermission|Permission required for reading data from the data proxy. If it is not specified, other applications will not be able to use the data proxy. For non-system applications, the level of the set permission must be system_basic or system_core. For system applications, the permission level is not limited. For details about the permission level, see Application Permission List.|String|Yes (initial value: left empty)| |requiredWritePermission|Permission required for writing data to the data proxy. If it is not specified, other applications will not be able to use the data proxy. For non-system applications, the level of the set permission must be system_basic or system_core. For system applications, the permission level is not limited. For details about the permission level, see Application Permission List.|String|Yes (initial value: left empty)| |metadata|Metadata of the data proxy. Only the name and resource fields can be configured.|Object|Yes (initial value: left empty)|

Example of the proxyData structure:

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Quick Start

harmony 鸿蒙app.json5 Configuration File

harmony 鸿蒙Internal Structure of the app Tag

harmony 鸿蒙Application Configuration File Overview (FA Model)

harmony 鸿蒙Application Configuration File Overview (Stage Model)

harmony 鸿蒙Application Installation and Uninstallation Process

harmony 鸿蒙Application Package Overview

harmony 鸿蒙Application Package Structure in FA Model

harmony 鸿蒙Application Package Structure in Stage Model

harmony 鸿蒙Application Package Update Process