ServiceAbility組件概述

ServiceAbility，即"基于Service模板的Ability"，主要用于后臺運行任務（如執行音樂播放、文件下載等），不提供用戶交互界面。ServiceAbility可由其他應用或PageAbility啟動，即使用戶切換到其他應用，ServiceAbility仍將在后臺繼續運行。

ServiceAbility組件配置

與PageAbility類似，ServiceAbility的相關配置在config.json配置文件的"module"對象的"abilities"對象中，與PageAbility的區別在于"type"屬性及"backgroundModes"屬性。

表1 ServiceAbility部分配置項說明

module對象內部結構

module對象包含HAP的配置信息。

表1****module對象內部結構說明

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對象內部結構

表2****distro對象內部結構說明

distro示例：

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

metadata對象內部結構

表3****metadata對象內部結構說明

parameters對象內部結構

表4****parameters對象內部結構說明

results對象內部結構

表5****results對象內部結構說明

customizeData對象的內部結構

表6****customizeData對象的內部結構說明

metadata對象示例：

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

表7****deviceType標簽配置說明

abilities對象的內部結構

表8****abilities對象的內部結構說明

不允許應用隱藏入口圖標

系統對無圖標應用實施嚴格管控，防止一些惡意應用故意配置無入口圖標，導致用戶找不到軟件所在的位置，無法操作卸載應用，在一定程度上保證用戶終端設備的安全。

入口圖標的設置: 需要在配置文件（config.json）中abilities配置下設置icon，label以及skills，而且skills的配置下必須同時包含“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": []
      }]
    }],

    ...

  }
}

如果應用確需隱藏入口圖標，需要配置AllowAppDesktopIconHide應用特權，具體配置方式參考[應用特權配置指南]。詳細的入口圖標及入口標簽的顯示規則如下。

• HAP中包含Page類型的PageAbility
  • 配置文件（config.json）中abilities配置中設置了入口圖標
    • 該應用沒有隱藏圖標的特權
      • 系統將使用該PageAbility配置的icon作為入口圖標，并顯示在桌面上。用戶點擊該圖標，頁面跳轉到該PageAbility首頁。
      • 系統將使用該PageAbility配置的label作為入口標簽，并顯示在桌面上（如果沒有配置label，返回包名）。
    • 該應用具有隱藏圖標的特權
      • 桌面查詢時不返回應用信息，不會在桌面上顯示對應的入口圖標和標簽。
  • 配置文件（config.json）中abilities配置中未設置入口圖標
    • 該應用沒有隱藏圖標的特權
      • 系統將使用系統默認圖標作為入口圖標，并顯示在桌面上。用戶點擊該圖標，頁面跳轉到應用管理中對應的應用詳情頁面（參考下圖）。
      • 系統將使用應用的包名作為入口標簽，并顯示在桌面上。
    • 該應用具有隱藏圖標的特權
      • 桌面查詢時不返回應用信息，不會在桌面上顯示對應的入口圖標和標簽。
• HAP中不包含Page類型的PageAbility
  • 該應用沒有隱藏圖標的特權
    • 系統將使用系統默認圖標作為入口圖標，并顯示在桌面上。用戶點擊該圖標，頁面跳轉到應用管理中對應的應用詳情頁面（參考下圖）。
    • 系統將使用應用的包名作為入口標簽，并顯示在桌面上。
  • 該應用具有隱藏圖標的特權
    • 桌面查詢時不返回應用信息，不會在桌面上顯示對應的入口圖標和標簽。

圖1 應用的詳情頁示意圖

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

uriPermission對象的內部結構

表9****uriPermission對象的內部結構說明

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對象的內部結構

表10****skills對象的內部結構說明

uris對象的內部結構

表11****uris對象的內部結構說明

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權限申請

表12****reqPermissions權限申請字段說明

usedScene對象內部結構

表13****usedScene對象內部結構說明

js對象的內部結構

表14****js對象的內部結構說明

window對象的內部結構

表15****window對象的內部結構說明

mode對象的內部結構

表16****mode對象的內部結構說明

js示例：

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

shortcuts對象的內部結構

表17****shortcuts對象的內部結構說明

intents對象的內部結構

表18****intents對象的內部結構說明

shortcuts示例：

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

forms對象的內部結構

表19****forms對象的內部結構說明

customizeData對象內部結構

表20****customizeData對象內部結構說明

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對象的內部結構

表21****distroFilter對象的內部結構說明

apiVersion對象的內部結構

表22****apiVersion對象的內部結構說明

screenShape對象的內部結構

表23****screenShape對象的內部結構說明

screenWindow對象的內部結構

表24****screenWindow對象的內部結構說明

screenDensity對象的內部結構

表25****screenDensity對象的內部結構說明

countryCode對象的內部結構

表26****countryCode對象的內部結構說明

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對象的內部結構

表27****commonEvents對象的內部結構說明

commonEvents示例：

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

testRunner對象的內部結構

表28****testRunner對象的內部結構說明

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

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

definePermission僅支持系統應用配置，三方應用配置不生效。

definePermissions對象內部結構

表29****definePermissions對象內部結構說明

審核編輯 黃宇