配置文件概述
本文以Stage模型為例，詳細介紹了HarmonyOS NEXT應用的各種配置文件，這些配置文件會向編譯工具、操作系統和應用市場提供應用的基本信息。
在基于Stage模型開發的應用項目代碼下，都存在一個app.json5的配置文件、以及一個或者多個module.json5配置文件。
應用配置文件
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},
}
app.json5配置文件主要包含一下內容：
- 應用的全局配置信息，包含應用的Bundle名稱、開發廠商、版本號等基本信息。
- 特定設備類型的配置信息。
具體屬性如下表：
| 屬性名稱 | 屬性含義 | 數據類型 | 是否必填 |
|---|---|---|---|
bundleName | 標識應用的Bundle名稱，用于標識應用的唯一性。命名規則如下 ： - 由字母、數字、下劃線和符號“.”組成，且必須以字母開頭。 - 字符串最小長度為7字節，最大長度為128字節。 - 推薦采用反域名形式命名（如 com.example.demo，建議第一級為域名后綴com，第二級為廠商/個人名，第三級為應用名，也可以多級）。對于隨系統源碼編譯的應用，建議命名為com.ohos.demo形式，其中的ohos標識系統應用。 | string | 是 |
bundleType | 標識應用的Bundle類型，用于區分應用或者元服務。支持的取值如下： - app：當前Bundle為應用。 - atomicService：當前Bundle為元服務。 shared：當前Bundle為共享庫應用，預留字段。 - appService：當前Bundle為系統級共享庫應用，僅供系統應用使用。 | string | 否，默認值為app |
debug | 標識應用是否可調試。 - true：可以進行斷點調試。 - false：不可以進行斷點調試。 | Boolean | 否，默認值為false |
icon | 標識應用的圖標，取值為圖標資源文件的索引。 | string | 是 |
label | 標識應用的名稱，取值為字符串資源的索引，字符串長度不超過63字節。 | string | 是 |
description | 標識應用的描述信息。取值為長度不超過255字節的字符串，內容為描述信息的字符串資源索引。 | string | 否，默認值為空 |
versionCode | 標識應用的版本號，取值為小于2^31的正整數。此數字僅用于確定某個版本是否比另一個版本更新，數值越大標識版本越高。 開發者可以將該值設置為任何正整數，但是必須確保應用的新版本都使用比舊版本更大的值。 | number | 是 |
versionName | 標識向用戶展示的應用版本號。 取值為長度不超過127字節的字符串，僅由數字和點構成，推薦采用“A.B.C.D"四段式的形式。四段式推薦的含義如下所示。 第一段：主版本號/Major，范圍0~99，重大修改的版本，如實現新的大功能或重大變化。 第二段：次版本號/Minor，范圍0~99，表示實現較突出的特點，如新功能添加或大問題修復。 第三段：特性版本號/Feature，范圍0~99，標識規劃的新版本特性。 第四段：修訂版本號/Parch，范圍0~999，表示維護版本，如修復bug。 | string | 是 |
minCompatibleVersionCode | 標識應用能夠兼容的最低歷史版本號，用于應用跨設備兼容性判斷，取值范圍為0~2147483647。 | number | 否，默認值為versionCode標簽的值。 |
minAPIVersion | 標識應用運行需要的SDK的API最小版本。取值范圍為0~2147482647 | number | 應用編譯構建時由build-profile.json5中的compatibleSdkVersion自動生成。 |
targetAPIVersion | 標識應用運行需要的API目標版本。取值范圍為0~2147483647。 | number | 應用編譯構建時由build-profile.json5中的compileSdkVersion自動生成。 |
apiReleaseType | 標識應用運行需要的API目標版本的類型，采用字符串類型表示。取值為”CaneryN"、“BetaN”或者“Release”，其中，N代表大于零的整數。 - Canary：受限發布的版本。 - Beta：公開發布的 Beta版本。- Release：公開發布的正式版本。 | string | 應用編譯構建時根據當前使用的SDK的Stage自動生成。即便手動配置了取值，編譯構建時也會被覆蓋。 |
accessible | 標識應用是否能訪問應用的安裝目錄，僅針對Stage模型的系統應用和預置應用生效。 | boolean | 否，默認值為false。 |
multiProjects | 標識當前工程是否支持多個工程的聯合開發。 true：當前工程支持多個工程的聯合開發。 - false：當前工程不支持多個工程的聯合開發。 | 否，默認值為false。 | |
asanEnabled | 標識應用程序是否開啟asan檢測，用于輔助定位buffer越界造成的crash問題。- true：當前工程開啟 asan檢測。- false：當前工程不開啟 asan檢測。 | boolean | 否，默認值為false。 |
tablet | 標識對tablet設備做的特殊配置，可以配置的屬性字段有minAPIVersion。如果使用該屬性對tablet設備做了特殊配置，則應用在tablet設備中會采用此處配置的屬性值，并忽略在app.json5公共區域配置的屬性值。 | object | 否，默認值為app.json5公共區域配置的屬性值。 |
tv | 標識對tv設備做的特殊配置，可以配置的屬性字段有minAPIVersion。如果使用該屬性對tv設備做了特殊配置，則應用在tv設備中會采用此處配置的屬性值，并忽略在app.json5公共區域配置的屬性值。 | object | 否，默認值為app.json5公共區域配置的屬性值。 |
wearable | 標識對wearable設備做的特殊配置，可以配置的屬性字段有minAPIVersion。如果使用該屬性對wearable設備做了特殊配置，則應用在wearable設備中會采用此處配置的屬性值，并忽略在app.json5公共區域配置的屬性值。 | object | 否，默認值為app.json5公共區域配置的屬性值。 |
car | 標識對car設備做的特殊配置，可以配置的屬性字段有minAPIVersion。如果使用該屬性對car設備做了特殊配置，則應用在car設備中會采用此處配置的屬性值，并忽略在app.json5公共區域配置的屬性值。 | object | 否，默認值為app.json5公共區域配置的屬性值。 |
default | 標識對default設備做的特殊配置，可以配置的屬性字段有minAPIVersion。如果使用該屬性對default設備做了特殊配置，則應用在default設備中會采用此處配置的屬性值，并忽略在app.json5公共區域配置的屬性值。 | object | 否，默認值為app.json5公共區域配置的屬性值。 |
targetBundleName | 標識當前包所指定的目標應用，標簽值的取值規則和范圍與bundleName標簽一致。配置該字段的應用為具有overlay特征的應用 | string | 否，默認值為空。 |
targetPriority | 標識當前應用的優先級，取值范圍為1~100。配置targetBundleName字段之后，才支持配置該字段。 | number | 否，默認值為1。 |
generateBuildHash | 標識當前應用的所有HAP和HSP是否由打包工具生成哈希值。該字段配置為true時，該應用下的所有HAP和HSP都會由打包工具生成對應的哈希值。系統OTA升級時，若應用的versionCode保持不變，可根據哈希值判斷應用是否需要升級。說明：該字段僅對預置應用生效。 | boolean | 否，默認值為false。 |
GWPAsanEnabled | 標識應用程序是否開啟GWP-asan堆內存檢測工具，用于對內存越界、內存釋放后使用等內存破壞問題進行分析。- true：當前工程開啟 GWP-asan檢測。- false：當前工程不開啟 GWP-asan檢測。 | boolean | 否，默認值為false。 |
appEnvironments | 標識當前模塊配置的應用環境變量。 | Array | 否，默認值為空。 |
maxChildProcess | 標識當前應用自身可創建的子進程的最大個數，取值范圍為0~512，0表示不限制，當應用有多個模塊時，以entry模塊的配置為準。 | number | 否，默認使用系統配置的默認值。 |
module.json5配置文件
先通過一個示例，整體認識下module.json5配置文件。
{"module": {"name": "entry","type": "entry","description": "$string:module_desc","mainElement": "EntryAbility","deviceTypes": ["tv","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"}}]},"targetModuleName": "feature","targetPriority": 50,"isolationMode": "nonisolationFirst"
}
module.json5配置文件主要包含以下內容：
Module的基本配置信息，包含Module名稱、類型、描述、支持的設備類型等基本信息。- 應用組件信息，包含UIAbility組件和ExtensionAbility組件的描述信息。
- 應用運行過程中所需的權限信息。
具體屬性如下表：
| 屬性名稱 | 屬性含義 | 數據類型 | 是否必輸 |
|---|---|---|---|
name | 標識當前Module的名稱，確保該名稱在整個應用中唯一。取值為長度不超過31字節的字符串，不支持中文。應用升級時允許修改該名稱，但需要應用適配Module相關數據目錄的遷移 | string | 是 |
type | 標識當前Module的類型。支持的取值如下：- entry：應用的主模塊。 - feature：應用的動態特性模塊。 *- har*：靜態共享包模塊。 - shared：動態共享包模塊。 | string | 是 |
srcEntry | 標識當前Module所對應的代碼路徑，取值為長度不超過127字節的字符串。 | string | 否，默認值為空。 |
description | 標識當前Module的描述信息，取值為長度不超過255字節的字符串，可以采用字符串資源索引格式。 | string | 否，默認值為空。 |
process | 標識當前Module的進程名，取值為長度不超過31字節的字符串。如果在HAP標簽下配置了process，則該應用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都運行在該進程中。說明：僅支持系統應用配置，第三方應用配置不生效。 | string | 否，默認值為app.json5文件下app標簽下的bundleName。 |
mainElement | 標識當前Module的入口UIAbility名稱或者ExtensionAbility名稱，取值為長度不超過255字節的字符串。 | string | 否，默認值為空。 |
deviceTypes | 標識當前Module可以運行在哪類設備上。 | Array | 是 |
deliveryWithInstall | 標識當前Module是否在用戶主動安裝的時候安裝，即該Module對應的HAP是否跟隨應用一起安裝。- true：主動安裝時安裝。 - false：主動安裝時不安裝 | boolean | 是 |
installationFree | 標識當前Module是否支持免安裝特性。- true：表示支持免安裝特性，且符合免安裝約束。 - false：表示不支持免安裝特性。 說明：當 bundleType為元服務時，該字段需要配置為true。反之，該字段需要配置為false。 | boolean | 是 |
virtualMachine | 標識當前Module運行的目標虛擬機類型，僅供云端分發使用，如應用市場和分發中心。如果目標虛擬機類型為ArkTS引擎，則其值為“ark+版本號”。 | string | 該標簽由IDE構建HAP的時候自動插入。 |
pages | 標識當前Module的profile資源，用于列舉每個頁面信息，取值為長度不超過255字節的字符串。 | string | 在有UIAbility的場景下，該標簽必輸。 |
metadata | 標識當前Module的自定義元信息，可通過資源引用的方式配置distributionFilter、shortcuts等信息。只對當前Module、UIAbility、ExtensionAbility生效。 | Array | 否，默認值為空。 |
abilities | 標識當前Module中UIAbility的配置信息，只對當前UIAbility生效。 | Array | 否，默認值為空。 |
extensionAbilities | 標識當前Module中ExtensionAbility的配置信息，只對當前ExtensionAbility生效。 | Array | 否，默認值為空。 |
definePermissions | 標識系統資源hap定義的權限，不支持應用自定義權限。 | Array | 否，默認值為空。 |
requestPermissions | 標識當前應用運行時需向系統申請的權限集合。 | Array | 否，默認值為空。 |
testRunner | 標識用于測試當前Mobule的測試框架的配置。 | object | 否，默認值為空。 |
atomicService | 標識當前應用是元服務時，有關元服務的相關配置。 | object | 否 |
dependencies | 標識當前模塊運行時依賴的共享庫列表。 | Array | 否，默認值為空。 |
targetModuleName | 標識當前包所指定的目標module，確保該名稱在整個應用中唯一。取值為長度不超過31字節的字符串，不支持中文。配置該字段的Module具有overlay特性。僅在動態共享包(HSP)中適用。 | string | 否，默認值為空。 |
targetPriority | 標識當前Module的優先級，取值范圍為1~100。配置targetModuleName字段之后才需要配置該字段。僅在動態共享包（HSP）中適用。 | Integer | 否，默認值為1。 |
proxyData | 標識當前Module提供的數據代理列表 | Array | 否，默認值為空。 |
isolationMode | 標識當前Module的多進程配置項。支持的取值如下：- nonisolationFirst：優先在非獨立進程中進行。 - isolationFirst：優先在獨立進程中運行。 - isolationOnly：只在獨立進程中運行。 - nonisolationOnly：只在非獨立進程中運行。 | string | 否，默認值為nonisolationFirst。 |
generateBuildHash | 標識當前HAP/HSP是否由打包工具生成哈希值。當配置為trrue時，如果系統OTA升級時應用versionCode保持不變，可根據哈希值判斷應用是否需要升級。該字段僅在app.json5文件中的generateBuildHash字段為false時生效。說明：該字段僅對預置應用生效。 | boolean | 否，默認值為false。 |
compressNativeLibs | 標識libs庫是否以壓縮存儲的方式打包到HAP。 - true：libs庫以壓縮方式存儲。 - false：libs庫以不壓縮方式存儲。 | boolean | 否，默認值為false。 |
libIsolation | 用于區分同應用不同HAP下的.so文件，以防止.so沖突。 - true：當前HAP的.so文件會存儲在libs目錄中以 Module命名的路徑下。- false：當前HAP的.so文件會直接存儲在libs目錄下。 | string | 否，默認值為false。 |
fileContextMenu | 標識當前HAP的右鍵菜單配置項。取值為長度不超過255字節的字符串。 | string | 否，默認值為空。 |
querySchemes | 標識允許當前應用進行跳轉查詢的URL schemes，只允許entry類型模塊配置，最多50個，每個字符串取值不超過128字節。 | Array | 否，默認值為空。 |
routerMap | 標識當前模塊配置的路由表路徑。取值為長度不超過255字節的字符串 | string | 否，默認值為空。 |
appEnvironments | 標識當前模塊配置的應用環境變量，只允許entry和feature模塊配置。 | Array | 否，默認值為空。 |
appStartup | 標識當前Module啟動框架配置路徑，僅在Entry中生效。 | string | 否，默認值為空。 |
資源配置文件
資源分類
應用開發中使用的各類資源文件，需要放入特定子目錄中存儲管理。資源目錄的示例如下所示，base目錄、限定詞目錄、rawfile目錄、resfile目錄稱為資源目錄，element、media、profile稱之為資源組目錄。
resources
|---base
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---en_US // 默認存在的目錄，設備語言環境是美式英文時，優先匹配此目錄下資源
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---zh_CN // 默認存在的目錄，設備語言環境是簡體中文時，優先匹配此目錄下資源
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---en_GB-vertical-car-mdpi // 自定義限定詞目錄示例，由開發者創建
| |---element
| | |---string.json
| |---media
| | |---icon.png
| |---profile
| | |---test_profile.json
|---rawfile // 其他類型文件，原始文件形式保存，不會被集成到resources.index文件中。文件名可自定義。
|---resfile // 其他類型文件，原始文件形式保存，不會被集成到resources.index文件中。文件名可自定義。
)
