應用基礎知識
APP
Ability
庫檔案
資源檔案
配置檔案
pack.info
1、APP
HarmonyOS的應用軟體包以APP Pack(Application Package)形式釋出,它是由一個或多個HAP(HarmonyOS Ability Package)以及描述每個HAP屬性的pack.info組成。HAP是Ability的部署包,HarmonyOS應用代碼圍繞Ability元件展開。
一個HAP是由代碼、資源、第三方庫及應用配置檔案組成的子產品包,可分為entry和feature兩種子產品類型,如圖1所示。
- entry:應用的主子產品。一個APP中,對于同一裝置類型必須有且隻有一個entry類型的HAP,可獨立安裝運作。
- feature:應用的動态特性子產品。一個APP可以包含一個或多個feature類型的HAP,也可以不含。隻有包含Ability的HAP才能夠獨立運作。
圖1 APP邏輯視圖
![](https://img.laitimes.com/img/9ZDMuAjOiMmIsIjOiQnIsICM38FdsYkRGZkRG9lcvx2bjxiNx8VZ6l2cs0TPB9UeFR0T6FleOpHOsJGcohVYsR2MMBjVtJWd0ckW65UbM5WOHJWa5kHT20ESjBjUIF2X0hXZ0xCMx81dvRWYoNHLrdEZwZ1Rh5WNXp1bwNjW1ZUba9VZwlHdssmch1mclRXY39CXldWYtlWPzNXZj9mcw1ycz9WL49zZuBnL0kTN2IjN1kDM4AjMxAjMwIzLc52YucWbp5GZzNmLn9Gbi1yZtl2Lc9CX6MHc0RHaiojIsJye.png)
2、Ability
Ability是應用所具備的能力的抽象,一個應用可以包含一個或多個Ability。Ability分為兩種類型:FA(Feature Ability)和PA(Particle Ability)。FA/PA是應用的基本組成單元,能夠實作特定的業務功能。FA有UI界面,而PA無UI界面。
3、庫檔案
庫檔案是應用依賴的第三方代碼(例如so、jar、bin、har等二進制檔案),存放在libs目錄。
4、資源檔案
應用的資源檔案(字元串、圖檔、音頻等)存放于resources目錄下,便于開發者使用和維護,詳見資源檔案的分類。
5、配置檔案
配置檔案 (config.json) 是應用的Ability資訊,用于聲明應用的Ability,以及應用所需權限等資訊,詳見的應用配置檔案。
應用配置檔案:檔案約定
簡介:應用的每個HAP的根目錄下都存在一個“config.json”配置檔案,主要涵蓋以下三個方面:
- 應用的全局配置資訊,包含應用的包名、生産廠商、版本号等基本資訊。
- 應用在具體裝置上的配置資訊。
- HAP包的配置資訊,包含每個Ability必須定義的基本屬性(如包名、類名、類型以及Ability提供的能力),以及應用通路系統或其他應用受保護部分所需的權限等。
檔案約定:配置檔案“config.json”采用JSON檔案格式,由屬性和值兩部分構成:
-
屬性
屬性出現順序不分先後,且每個屬性最多隻允許出現一次。
-
值
每個屬性的值為JSON的基本資料類型(數值、字元串、布爾值、數組、對象或者null類型)。如果屬性值需要引用資源檔案,可參見資源檔案。
6、pack.info
描述應用軟體包中每個HAP的屬性,由IDE編譯生成,應用市場根據該檔案進行拆包和HAP的分類存儲。HAP的具體屬性包括:
- delivery-with-install: 表示該HAP是否支援随應用安裝。“true”表示支援随應用安裝;“false”表示不支援随應用安裝。
- name:HAP檔案名。
- module-type:子產品類型,entry或feature。
- device-type:表示支援該HAP運作的裝置類型。
二、應用配置檔案
1、簡介
應用的每個HAP的根目錄下都存在一個“config.json”配置檔案,主要涵蓋以下三個方面:
- 應用的全局配置資訊,包含應用的包名、生産廠商、版本号等基本資訊。
- 應用在具體裝置上的配置資訊。
- HAP包的配置資訊,包含每個Ability必須定義的基本屬性(如包名、類名、類型以及Ability提供的能力),以及應用通路系統或其他應用受保護部分所需的權限等。
檔案約定
配置檔案“config.json”采用JSON檔案格式,由屬性和值兩部分構成:
-
屬性
屬性出現順序不分先後,且每個屬性最多隻允許出現一次。
-
值
每個屬性的值為JSON的基本資料類型(數值、字元串、布爾值、數組、對象或者null類型)。如果屬性值需要引用資源檔案,可參見資源檔案。
2、配置檔案的元素
此部分提供“config.json”檔案中所有屬性的詳細解釋。
配置檔案的内部結構
應用的配置檔案“config.json”中由“app”、“deviceConfig”和“module”三個部分組成,缺一不可。配置檔案的内部結構說明參見表1。
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
app | 表示應用的全局配置資訊。同一個應用的不同HAP包的“app”配置必須保持一緻。 | 對象 | 否 |
deviceConfig | 表示應用在具體裝置上的配置資訊。 | 對象 | 否 |
module | 表示HAP包的配置資訊。該标簽下的配置隻對目前HAP包生效。 | 對象 | 否 |
app對象的内部結構
app對象包含應用的全局配置資訊,内部結構說明參見表2。
屬性名稱 | 子屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|---|
bundleName | - | 表示應用的包名,用于辨別應用的唯一性。 包名是由字母、數字、下劃線(_)和點号(.)組成的字元串,必須以字母開頭。支援的字元串長度為7~127位元組。 包名通常采用反域名形式表示(例如,com.huawei.himusic)。建議第一級為域名字尾“com”,第二級為廠商/個人名,第三級為應用名,也可以采用多級。 | 字元串 | 否 |
vendor | - | 表示對應用開發廠商的描述。字元串長度不超過255位元組。 | 字元串 | 可預設,預設值為空。 |
version | - | 表示應用的版本資訊。 | 對象 | 否 |
code | 表示應用的版本号,僅用于HarmonyOS管理該應用,對使用者不可見。取值為大于零的整數。 | 數值 | 否 | |
name | 表示應用的版本号,用于向使用者呈現。取值可以自定義。 | 字元串 | 否 | |
apiVersion | - | 表示應用依賴的HarmonyOS的API版本。 | 對象 | 否 |
compatible | 表示應用運作需要的API最小版本。取值為大于零的整數。 | 數值 | 否 | |
target | 表示應用運作需要的API目标版本。取值為大于零的整數。 | 數值 | 可預設,預設值為應用所在裝置的目前API版本。 |
app示例:
"app": {
"bundleName": "com.huawei.hiworld.example",
"vendor": "huawei",
"version": {
"code": 2,
"name": "2.0"
}
"apiVersion": {
"compatible": 3,
"target": 3
}
}
deviceConfig對象的内部結構
deviceConfig包含在具體裝置上的應用配置資訊,可以包含default、car、tv、wearable、liteWearable、smartVision等屬性。default标簽内的配置是适用于所有裝置通用,其他裝置類型如果有特殊的需求,則需要在該裝置類型的标簽下進行配置。内部結構說明參見表3。
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
default | 表示所有裝置通用的應用配置資訊。 | 對象 | 否 |
car | 表示車機特有的應用配置資訊。 | 對象 | 可預設,預設為空。 |
tv | 表示智慧屏特有的應用配置資訊。 | 對象 | 可預設,預設為空。 |
wearable | 表示智能穿戴特有的應用配置資訊。 | 對象 | 可預設,預設為空。 |
liteWearable | 表示輕量級智能穿戴特有的應用配置資訊。 | 對象 | 可預設,預設為空。 |
smartVision | 表示智能攝像頭特有的應用配置資訊。 | 對象 | 可預設,預設為空。 |
default、car、tv、wearable、liteWearable、smartVision等對象的内部結構說明,可參見表4。
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
process | 表示應用或者Ability的程序名。 如果在“deviceConfig”标簽下配置了“process”标簽,則該應用的所有Ability都運作在這個程序中。 如果在“abilities”标簽下也為某個Ability配置了“process”标簽,則該Ability就運作在這個程序中。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 可預設,預設為應用的軟體包名。 |
directLaunch | 表示應用是否支援在裝置未解鎖狀态直接啟動。如果配置為“true”,則表示應用支援在裝置未解鎖狀态下啟動。使用場景舉例:應用支援在裝置未解鎖情況下接聽來電。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 布爾類型 | 可預設,預設為“false”。 |
supportBackup | 表示應用是否支援備份和恢複。如果配置為“false”,則不支援為該應用執行備份或恢複操作。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 布爾類型 | 可預設,預設為“false”。 |
compressNativeLibs | 表示libs庫是否以壓縮存儲的方式打包到HAP包。如果配置為“false”,則libs庫以不壓縮的方式存儲,HAP包在安裝時無需解壓libs,運作時會直接從HAP内加載libs庫。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 布爾類型 | 可預設,預設為“true”。 |
network | 表示網絡安全性配置。該标簽允許應用通過配置檔案的安全聲明來自定義其網絡安全,無需修改應用代碼。 | 對象 | 可預設,預設為空。 |
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
usesCleartext | 表示是否允許應用使用明文網絡流量(例如,明文HTTP)。
| 布爾類型 | 可預設,預設為“false”。 |
securityConfig | 表示應用的網絡安全配置資訊。 | 對象 | 可預設,預設為空。 |
屬性名稱 | 子屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|---|
domainSettings | - | 表示自定義的網域範圍的安全配置,支援多層嵌套,即一個domainSettings對象中允許嵌套更小網域範圍的domainSettings對象。 | 對象 | 可預設,預設為空。 |
cleartextPermitted | 表示自定義的網域範圍内是否允許明文流量傳輸。當usesCleartext和securityConfig同時存在時,自定義網域是否允許明文流量傳輸以cleartextPermitted的取值為準。
| 布爾類型 | 否 | |
domains | 表示域名配置資訊,包含兩個參數:subDomains和name。
| 對象數組 | 否 |
deviceConfig示例:
"deviceConfig": {
"default": {
"process": "com.huawei.hiworld.example",
"directLaunch": false,
"supportBackup": false,
"network": {
"usesCleartext": true,
"securityConfig": {
"domainSettings": {
"cleartextPermitted": true,
"domains": [
{
"subDomains": true,
"name": "example.ohos.com"
}
]
}
}
}
}
}
module對象的内部結構
module對象包含HAP包的配置資訊,内部結構說明參見表7。
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
package | 表示HAP的包結構名稱,在應用内應保證唯一性。采用反向域名格式(建議與HAP的工程目錄保持一緻)。字元串長度不超過127位元組。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 否 |
name | 表示HAP的類名。采用反向域名方式表示,字首需要與同級的package标簽指定的包名一緻,也可采用“.”開頭的命名方式。字元串長度不超過255位元組。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 否 |
description | 表示HAP的描述資訊。字元串長度不超過255位元組。如果字元串超出長度或者需要支援多語言,可以采用資源索引的方式添加描述内容。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 可預設,預設值為空。 |
supportedModes | 表示應用支援的運作模式。目前隻定義了駕駛模式(drive)。 該标簽僅适用于車機。 | 字元串數組 | 可預設,預設值為空。 |
deviceType | 表示允許Ability運作的裝置類型。系統預定義的裝置類型包括:tv(智慧屏)、car(車機)、wearable(智能穿戴)、liteWearable(輕量級智能穿戴)等。 | 字元串數組 | 否 |
distro | 表示HAP釋出的具體描述。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 對象 | 否 |
abilities | 表示目前子產品内的所有Ability。采用對象數組格式,其中每個元素表示一個Ability對象。 | 對象數組 | 可預設,預設值為空。 |
js | 表示基于JS UI架構開發的JS子產品集合,其中的每個元素代表一個JS子產品的資訊。 | 對象 | 可預設,預設值為空。 |
shortcuts | 表示應用的快捷方式資訊。采用對象數組格式,其中的每個元素表示一個快捷方式對象。 | 對象數組 | 可預設,預設值為空。 |
defPermissions | 表示應用定義的權限。應用調用者必須申請這些權限,才能正常調用該應用。 | 對象數組 | 可預設,預設值為空。 |
reqPermissions | 表示應用運作時向系統申請的權限。 | 對象數組 | 可預設,預設值為空。 |
module示例:
"module": {
"package": "com.example.myapplication.entry",
"name": ".MyOHOSAbilityPackage",
"description": "$string:description_application",
"supportedModes": [
"drive"
],
"deviceType": [
"car"
],
"distro": {
"deliveryWithInstall": true,
"moduleName": "ohos_entry",
"moduleType": "entry"
},
"abilities": [
...
],
"shortcuts": [
...
],
"js": [
...
],
"reqPermissions": [
...
],
"defPermissions": [
...
]
}
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
deliveryWithInstall | 表示目前HAP是否支援随應用安裝。
| 布爾類型 | 否 |
moduleName | 表示目前HAP的名稱。 | 字元串 | 否 |
moduleType | 表示目前HAP的類型,包括兩種類型:entry和feature。 | 字元串 | 否 |
distro示例:
"distro": {
"deliveryWithInstall": true,
"moduleName": "ohos_entry",
"moduleType": "entry"
}
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
name | 表示Ability名稱。取值可采用反向域名方式表示,由包名和類名組成,如“com.example.myapplication.MainAbility”;也可采用“.”開頭的類名方式表示,如“.MainAbility”。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 否 |
description | 表示對Ability的描述。取值可以是描述性内容,也可以是對描述性内容的資源索引,以支援多語言。 | 字元串 | 可預設,預設值為空。 |
icon | 表示Ability圖示資源檔案的索引。取值示例:$media:ability_icon。 如果在該Ability的“skills”屬性中,“actions”的取值包含 “action.system.home”,“entities”取值中包含“entity.system.home”,則該Ability的icon将同時作為應用的icon。如果存在多個符合條件的Ability,則取位置靠前的Ability的icon作為應用的icon。 | 字元串 | 可預設,預設值為空。 |
label | 表示Ability對使用者顯示的名稱。取值可以是Ability名稱,也可以是對該名稱的資源索引,以支援多語言。 如果在該Ability的“skills”屬性中,“actions”的取值包含 “action.system.home”,“entities”取值中包含“entity.system.home”,則該Ability的label将同時作為應用的label。如果存在多個符合條件的Ability,則取位置靠前的Ability的label作為應用的label。 | 字元串 | 可預設,預設值為空。 |
uri | 表示Ability的統一資源辨別符。格式為[scheme:][//authority][path][?query][#fragment]。 | 字元串 | 可預設,對于data類型的Ability不可預設。 |
launchType | 表示Ability的啟動模式,支援“standard”和“singleton”兩種模式:
| 字元串 | 可預設,預設值為“standard”。 |
visible | 表示Ability是否可以被其他應用調用。
| 布爾類型 | 可預設,預設值為“false”。 |
permissions | 表示其他應用的Ability調用此Ability時需要申請的權限。通常采用反向域名格式,取值可以是系統預定義的權限,也可以是開發者自定義的權限。如果是自定義權限,取值必須與“defPermissions”标簽中定義的某個權限的“name”标簽值一緻。 | 字元串數組 | 可預設,預設值為空。 |
skills | 表示Ability能夠接收的Intent的特征。 | 對象數組 | 可預設,預設值為空。 |
deviceCapability | 表示Ability運作時要求裝置具有的能力,采用字元串數組的格式表示。 | 字元串數組 | 可預設,預設值為空。 |
type | 表示Ability的類型。取值範圍如下:
| 字元串 | 否 |
formEnabled | 表示FA類型的Ability是否提供卡片(form)能力。該标簽僅适用于page類型的Ability。
| 布爾類型 | 可預設,預設值為“false”。 |
form | 表示AbilityForm的屬性。該标簽僅當“formEnabled”為“true”時,才能生效。 | 對象 | 可預設,預設值為空。 |
orientation | 表示該Ability的顯示模式。該标簽僅适用于page類型的Ability。取值範圍如下:
| 字元串 | 可預設,預設值為“unspecified”。 |
backgroundModes | 表示背景服務的類型,可以為一個服務配置多個背景服務類型。該标簽僅适用于service類型的Ability。取值範圍如下:
| 字元串數組 | 可預設,預設值為空。 |
readPermission | 表示讀取Ability的資料所需的權限。該标簽僅适用于data類型的Ability。取值為長度不超過255位元組的字元串。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 可預設,預設為空。 |
writePermission | 表示向Ability寫資料所需的權限。該标簽僅适用于data類型的Ability。取值為長度不超過255位元組的字元串。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 可預設,預設為空。 |
directLaunch | 表示Ability是否支援在裝置未解鎖狀态直接啟動。如果配置為“true”,則表示Ability支援在裝置未解鎖狀态下啟動。 如果“deviceConfig”和“abilities”中同時配置了“directLaunch”,則采用Ability對應的取值;如果同時未配置,則采用系統預設值。 | 布爾值 | 可預設,預設為“false”。 |
configChanges | 表示Ability關注的系統配置集合。當已關注的配置發生變更後,Ability會收到onConfigurationUpdated回調。取值範圍:
| 字元串數組 | 可預設,預設為空。 |
mission | 表示Ability指定的任務棧。該标簽僅适用于page類型的Ability。預設情況下應用中所有Ability同屬一個任務棧。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 可預設,預設為應用的包名。 |
targetAbility | 表示目前Ability重用的目标Ability。該标簽僅适用于page類型的Ability。如果配置了targetAbility屬性,則目前Ability(即别名Ability)的屬性中僅“name”、“icon”、“label”、“visible”、“permissions”、“skills”生效,其它屬性均沿用targetAbility中的屬性值。目标Ability必須與别名Ability在同一應用中,且在配置檔案中目标Ability必須在别名之前進行聲明。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 字元串 | 可預設,預設值為空。表示目前Ability不是一個别名Ability。 |
multiUserShared | 表示Ability是否支援多使用者狀态進行共享,該标簽僅适用于data類型的Ability。 配置為“true”時,表示在多使用者下隻有一份存儲資料。需要注意的是,該屬性會使visible屬性失效。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 布爾類型 | 可預設,預設值為“false”。 |
supportPipMode | 表示Ability是否支援使用者進入PIP模式(用于在在頁面最上層懸浮小視窗,俗稱“畫中畫”,常見于視訊播放等場景)。該标簽僅适用于page類型的Ability。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 布爾類型 | 可預設,預設值為“false”。 |
abilities示例:
"abilities": [
{
"name": ".MainAbility",
"description": "himusic main ability",
"icon": "$media:ic_launcher",
"label": "HiMusic",
"launchType": "standard",
"orientation": "unspecified",
"permissions": [
],
"visible": true,
"skills": [
{
"actions": [
"action.system.home"
],
"entities": [
"entity.system.home"
]
}
],
"directLaunch": false,
"configChanges": [
"locale",
"layout",
"fontSize",
"orientation"
],
"type": "page",
"formEnabled": false
},
{
"name": ".PlayService",
"description": "himusic play ability",
"icon": "$media:ic_launcher",
"label": "HiMusic",
"launchType": "standard",
"orientation": "unspecified",
"visible": false,
"skills": [
{
"actions": [
"action.play.music",
"action.stop.music"
],
"entities": [
"entity.audio"
]
}
],
"type": "service",
"backgroundModes": [
"audioPlayback"
]
},
{
"name": ".UserADataAbility",
"type": "data",
"uri": "dataability://com.huawei.hiworld.himusic.UserADataAbility",
"visible": true
}
]
屬性名稱 | 子屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|---|
actions | - | 表示能夠接收的Intent的action值,可以包含一個或多個action。 取值通常為系統預定義的action值,詳見《API參考》中的ohos.aafwk.content.Intent類。 | 字元串數組 | 可預設,預設值為空。 |
entities | - | 表示能夠接收的Intent的Ability的類别(如視訊、桌面應用等),可以包含一個或多個entity。 取值通常為系統預定義的類别,詳見《API參考》中的ohos.aafwk.content.Intent類,也可以自定義。 | 字元串數組 | 可預設,預設值為空。 |
uris | - | 表示能夠接收的Intent的uri,可以包含一個或者多個uri。 | 對象數組 | 可預設,預設值為空。 |
scheme | 表示uri的scheme值。 | 字元串 | 不可預設。 | |
host | 表示uri的host值。 | 字元串 | 可預設,預設值為空。 | |
port | 表示uri的port值。 | 字元串 | 可預設,預設值為空。 | |
path | 表示uri的path值。 | 字元串 | 可預設,預設值為空。 | |
type | 表示uri的type值。 | 字元串 | 可預設,預設值為空。 |
skills示例:
"skills": [
{
"actions": [
"action.system.home"
],
"entities": [
"entity.system.home"
],
"uris": [
{
"scheme": "http",
"host": "www.xxx.com",
"port": "8080",
"path": "query/student/name",
"type": "text"
}
]
}
]
屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|
formEntity | 表示AbilityForm支援的顯示方式,目前支援的位置包括:
| 字元串數組 | 可預設,預設值為空。 |
defaultHeight | 表示AbilityForm的預設高度,機關:像素。Form使用方應當根據該值為Form申請相應高度的容器布局。 | 數值 | 可預設,預設值為“0”。 |
defaultWidth | 表示AbilityForm的預設寬度,機關:像素。Form使用方應當根據該值為Form申請相應寬度的容器布局。 | 數值 | 可預設,預設值為“0”。 |
form示例:
"form": {
"formEntity": [
"homeScreen",
"searchbox"
],
"defaultHeight": 100,
"defaultWidth": 200
}
屬性名稱 | 子屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|---|
name | - | 表示JS Module的名字。該标簽不可預設,預設值為default。 | 字元串 | 否 |
pages | - | 表示JS Module的頁面用于列舉JS Module中每個頁面的路由資訊[頁面路徑+頁面名稱]。該标簽不可預設,取值為數組,數組第一個元素代表JS FA首頁。 | 數組 | 否 |
window | - | 用于定義與顯示視窗相關的配置。 該标簽僅适用于智慧屏、智能穿戴、車機。 | 對象 | 可預設。 |
designWidth | 表示頁面設計基準寬度。以此為基準,根據實際裝置寬度來縮放元素大小。 | 數值 | 可預設,預設值為750px。 | |
autoDesignWidth | 表示頁面設計基準寬度是否自動計算。當配置為true時,designWidth将會被忽略,設計基準寬度由裝置寬度與螢幕密度計算得出。 | 布爾類型 | 可預設,預設值為“false”。 |
js示例:
"js": [
{
"name": "default",
"pages": [
"pages/index/index",
"pages/detail/detail"
],
"window": {
"designWidth": 750,
"autoDesignWidth": false
}
}
]
屬性名稱 | 子屬性名稱 | 含義 | 資料類型 | 是否可預設 |
---|---|---|---|---|
shortcutId | - | 表示快捷方式的ID。字元串的最大長度為63位元組。 | 字元串 | 否 |
label | - | 表示快捷方式的标簽資訊,即快捷方式對外顯示的文字描述資訊。取值可以是描述性内容,也可以是辨別label的資源索引。字元串最大長度為63位元組。 | 字元串 | 可預設,預設為空。 |
intents | - | 表示快捷方式内定義的目标intent資訊集合,每個intent可配置兩個子标簽,targetClass, targetBundle。 | - | 可預設,預設為空。 |
targetClass | 表示快捷方式目标類名。 | 字元串 | 可預設,預設值為空。 | |
targetBundle | 表示快捷方式目标Ability所在應用的包名。 | 字元串 | 可預設,預設值為空。 |
示例:
"js": [
{
"name": "default",
"pages": [
"pages/index/index",
"pages/detail/detail"
],
"window": {
"designWidth": 750,
"autoDesignWidth": false
}
}
]
3、配置檔案示例
以JSON檔案為config.json的一個簡單示例,該示例的應用聲明為三個Ability。
{
"app": {
"bundleName": "com.huawei.hiworld.himusic",
"vendor": "huawei",
"version": {
"code": 2,
"name": "2.0"
},
"apiVersion": {
"compatible": 3,
"target": 3
}
},
"deviceConfig": {
"default": {
}
},
"module": {
"package": "com.huawei.hiworld.himusic.entry",
"name": ".MainApplication",
"supportedModes": [
"drive"
],
"distro": {
"moduleType": "entry",
"deliveryWithInstall": true,
"moduleName": "hap-car"
},
"deviceType": [
"car"
],
"abilities": [
{
"name": ".MainAbility",
"description": "himusic main ability",
"icon": "$media:ic_launcher",
"label": "HiMusic",
"launchType": "standard",
"orientation": "unspecified",
"visible": true,
"skills": [
{
"actions": [
"action.system.home"
],
"entities": [
"entity.system.home"
]
}
],
"type": "page",
"formEnabled": false
},
{
"name": ".PlayService",
"description": "himusic play ability",
"icon": "$media:ic_launcher",
"label": "HiMusic",
"launchType": "standard",
"orientation": "unspecified",
"visible": false,
"skills": [
{
"actions": [
"action.play.music",
"action.stop.music"
],
"entities": [
"entity.audio"
]
}
],
"type": "service",
"backgroundModes": [
"audioPlayback"
]
},
{
"name": ".UserADataAbility",
"type": "data",
"uri": "dataability://com.huawei.hiworld.himusic.UserADataAbility",
"visible": true
}
],
"reqPermissions": [
{
"name": "ohos.permission.DISTRIBUTED_DATASYNC",
"reason": "",
"usedScene": {
"ability": [
"com.huawei.hiworld.himusic.entry.MainAbility",
"com.huawei.hiworld.himusic.entry.PlayService"
],
"when": "inuse"
}
}
]
}
}
4、資源檔案的分類
resources目錄
應用的資源檔案(字元串、圖檔、音頻等)統一存放于resources目錄下,便于開發者使用和維護。resources目錄包括兩大類目錄,一類為base目錄與限定詞目錄,另一類為rawfile目錄,詳見表1。
資源目錄示例:
resources
|---base // 預設存在的目錄
| |---element
| | |---string.json
| |---media
| | |---icon.png
|---en_GB-vertical-car-mdpi // 限定詞目錄示例,需要開發者自行建立
| |---element
| | |---string.json
| |---media
| | |---icon.png
|---rawfile // 預設存在的目錄
分類 | base目錄與限定詞目錄 | rawfile目錄 |
---|---|---|
組織形式 | 按照兩級目錄形式來組織,目錄命名必須符合規範,以便根據裝置狀态去比對相應目錄下的資源檔案。 一級子目錄為base目錄和限定詞目錄。
| 支援建立多層子目錄,目錄名稱可以自定義,檔案夾内可以自由放置各類資源檔案。 rawfile目錄的檔案不會根據裝置狀态去比對不同的資源。 |
編譯方式 | 目錄中的資源檔案會被編譯成二進制檔案,并賦予資源檔案ID。 | 目錄中的資源檔案會被直接打包進應用,不經過編譯,也不會被賦予資源檔案ID。 |
引用方式 | 通過指定資源類型(type)和資源名稱(name)來引用,詳見資源檔案的引用方法。 | 通過指定檔案路徑和檔案名來引用,詳見資源檔案的引用方法。 |
限定詞目錄
限定詞目錄可以由一個或多個表征應用場景或裝置特征的限定詞組合而成,包括語言、文字、國家或地區、橫豎屏、裝置類型和螢幕密度等六個次元,限定詞之間通過下劃線(_)或者中劃線(-)連接配接。開發者在建立限定詞目錄時,需要掌握限定詞目錄的命名要求以及與限定詞目錄與裝置狀态的比對規則。
限定詞目錄的命名要求
- 限定詞的組合順序:語言_文字_國家或地區-橫豎屏-裝置類型-螢幕密度。開發者可以根據應用的使用場景和裝置特征,選擇其中的一類或幾類限定詞組成目錄名稱。
- 限定詞的連接配接方式:語言、文字、國家或地區之間采用下劃線(_)連接配接,除此之外的其他限定詞之間均采用中劃線(-)連接配接。例如:zh_Hant_CN、zh_CN-car-ldpi。
- 限定詞的取值範圍:每類限定詞的取值必須符合表2中的條件,否則,将無法比對目錄中的資源檔案。
表2 限定詞取值要求
限定詞類型 含義與取值說明 語言 表示裝置使用的語言類型,由2個小寫字母組成。例如:zh表示中文,en表示英語。
詳細取值範圍,參見ISO 639-1(ISO制定的語言編碼标準)。
文字 表示裝置使用的文字類型,由1個大寫字母(首字母)和3個小寫字母組成。例如:Hans表示簡體中文,Hant表示繁體中文。
詳細取值範圍,參見ISO 15924(ISO制定的文字編碼标準)。
國家或地區 表示使用者所在的國家或地區,由2~3個大寫字母或者3個數字組成。例如:CN表示中國,GB表示英國。
詳細取值範圍,參見ISO 3166-1(ISO制定的國家和地區編碼标準)。
橫豎屏 表示裝置的螢幕方向,取值如下: - vertical:豎屏
- horizontal:橫屏
裝置類型 表示裝置的類型,取值如下: - car:車機
- tv:智慧屏
- wearable:智能穿戴
螢幕密度 表示裝置的螢幕密度(機關為dpi),取值如下: - sdpi:表示小規模的螢幕密度(Small-scale Dots Per Inch),适用于dpi取值為(0, 120]的裝置。
- mdpi:表示中規模的螢幕密度(Medium-scale Dots Per Inch),适用于dpi取值為(120, 160]的裝置。
- ldpi:表示大規模的螢幕密度(Large-scale Dots Per Inch),适用于dpi取值為(160, 240]的裝置。
- xldpi:表示特大規模的螢幕密度(Extra Large-scale Dots Per Inch),适用于dpi取值為(240, 320]的裝置。
- xxldpi:表示超大規模的螢幕密度(Extra Extra Large-scale Dots Per Inch),适用于dpi取值為(320, 480]的裝置。
- xxxldpi:表示超特大規模的螢幕密度(Extra Extra Extra Large-scale Dots Per Inch),适用于dpi取值為(480, 640]的裝置。
限定詞目錄與裝置狀态的比對規則
- 在為裝置比對對應的資源檔案時,限定詞目錄比對的優先級從高到低依次為:區域(語言_文字_國家或地區)> 橫豎屏 > 裝置類型 > 螢幕密度。
- 如果限定詞目錄中包含語言、文字、橫豎屏、裝置類型限定詞,則對應限定詞的取值必須與目前的裝置狀态完全一緻,該目錄才能夠參與裝置的資源比對。例如,限定詞目錄“zh_CN-car-ldpi”不能參與“en_US”裝置的資源比對。
資源組目錄
base目錄與限定詞目錄下面可以建立資源組目錄(包括element、media、animation、layout、graphic、profile),用于存放特定類型的資源檔案,詳見表3。
資源組目錄 | 目錄說明 | 資源檔案 |
---|---|---|
element | 表示元素資源,以下每一類資料都采用相應的JSON檔案來表征。
| element目錄中的檔案名稱建議與下面的檔案名保持一緻。每個檔案中隻能包含同一類型的資料。
|
media | 表示媒體資源,包括圖檔、音頻、視訊等非文本格式的檔案。 | 檔案名可自定義,例如:icon.png。 |
animation | 表示動畫資源,采用XML檔案格式。 | 檔案名可自定義,例如:zoom_in.xml。 |
layout | 表示布局資源,采用XML檔案格式。 | 檔案名可自定義,例如:home_layout.xml。 |
graphic | 表示可繪制資源,采用XML檔案格式。 | 檔案名可自定義,例如:notifications_dark.xml。 |
profile | 表示其他類型檔案,以原始檔案形式儲存。 | 檔案名可自定義。 |
5、資源檔案的使用
資源檔案的引用方法
系統資源檔案
boolean.json示例
color.json示例
float.json示例
intarray.json示例
integer.json示例
pattern.json示例
plural.json示例
strarray.json示例
string.json示例
資源檔案的引用方法
base目錄與限定詞目錄中的資源檔案:通過指定資源類型(type)和資源名稱(name)來引用。
- Java檔案引用資源檔案的格式:ResourceTable.type_name。特别地,如果引用的是系統資源,則采用:ohos.global.systemres.ResourceTable.type_name。
- 示例一:在Java檔案中,引用string.json檔案中類型為“String”、名稱為“app_name”的資源。
ohos.global.resource.ResourceManager resManager = getAbilityContext().getResourceManager();
String result = resManager.getElement(ResourceTable.String_app_name).getString();
示例二:在Java檔案中,引用color.json檔案中類型為“Color”、名稱為“red”的資源。
ohos.global.resource.ResourceManager resManager = getAbilityContext().getResourceManager();
int color = resManager.getElement(ResourceTable.Color_red).getColor();
XML檔案引用資源檔案的格式:$type:name。特别地,如果引用的是系統資源,則采用:$ohos:type:name。
在XML檔案中,引用string.json檔案中類型為“String”、名稱為“app_name”的資源,示例如下:
<?xml version="1.0" encoding="utf-8"?>
<DirectionalLayout xmlns:ohos="http://schemas.huawei.com/res/ohos"
ohos:width="match_parent"
ohos:height="match_parent"
ohos:orientation="vertical">
<Text ohos:text="$string:app_name"/>
</DirectionalLayout>
rawfile目錄中的資源檔案:通過指定檔案路徑和檔案名稱來引用。
在Java檔案中,引用一個路徑為“resources/rawfile/”、名稱為“example.js”的資源檔案,示例如下:
ohos.global.resource.ResourceManager resManager = getAbilityContext().getResourceManager();
ohos.global.resource.RawFileEntry rawFileEntry = resManager.getRawFileEntry("resources/rawfile/example.js");
系統資源檔案
目前支援的系統資源檔案詳見表1。
系統資源名稱 | 含義 | 類型 |
---|---|---|
ic_app | 表示HarmonyOS應用的預設圖示。 | 媒體 |
request_location_reminder_title | 表示“請求使用裝置定位功能”的提示标題。 | 字元串 |
request_location_reminder_content | 表示“請求使用裝置定位功能”的提示内容,即:請在下拉快捷欄打開"位置資訊"開關。 | 字元串 |
boolean.json示例
{
"boolean":[
{
"name":"boolean_1",
"value":true
},
{
"name":"boolean_ref",
"value":"$boolean:boolean_1"
}
]
}
color.json示例
{
"color":[
{
"name":"red",
"value":"#ff0000"
},
{
"name":"red_ref",
"value":"$color:red"
}
]
}
float.json示例
{
"float":[
{
"name":"float_1",
"value":"30.6"
},
{
"name":"float_ref",
"value":"$float:float_1"
},
{
"name":"float_px",
"value":"100px"
}
]
}
intarray.json示例
{
"intarray":[
{
"name":"intarray_1",
"value":[
100,
200,
"$integer:integer_1"
]
}
]
}
integer.json示例
{
"integer":[
{
"name":"integer_1",
"value":100
},
{
"name":"integer_ref",
"value":"$integer:integer_1"
}
]
}
pattern.json示例
{
"pattern":[
{
"name":"base",
"value":[
{
"name":"width",
"value":"100vp"
},
{
"name":"height",
"value":"100vp"
},
{
"name":"size",
"value":"25px"
}
]
},
{
"name":"child",
"parent":"base",
"value":[
{
"name":"noTitile",
"value":"Yes"
}
]
}
]
}
plural.json示例
{
"plural":[
{
"name":"eat_apple",
"value":[
{
"quantity":"one",
"value":"%d apple"
},
{
"quantity":"other",
"value":"%d apples"
}
]
}
]
}
strarray.json示例
{
"strarray":[
{
"name":"size",
"value":[
{
"value":"small"
},
{
"value":"$string:hello"
},
{
"value":"large"
},
{
"value":"extra large"
}
]
}
]
}
string.json示例
{
"string":[
{
"name":"hello",
"value":"hello base"
},
{
"name":"app_name",
"value":"my application"
},
{
"name":"app_name_ref",
"value":"$string:app_name"
},
{
"name":"app_sys_ref",
"value":"$ohos:string:request_location_reminder_title"
}
]
}