module.json5 Configuration File

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",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "virtualMachine": "ark",
    "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"
        ]
      }
    ],
    "definePermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "grantMode": "system_grant",
        "availableLevel": "system_core",
        "provisionEnable": true,
        "distributedSceneEnable": false,
        "label": "$string:EntryAbility_label"
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when": "inuse"
        }
      }
    ],
    "targetModuleName": "feature",
    "targetPriority": 50,
    "querySchemes": [
      "app1Scheme",
      "app2Scheme"
    ],
    "routerMap": "$profile:router_map",
    "appEnvironments": [
      {
        "name": "name1",
        "value": "value1"
      }
    ],
    "hnpPackages": [
      {
        "package": "hnpsample.hnp",
        "type": "public"
      }
    ],
    "fileContextMenu": "$profile:menu"
  }
}

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 |Device Type|Value|Description| |——–|——–|——–| |Tablet|tablet|-| |Smart TV|tv|-| |Smart watch|wearable|Watch that provides call features.| |Head unit|car|-| |PC/2-in-1 device|2in1|PC, mainly used for multi-window and multi-task interactions, and keyboard and mouse operations. It fully showcases the device productivity. In the OpenHarmony topics, “2-in-1” indicates PC/2-in-1 device.| |Default device|default|Device that provides full access to system capabilities.|

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 pages

Table 4 window

{
  "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. The tag value is an array and contains three subtags: name, value, and resource.

Table 5 metadata

The metadata tag can be used to configure the default size and position (in vp) of the main window in the format of alignment mode +/- offset. The name ohos.ability.window.height indicates the default height, ohos.ability.window.width indicates the default width, and ohos.ability.window.left indicates the default left position,|with alignment modes including center, left (default), and right. If the offset is 0, this parameter can be omitted. The name ohos.ability.window.top indicates the position of the top, with alignment modes including center, top (default), and bottom. If both weight and height are omitted, the system default size is used.

The metadata tag can be used to configure the enabling function of removing the startup page. The name enable.remove.starting.window can be set to true or false. If the value is left empty, the default value false is used.

The value of resource is in the format of $profile:file name, where \$profile indicates that the resource is placed under /resources/base/profile in the project directory. For example, \$profile:shortcuts_config indicates the /resources/base/profile/shortcuts_config.json file.

{
  "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"
      },
      {
        "name": "ohos.ability.window.height",
        "value": "987"
      },
      {
        "name": "ohos.ability.window.width",
        "value": "1300"
      },
      {
        "name": "ohos.ability.window.left",
        "value": "right-50"
      },
      {
        "name": "ohos.ability.window.top",
        "value": "center+50"
      },
      {
        "name": "enable.remove.starting.window",
        "value": "true"
      }],
    }],

    "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:layered_image",
    "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"
    ],
    "startWindow": "$profile:start_window",
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:red",
    "removeMissionAfterTerminate": true,
    "orientation": "$string:orientation",
    "supportWindowMode": ["fullscreen", "split", "floating"],
    "maxWindowRatio": 3.5,
    "minWindowRatio": 0.5,
    "maxWindowWidth": 2560,
    "minWindowWidth": 1400,
    "maxWindowHeight": 300,
    "minWindowHeight": 200,
    "excludeFromMissions": false,
    "unclearableMission": false,
    "excludeFromDock": 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.

Table 7 skills

Table 8 uris

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/*",
              "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": "./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": [],
        "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 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 /resources/base/profile/.

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

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

wants

The wants tag provides wants information for a shortcut.

Table 11-1 wants

Example of the data structure:

{
  "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. In earlier versions, 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"
    ]
  }
  }
  

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

• Configuration rules: This tag consists of four attributes: screenShape, screenWindow, screenDensity, and countryCode.

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 field 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": {// Distribution in China is supported.
        "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 is available only when bundleType is set to atomicService in the app.json file.

Table 18 atomicService

Table 19 preloads

Example of the atomicService 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 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 |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 bundle name/xxx format. The value is a string with a maximum of 255 bytes.|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 levels, see Application Permissions. The value is a string with a maximum of 255 bytes.|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 levels, see Application Permissions. The value is a string with a maximum of 255 bytes.|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"
        }
      }
    ]
  }
}

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

definePermissions

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

Table 24 definePermissions

Example of the definePermissions structure:

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

hnpPackages

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

Table 25 hnpPackages

Example of the hnpPackages structure:

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

fileContextMenu

The fileContextMenu tag provides configuration options for the context menu (displayed upon right-clicking) of the current HAP. It is a profile file that contains the context menu configuration registered by the application.

Example of the fileContextMenu structure:

{
  "module": {
    // ...
    "fileContextMenu": "$profile:menu" // Configured through the resource file 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 26 fileContextMenu

Table 27 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 right-click the file manager, 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 fields are also passed in parameter of want:

Table 28 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 field is set, the startWindowIcon and startWindowBackground fields do not take effect.

Table 29 startWindow configuration

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

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Quick Start

harmony 鸿蒙Creating an Application Clone

harmony 鸿蒙app.json5 Configuration File

harmony 鸿蒙Structure of the app Tag

harmony 鸿蒙Overview of Application Configuration Files in FA Model

harmony 鸿蒙Overview of Application Configuration Files in Stage Model

harmony 鸿蒙Application Installation, Uninstall, and Update

harmony 鸿蒙Application Package Overview

harmony 鸿蒙Application Package Structure in FA Model

harmony 鸿蒙Application Package Structure in Stage Model