配置文件的差異

FA模型應用在[config.json文件]中描述應用的基本信息，一個應用工程中可以創建多個Module，每個Module中都有一份config.json文件。config.json由app、deviceConfig和module三部分組成，app標簽用于配置應用級別的屬性，如果一個應用有多個Module，需要由開發者保證各個config.json文件中app標簽配置的一致性。

Stage模型應用在[app.json5]和[module.json]文件中描述應用的基本信息，和FA模型應用類似，一個Stage模型應用工程中同樣可以創建多個Module，但是一個應用工程中僅存在一份app.json5，用于配置應用級別的屬性，對每個Module都生效；每個Module中都有一份module.json5配置文件，用于配置Module級別的屬性，僅對當前Module生效。 開發前請熟悉鴻蒙開發指導文檔 ：gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md點擊或者復制轉到。

圖1 配置文件差異

app.json5配置文件

配置文件示例

先通過一個示例，整體認識一下app.json5配置文件。

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "description": "$string:description_application",
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "car": {
      "minAPIVersion": 8
    },
    "targetBundleName": "com.application.test",
    "targetPriority": 50,
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ],
    "maxChildProcess": 5,
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 5
    }
  },
}

配置文件標簽

app.json5配置文件包含以下標簽。

表1 app.json5配置文件標簽說明

appEnvironments標簽

此標簽標識應用配置的環境變量。

表1 appEnvironments標簽說明

appEnvironments標簽示例：

{
  "app": {
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ]
  }
}

multiAppMode標簽

應用多開模式。

表1 multiAppMode標簽說明

multiAppMode標簽示例：

{
  "app": {
    "multiAppMode": {
      "multiAppModeType": "appClone",
      "maxCount": 5
    }
  }
}

module.json5配置文件

配置文件示例

先通過一個示例，整體認識一下module.json5配置文件。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "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: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"
            ]
          }
        ],
        "continueType": [
          "continueType1"
        ]
      }
    ],
    "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"
      }
    ]
  }
}

配置文件標簽

module.json5配置文件包含以下標簽。

表1 module.json5配置文件標簽說明

deviceTypes標簽

表2 deviceTypes標簽說明

deviceTypes示例：

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

pages標簽

該標簽是一個profile文件資源，用于指定描述頁面信息的配置文件。

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // 通過profile下的資源文件配置
  }
}

在開發視圖的resources/base/profile下面定義配置文件main_pages.json，其中文件名"main_pages"可自定義，需要和pages標簽指定的信息對應。配置文件中列舉了當前應用組件中的頁面信息，包含頁面的路由信息和顯示窗口相關的配置。

表3 pages標簽說明

表4 window標簽說明

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

metadata標簽

該標簽標識HAP的自定義元信息，標簽值為數組類型，包含name、value、resource三個子標簽。

表5 metadata標簽說明

resource屬性值使用“profile:文件名”的方式指定文件所在位置，profile:文件名”的方式指定文件所在位置，profile表示資源的路徑為工程中的/resources/base/profile目錄下。例如$profile:shortcuts_config指定了/resources/base/profile/shortcuts_config.json文件。

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

abilities標簽描述UIAbility組件的配置信息，標簽值為數組類型，該標簽下的配置只對當前UIAbility生效。

表6 abilities標簽說明

abilities示例：

{
  "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,
    "excludeFromDock": false,
    "preferMultiWindowOrientation": "default",
    "isolationProcess": false,
    "continueType": [
      "continueType1",
      "continueType2"
    ]
  }]
}

skills標簽

該標簽標識UIAbility組件或者ExtensionAbility組件能夠接收的[Want]的特征。

表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": "./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"
      ]
    }
  ]
}

requestPermissions標簽

該標簽標識應用運行時需向系統申請的權限集合

說明：

• 在requestPermissions標簽中配置的權限項將在應用級別生效，即該權限適用于整個應用程序。
• 如果應用需要訂閱自己發布的事件，而且應用在extensionAbilities標簽中的permissions字段中設置了訪問該應用所需要的權限，那么應用也需要在requestPermissions標簽中注冊相關權限才能收到該事件。
• 生態治理中，要求受限的權限必須要校驗usedScene，但是在HAR/HSP中沒有usedScene/ability，會影響構建出包，所以HAR/HSP包中不再校驗這個邏輯。

表10 requestPermissions標簽說明

requestPermissions示例：

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

shortcuts標簽

shortcuts標識應用的快捷方式信息。標簽值為數組，包含四個子標簽shortcutId、label、icon、wants。

metadata中指定shortcut信息，其中：

• name：指定shortcuts的名稱，使用ohos.ability.shortcuts作為shortcuts信息的標識。
• resource：指定shortcuts信息的資源位置。

表11 shortcuts標簽說明

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

   {
     "shortcuts": [
       {
         "shortcutId": "id_test1",
         "label": "$string:shortcut",
         "icon": "$media:aa_icon",
         "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"
             }
           ]
         }
       ]
     }
   }
   

wants標簽

此標簽用于標識快捷方式內定義的目標wants信息集合。

表11-1 wants標簽說明

data標簽示例：

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

distributionFilter標簽

該標簽用于定義HAP對應的細分設備規格的分發策略，以便在應用市場進行云端分發應用包時做精準匹配。

說明： 該標簽從API10及以后版本開始生效，API9及以前版本使用distroFilter標簽。

• 適用場景： 當一個工程中存在多個Entry，且多個Entry配置的deviceTypes存在交集時，則需要通過該標簽進行區分。比如下面的兩個Entry都支持tablet類型，就需要通過該標簽進行區分。

  // entry1支持的設備類型
  {
    "module": {
      "name": "entry1",
      "type": "entry",
      "deviceTypes" : [
        "tv",
        "tablet"
      ]
    }
  }
  

  // entry2支持的設備類型
  {
    "module": {
      "name": "entry2",
      "type": "entry",
      "deviceTypes" : [
        "car",
        "tablet"
      ]
    }
  }
  

• 配置規則： 該標簽支持配置四個屬性，包括屏幕形狀([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.json中bundleType指定為atomicService時使能。

表18 atomicService標簽說明

表19 preloads標簽說明

atomicService標簽示例：

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

dependencies標簽

此標簽標識模塊運行時依賴的共享庫列表。

表20 dependencies標簽說明

dependencies標簽示例：

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

proxyData標簽

此標簽標識模塊提供的數據代理列表，僅限entry和feature配置。

表21 proxyData標簽說明

proxyData標簽示例：

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

此標簽標識模塊配置的路由表的路徑。

routerMap配置文件描述模塊的路由表信息，routerMap標簽值為數組類型。

表22 routerMap標簽說明

示例如下：

1. 在開發視圖的resources/base/profile下面定義配置文件，文件名可以自定義，例如：router_map.json。

   {
     "routerMap": [
       {
         "name": "DynamicPage1",
         "pageSourceFile": "src/main/ets/pages/pageOne.ets",
         "buildFunction": "myFunction"
       },
       {
         "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對象內部，可以填入自定義數據。

data標簽示例：

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

appEnvironments標簽

此標簽標識模塊配置的應用環境變量。

表23 appEnvironments標簽說明

appEnvironments標簽示例：

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

definePermissions標簽

該標簽僅支持系統資源hap定義權限，不支持應用自定義權限。

表24 definePermissions標簽說明

definePermissions標簽示例：

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

hnpPackages標簽

該標簽標識應用包含的Native軟件包信息。

表10 hnpPackages標簽說明

hnpPackages示例：

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

審核編輯 黃宇