1# @ohos.backgroundTaskManager (后台任务管理) 2 3本模块提供后台任务管理能力。 4 5当应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。 6 7应用有不可中断且短时间能完成的任务时（如，用户在文件管理器上点击垃圾文件清理，若清理未完成时退到后台，文件管理器需要申请短时任务完成清理），可以使用短时任务机制。 8 9应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。 10 11对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如需要在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。 12 13> **说明：** 14> - 从API Version 9 开始，该接口不再维护，推荐使用新接口[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](js-apis-resourceschedule-backgroundTaskManager.md) 15> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16 17 18## 导入模块 19 20```js 21import backgroundTaskManager from '@ohos.backgroundTaskManager'; 22``` 23 24 25## backgroundTaskManager.requestSuspendDelay 26 27requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo 28 29后台应用申请延迟挂起。 30 31延迟挂起时间一般情况下默认值为3分钟，低电量（依据系统低电量广播）时默认值为1分钟。 32 33**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 34 35**参数**： 36 37| 参数名 | 类型 | 必填 | 说明 | 38| -------- | -------------------- | ---- | ------------------------------ | 39| reason | string | 是 | 延迟挂起申请的原因。 | 40| callback | Callback<void> | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 | 41 42**返回值**： 43 44| 类型 | 说明 | 45| ------------------------------------- | --------- | 46| [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | 47 48**示例**： 49 50 ```js 51 import backgroundTaskManager from '@ohos.backgroundTaskManager'; 52 53 let myReason = 'test requestSuspendDelay'; 54 let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { 55 console.info("Request suspension delay will time out."); 56 }) 57 58 let id = delayInfo.requestId; 59 let time = delayInfo.actualDelayTime; 60 console.info("The requestId is: " + id); 61 console.info("The actualDelayTime is: " + time); 62 ``` 63 64 65## backgroundTaskManager.getRemainingDelayTime 66 67getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 68 69获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 70 71**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 72 73**参数**： 74 75| 参数名 | 类型 | 必填 | 说明 | 76| --------- | --------------------------- | ---- | ---------------------------------------- | 77| requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | 78| callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | 79 80**示例**： 81 82 ```js 83 import backgroundTaskManager from '@ohos.backgroundTaskManager'; 84 85 let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); 86 backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId, (err, res) => { 87 if(err) { 88 console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code); 89 } else { 90 console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 91 } 92 }) 93 ``` 94 95 96## backgroundTaskManager.getRemainingDelayTime 97 98getRemainingDelayTime(requestId: number): Promise<number> 99 100获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 101 102**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 103 104**参数**： 105 106| 参数名 | 类型 | 必填 | 说明 | 107| --------- | ------ | ---- | ---------- | 108| requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | 109 110**返回值**： 111 112| 类型 | 说明 | 113| --------------------- | ---------------------------------------- | 114| Promise<number> | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | 115 116**示例**： 117 118 ```js 119 let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); 120 backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId).then( res => { 121 console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 122 }).catch( err => { 123 console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); 124 }) 125 ``` 126 127 128## backgroundTaskManager.cancelSuspendDelay 129 130cancelSuspendDelay(requestId: number): void 131 132取消延迟挂起。 133 134**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 135 136**参数**： 137 138| 参数名 | 类型 | 必填 | 说明 | 139| --------- | ------ | ---- | ---------- | 140| requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | 141 142**示例**： 143 144 ```js 145 let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); 146 backgroundTaskManager.cancelSuspendDelay(delayInfo.requestId); 147 ``` 148 149 150## backgroundTaskManager.startBackgroundRunning<sup>8+</sup> 151 152startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 153 154向系统申请长时任务，使用callback形式返回结果。 155 156**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 157 158**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 159 160**参数**： 161 162| 参数名 | 类型 | 必填 | 说明 | 163| --------- | ---------------------------------- | ---- | ---------------------------------------- | 164| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-context.md)。 | 165| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | 166| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击后跳转的界面。 | 167| callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | 168 169**示例**： 170 171FA模型示例： 172 173```js 174import backgroundTaskManager from '@ohos.backgroundTaskManager'; 175import featureAbility from '@ohos.ability.featureAbility'; 176import wantAgent from '@ohos.wantAgent'; 177 178function callback(err, data) { 179 if (err) { 180 console.error("Operation startBackgroundRunning failed Cause: " + err); 181 } else { 182 console.info("Operation startBackgroundRunning succeeded"); 183 } 184} 185 186let wantAgentInfo = { 187 wants: [ 188 { 189 bundleName: "com.example.myapplication", 190 abilityName: "com.example.myapplication.MainAbility" 191 } 192 ], 193 operationType: wantAgent.OperationType.START_ABILITY, 194 requestCode: 0, 195 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 196}; 197 198wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 199 backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), 200 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback) 201}); 202 203``` 204 205Stage模型示例： 206 207```ts 208import UIAbility from '@ohos.app.ability.UIAbility'; 209import backgroundTaskManager from '@ohos.backgroundTaskManager'; 210import wantAgent from '@ohos.app.ability.wantAgent'; 211 212function callback(err, data) { 213 if (err) { 214 console.error("Operation startBackgroundRunning failed Cause: " + err); 215 } else { 216 console.info("Operation startBackgroundRunning succeeded"); 217 } 218} 219 220export default class EntryAbility extends UIAbility { 221 onCreate(want, launchParam) { 222 let wantAgentInfo = { 223 wants: [ 224 { 225 bundleName: "com.example.myapplication", 226 abilityName: "EntryAbility" 227 } 228 ], 229 operationType: wantAgent.OperationType.START_ABILITY, 230 requestCode: 0, 231 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 232 }; 233 234 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 235 backgroundTaskManager.startBackgroundRunning(this.context, 236 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback) 237 }); 238 } 239}; 240``` 241 242## backgroundTaskManager.startBackgroundRunning<sup>8+</sup> 243 244startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 245 246向系统申请长时任务，使用promise形式返回结果。 247 248**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 249 250**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 251 252**参数**： 253 254| 参数名 | 类型 | 必填 | 说明 | 255| --------- | ---------------------------------- | ---- | ---------------------------------------- | 256| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-context.md)。 | 257| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | 258| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。 | 259 260**返回值**： 261 262| 类型 | 说明 | 263| -------------- | ---------------- | 264| Promise\<void> | 使用Promise形式返回结果。 | 265 266**示例**： 267 268FA模型示例： 269 270```js 271import backgroundTaskManager from '@ohos.backgroundTaskManager'; 272import featureAbility from '@ohos.ability.featureAbility'; 273import wantAgent from '@ohos.wantAgent'; 274 275let wantAgentInfo = { 276 wants: [ 277 { 278 bundleName: "com.example.myapplication", 279 abilityName: "com.example.myapplication.MainAbility" 280 } 281 ], 282 operationType: wantAgent.OperationType.START_ABILITY, 283 requestCode: 0, 284 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 285}; 286 287wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 288 backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), 289 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => { 290 console.info("Operation startBackgroundRunning succeeded"); 291 }).catch((err) => { 292 console.error("Operation startBackgroundRunning failed Cause: " + err); 293 }); 294}); 295``` 296 297Stage模型示例： 298 299```ts 300import UIAbility from '@ohos.app.ability.UIAbility'; 301import backgroundTaskManager from '@ohos.backgroundTaskManager'; 302import wantAgent from '@ohos.app.ability.wantAgent'; 303 304export default class EntryAbility extends UIAbility { 305 onCreate(want, launchParam) { 306 let wantAgentInfo = { 307 wants: [ 308 { 309 bundleName: "com.example.myapplication", 310 abilityName: "EntryAbility" 311 } 312 ], 313 operationType: wantAgent.OperationType.START_ABILITY, 314 requestCode: 0, 315 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 316 }; 317 318 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 319 backgroundTaskManager.startBackgroundRunning(this.context, 320 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => { 321 console.info("Operation startBackgroundRunning succeeded"); 322 }).catch((err) => { 323 console.error("Operation startBackgroundRunning failed Cause: " + err); 324 }); 325 }); 326 } 327}; 328``` 329 330## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup> 331 332stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 333 334向系统申请取消长时任务，使用callback形式返回结果。 335 336**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 337 338**参数**： 339 340| 参数名 | 类型 | 必填 | 说明 | 341| -------- | ------------------------- | ---- | ---------------------------------------- | 342| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-context.md)。 | 343| callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | 344 345**示例**： 346 347FA模型示例： 348 349```js 350import backgroundTaskManager from '@ohos.backgroundTaskManager'; 351import featureAbility from '@ohos.ability.featureAbility'; 352 353function callback(err, data) { 354 if (err) { 355 console.error("Operation stopBackgroundRunning failed Cause: " + err); 356 } else { 357 console.info("Operation stopBackgroundRunning succeeded"); 358 } 359} 360 361backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback); 362 363``` 364 365Stage模型示例： 366 367```ts 368import UIAbility from '@ohos.app.ability.UIAbility'; 369import backgroundTaskManager from '@ohos.backgroundTaskManager'; 370 371function callback(err, data) { 372 if (err) { 373 console.error("Operation stopBackgroundRunning failed Cause: " + err); 374 } else { 375 console.info("Operation stopBackgroundRunning succeeded"); 376 } 377} 378 379export default class EntryAbility extends UIAbility { 380 onCreate(want, launchParam) { 381 backgroundTaskManager.stopBackgroundRunning(this.context, callback); 382 } 383}; 384``` 385 386## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup> 387 388stopBackgroundRunning(context: Context): Promise<void> 389 390向系统申请取消长时任务，使用promise形式返回结果。 391 392**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 393 394**参数**： 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ------- | ------- | ---- | ---------------------------------------- | 398| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-context.md)。 | 399 400**返回值**： 401 402| 类型 | 说明 | 403| -------------- | ---------------- | 404| Promise\<void> | 使用Promise形式返回结果。 | 405 406**示例**： 407 408FA模型示例： 409 410```js 411import backgroundTaskManager from '@ohos.backgroundTaskManager'; 412import featureAbility from '@ohos.ability.featureAbility'; 413 414backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { 415 console.info("Operation stopBackgroundRunning succeeded"); 416}).catch((err) => { 417 console.error("Operation stopBackgroundRunning failed Cause: " + err); 418}); 419 420``` 421 422Stage模型示例： 423 424```ts 425import UIAbility from '@ohos.app.ability.UIAbility'; 426import backgroundTaskManager from '@ohos.backgroundTaskManager'; 427 428export default class EntryAbility extends UIAbility { 429 onCreate(want, launchParam) { 430 backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { 431 console.info("Operation stopBackgroundRunning succeeded"); 432 }).catch((err) => { 433 console.error("Operation stopBackgroundRunning failed Cause: " + err); 434 }); 435 } 436}; 437``` 438 439## DelaySuspendInfo 440 441延迟挂起信息。 442 443**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 444 445| 名称 | 类型 | 必填 | 说明 | 446| --------------- | ------ | ---- | ---------------------------------------- | 447| requestId | number | 是 | 延迟挂起的请求ID。 | 448| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | 449 450 451## BackgroundMode<sup>8+</sup> 452 453**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 454 455| 名称 | 值 | 说明 | 456| ----------------------- | ---- | --------------------- | 457| DATA_TRANSFER | 1 | 数据传输。 | 458| AUDIO_PLAYBACK | 2 | 音频播放。 | 459| AUDIO_RECORDING | 3 | 录音。 | 460| LOCATION | 4 | 定位导航。 | 461| BLUETOOTH_INTERACTION | 5 | 蓝牙相关。 | 462| MULTI_DEVICE_CONNECTION | 6 | 多设备互联。 | 463| WIFI_INTERACTION | 7 | WLAN相关<br />此接口为系统接口。 | 464| VOIP | 8 | 音视频通话<br />此接口为系统接口。 | 465| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效）。 | 466