ServiceAbility組件概述

ServiceAbility，即"基于Service模板的Ability"，主要用于后臺(tái)運(yùn)行任務(wù)（如執(zhí)行音樂播放、文件下載等），不提供用戶交互界面。ServiceAbility可由其他應(yīng)用或PageAbility啟動(dòng)，即使用戶切換到其他應(yīng)用，ServiceAbility仍將在后臺(tái)繼續(xù)運(yùn)行。

ServiceAbility組件配置

與PageAbility類似，ServiceAbility的相關(guān)配置在config.json配置文件的"module"對(duì)象的"abilities"對(duì)象中，與PageAbility的區(qū)別在于"type"屬性及"backgroundModes"屬性。

表1 ServiceAbility部分配置項(xiàng)說明

module對(duì)象內(nèi)部結(jié)構(gòu)

module對(duì)象包含HAP的配置信息。

表1****module對(duì)象內(nèi)部結(jié)構(gòu)說明

module示例：

{
  "module": {
    "mainAbility": ".EntryAbility",
    "deviceType": [
      "default",
      "tablet"
    ],
    "abilities": [
      {
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ],
        "orientation": "unspecified",
        "visible": true,
        "srcPath": "EntryAbility",
        "name": ".EntryAbility",
        "srcLanguage": "ets",
        "icon": "$media:icon",
        "description": "$string:MainAbility_desc",
        "formsEnabled": false,
        "label": "$string:MainAbility_label",
        "type": "page",
        "launchType": "multiton"
      }
    ],
    "distro": {
      "moduleType": "entry",
      "installationFree": false,
      "deliveryWithInstall": true,
      "moduleName": "entry"
    },
    "package": "com.example.entry",
    "srcPath": "",
    "name": ".entry",
    "js": [
      {
        "mode": {
          "syntax": "ets",
          "type": "pageAbility"
        },
        "pages": [
          "pages/Index"
        ],
        "name": ".EntryAbility",
        "window": {
          "designWidth": 720,
          "autoDesignWidth": false
        }
      }
    ]
  }
}

distro對(duì)象內(nèi)部結(jié)構(gòu)

表2****distro對(duì)象內(nèi)部結(jié)構(gòu)說明

distro示例：

"distro": {
  "moduleName": "ohos_entry",
  "moduleType": "entry",
  "installationFree": true,
  "deliveryWithInstall": true
}

metadata對(duì)象內(nèi)部結(jié)構(gòu)

表3****metadata對(duì)象內(nèi)部結(jié)構(gòu)說明

parameters對(duì)象內(nèi)部結(jié)構(gòu)

表4****parameters對(duì)象內(nèi)部結(jié)構(gòu)說明

results對(duì)象內(nèi)部結(jié)構(gòu)

表5****results對(duì)象內(nèi)部結(jié)構(gòu)說明

customizeData對(duì)象的內(nèi)部結(jié)構(gòu)

表6****customizeData對(duì)象的內(nèi)部結(jié)構(gòu)說明

metadata對(duì)象示例：

"metaData": {
  "parameters" : [{
    "name" : "a test for metadata parameter",
    "type" : "Float",
    // "$string:parameters_description"為文件資源索引值
    "description" : "$string:parameters_description"
  }],
  "results" : [{
    "name" : "a test for metadata result",
    "type" : "Float",
    "description" : "$string:results_description"
  }],
  "customizeData" : [{
    "name" : "a customizeData",
    "value" : "string",
    "extra" : "$string:customizeData_description"
  }]
}

deviceType標(biāo)簽

表7****deviceType標(biāo)簽配置說明

abilities對(duì)象的內(nèi)部結(jié)構(gòu)

表8****abilities對(duì)象的內(nèi)部結(jié)構(gòu)說明

不允許應(yīng)用隱藏入口圖標(biāo)

系統(tǒng)對(duì)無圖標(biāo)應(yīng)用實(shí)施嚴(yán)格管控，防止一些惡意應(yīng)用故意配置無入口圖標(biāo)，導(dǎo)致用戶找不到軟件所在的位置，無法操作卸載應(yīng)用，在一定程度上保證用戶終端設(shè)備的安全。

入口圖標(biāo)的設(shè)置: 需要在配置文件（config.json）中abilities配置下設(shè)置icon，label以及skills，而且skills的配置下必須同時(shí)包含“ohos.want.action.home” 和 “entity.system.home”。

{
  "module":{

    ...

    "abilities": [{
      "icon": "$media:icon",
      "label": "Login",
      "skills": [{
        "actions": ["ohos.want.action.home"],
        "entities": ["entity.system.home"],
        "uris": []
      }]
    }],

    ...

  }
}

如果應(yīng)用確需隱藏入口圖標(biāo)，需要配置AllowAppDesktopIconHide應(yīng)用特權(quán)，具體配置方式參考[應(yīng)用特權(quán)配置指南]。詳細(xì)的入口圖標(biāo)及入口標(biāo)簽的顯示規(guī)則如下。

• HAP中包含Page類型的PageAbility
  • 配置文件（config.json）中abilities配置中設(shè)置了入口圖標(biāo)
    • 該應(yīng)用沒有隱藏圖標(biāo)的特權(quán)
      • 系統(tǒng)將使用該P(yáng)ageAbility配置的icon作為入口圖標(biāo)，并顯示在桌面上。用戶點(diǎn)擊該圖標(biāo)，頁面跳轉(zhuǎn)到該P(yáng)ageAbility首頁。
      • 系統(tǒng)將使用該P(yáng)ageAbility配置的label作為入口標(biāo)簽，并顯示在桌面上（如果沒有配置label，返回包名）。
    • 該應(yīng)用具有隱藏圖標(biāo)的特權(quán)
      • 桌面查詢時(shí)不返回應(yīng)用信息，不會(huì)在桌面上顯示對(duì)應(yīng)的入口圖標(biāo)和標(biāo)簽。
  • 配置文件（config.json）中abilities配置中未設(shè)置入口圖標(biāo)
    • 該應(yīng)用沒有隱藏圖標(biāo)的特權(quán)
      • 系統(tǒng)將使用系統(tǒng)默認(rèn)圖標(biāo)作為入口圖標(biāo)，并顯示在桌面上。用戶點(diǎn)擊該圖標(biāo)，頁面跳轉(zhuǎn)到應(yīng)用管理中對(duì)應(yīng)的應(yīng)用詳情頁面（參考下圖）。
      • 系統(tǒng)將使用應(yīng)用的包名作為入口標(biāo)簽，并顯示在桌面上。
    • 該應(yīng)用具有隱藏圖標(biāo)的特權(quán)
      • 桌面查詢時(shí)不返回應(yīng)用信息，不會(huì)在桌面上顯示對(duì)應(yīng)的入口圖標(biāo)和標(biāo)簽。
• HAP中不包含Page類型的PageAbility
  • 該應(yīng)用沒有隱藏圖標(biāo)的特權(quán)
    • 系統(tǒng)將使用系統(tǒng)默認(rèn)圖標(biāo)作為入口圖標(biāo)，并顯示在桌面上。用戶點(diǎn)擊該圖標(biāo)，頁面跳轉(zhuǎn)到應(yīng)用管理中對(duì)應(yīng)的應(yīng)用詳情頁面（參考下圖）。
    • 系統(tǒng)將使用應(yīng)用的包名作為入口標(biāo)簽，并顯示在桌面上。
  • 該應(yīng)用具有隱藏圖標(biāo)的特權(quán)
    • 桌面查詢時(shí)不返回應(yīng)用信息，不會(huì)在桌面上顯示對(duì)應(yīng)的入口圖標(biāo)和標(biāo)簽。

圖1 應(yīng)用的詳情頁示意圖

注：應(yīng)用詳情頁面中顯示的label可能與桌面上顯示的不同。如果非Page類型的PageAbility配置了入口圖標(biāo)和label，那么詳情頁中顯示的即為配置的。

uriPermission對(duì)象的內(nèi)部結(jié)構(gòu)

表9****uriPermission對(duì)象的內(nèi)部結(jié)構(gòu)說明

abilities示例：

"abilities": [
  {
    "name": ".EntryAbility",
    "description": "test main ability",
    // $media:ic_launcher 為媒體類資源
    "icon": "$media:ic_launcher",
    // $string:example 為字符串類資源
    "label": "$string:example",
    "launchType": "multiton",
    "orientation": "unspecified",
    "permissions": [],
    "visible": true,
    "skills": [
      {
        "actions": [
          "action.system.home"
        ],
        "entities": [
          "entity.system.home"
        ]
      }
    ],
    "configChanges": [
      "locale",
      "layout",
      "fontSize",
      "orientation"
    ],
    "type": "page",
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:red",
    "removeMissionAfterTerminate": true
  },
  {
    "name": ".PlayService",
    "description": "example play ability",
    "icon": "$media:ic_launcher",
    "label": "$string:example",
    "launchType": "multiton",
    "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.example.world.test.UserADataAbility",
    "visible": true
  }
]

skills對(duì)象的內(nèi)部結(jié)構(gòu)

表10****skills對(duì)象的內(nèi)部結(jié)構(gòu)說明

uris對(duì)象的內(nèi)部結(jié)構(gòu)

表11****uris對(duì)象的內(nèi)部結(jié)構(gòu)說明

skills示例：

"skills": [
  {
    "actions": [
      "action.system.home"
    ],
    "entities": [
      "entity.system.home"
    ],
    "uris": [
      {
        "scheme": "http",
        "host": "www.example.com",
        "port": "8080",
        "path": "query/student/name",
        "type": "text/*"
      }
    ]
  }
]

reqPermissions權(quán)限申請(qǐng)

表12****reqPermissions權(quán)限申請(qǐng)字段說明

usedScene對(duì)象內(nèi)部結(jié)構(gòu)

表13****usedScene對(duì)象內(nèi)部結(jié)構(gòu)說明

js對(duì)象的內(nèi)部結(jié)構(gòu)

表14****js對(duì)象的內(nèi)部結(jié)構(gòu)說明

window對(duì)象的內(nèi)部結(jié)構(gòu)

表15****window對(duì)象的內(nèi)部結(jié)構(gòu)說明

mode對(duì)象的內(nèi)部結(jié)構(gòu)

表16****mode對(duì)象的內(nèi)部結(jié)構(gòu)說明

js示例：

"js": [
  {
    "name": ".EntryAbility",
    "pages": [
      "pages/index",
      "pages/detail/detail"
    ],
    "window": {
      "designWidth": 720,
      "autoDesignWidth": false
    },
    "type": "form",
    "mode": {
      "syntax": "ets",
      "type": "pageAbility"
    }
  }
]

shortcuts對(duì)象的內(nèi)部結(jié)構(gòu)

表17****shortcuts對(duì)象的內(nèi)部結(jié)構(gòu)說明

intents對(duì)象的內(nèi)部結(jié)構(gòu)

表18****intents對(duì)象的內(nèi)部結(jié)構(gòu)說明

shortcuts示例：

"shortcuts": [
  {
    "shortcutId": "id",
    // $string:shortcut 為配置的字符串資源值
    "label": "$string:shortcut",
    "intents": [
      {
        "targetBundle": "com.example.world.test",
        "targetClass": "com.example.world.test.entry.EntryAbility"
      }
    ]
  }
]

forms對(duì)象的內(nèi)部結(jié)構(gòu)

表19****forms對(duì)象的內(nèi)部結(jié)構(gòu)說明

customizeData對(duì)象內(nèi)部結(jié)構(gòu)

表20****customizeData對(duì)象內(nèi)部結(jié)構(gòu)說明

forms示例：

"forms": [
  {
    "name": "Form_Js",
    "description": "It's Js Form",
    "type": "JS",
    "jsComponentName": "card",
    "colorMode": "auto",
    "isDefault": true,
    "updateEnabled": true,
    "scheduledUpdateTime": "11:00",
    "updateDuration": 1,
    "defaultDimension": "2*2",
    "supportDimensions": [
      "2*2",
      "2*4",
      "4*4"
    ]
  },
  {
    "name": "Form_Js",
    "description": "It's JS Form",
    "type": "Js",
    "colorMode": "auto",
    "isDefault": false,
    "updateEnabled": true,
    "scheduledUpdateTime": "21:05",
    "updateDuration": 1,
    "defaultDimension": "1*2",
    "supportDimensions": [
      "1*2"
    ],
    "landscapeLayouts": [
      "$layout:ability_form"
    ],
    "portraitLayouts": [
      "$layout:ability_form"
    ],
    "formConfigAbility": "ability://com.example.myapplication.fa/.EntryAbility",
    "metaData": {
      "customizeData": [
        {
          "name": "originWidgetName",
          "value": "com.example.weather.testWidget"
        }
      ]
    }
  }
]

distroFilter對(duì)象的內(nèi)部結(jié)構(gòu)

表21****distroFilter對(duì)象的內(nèi)部結(jié)構(gòu)說明

apiVersion對(duì)象的內(nèi)部結(jié)構(gòu)

表22****apiVersion對(duì)象的內(nèi)部結(jié)構(gòu)說明

screenShape對(duì)象的內(nèi)部結(jié)構(gòu)

表23****screenShape對(duì)象的內(nèi)部結(jié)構(gòu)說明

screenWindow對(duì)象的內(nèi)部結(jié)構(gòu)

表24****screenWindow對(duì)象的內(nèi)部結(jié)構(gòu)說明

screenDensity對(duì)象的內(nèi)部結(jié)構(gòu)

表25****screenDensity對(duì)象的內(nèi)部結(jié)構(gòu)說明

countryCode對(duì)象的內(nèi)部結(jié)構(gòu)

表26****countryCode對(duì)象的內(nèi)部結(jié)構(gòu)說明

distroFilter示例：

"distroFilter":  {
  "apiVersion": {
    "policy": "include",
    "value": [4,5]
  },
  "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","HK"]
  }
}

commonEvents對(duì)象的內(nèi)部結(jié)構(gòu)

表27****commonEvents對(duì)象的內(nèi)部結(jié)構(gòu)說明

commonEvents示例：

"commonEvents": [
  {
    "name": ".EntryAbility",
    "permission": "ohos.permission.GET_BUNDLE_INFO",
    "data": [
      "com.example.demo",
      "100"
    ],
    "events": [
      "install",
      "update"
    ]
  }
]

testRunner對(duì)象的內(nèi)部結(jié)構(gòu)

表28****testRunner對(duì)象的內(nèi)部結(jié)構(gòu)說明

"testRunner": {
  "name": "myTestRunnerName",
  "srcPath": "etc/test/TestRunner.ts"
}

`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

definePermission僅支持系統(tǒng)應(yīng)用配置，三方應(yīng)用配置不生效。

definePermissions對(duì)象內(nèi)部結(jié)構(gòu)

表29****definePermissions對(duì)象內(nèi)部結(jié)構(gòu)說明

審核編輯 黃宇