1# @ohos.resourceschedule.backgroundTaskManager (后台任务管理) 2 3本模块提供申请后台任务的接口。当应用退至后台时，开发者可以通过本模块接口为应用申请短时、长时任务，避免应用进程被终止或挂起。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```ts 13import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 14``` 15 16## backgroundTaskManager.requestSuspendDelay 17 18requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo 19 20申请短时任务。 21 22> **说明：** 23> 24> 短时任务的申请和使用过程中的约束与限制请参考[指南](../../task-management/transient-task.md#约束与限制)。 25 26**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 27 28**参数**： 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | -------------------- | ---- | ------------------------------ | 32| reason | string | 是 | 申请短时任务的原因。 | 33| callback | Callback<void> | 是 | 短时任务即将超时的回调函数，一般在超时前6秒，通过此回调通知应用。 | 34 35**返回值**： 36 37| 类型 | 说明 | 38| ------------------------------------- | --------- | 39| [DelaySuspendInfo](#delaysuspendinfo) | 返回短时任务信息。 | 40 41**错误码**： 42 43以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 44 45| 错误码ID | 错误信息 | 46| --------- | ------- | 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 48| 9800001 | Memory operation failed. | 49| 9800002 | Parcel operation failed. | 50| 9800003 | Internal transaction failed. | 51| 9800004 | System service operation failed. | 52| 9900001 | Caller information verification failed for a transient task. | 53| 9900002 | Transient task verification failed. | 54 55**示例**： 56 57```ts 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60let myReason = 'test requestSuspendDelay'; 61try { 62 let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { 63 // 回调函数。应用申请的短时任务即将超时，通过此函数回调应用，执行一些清理和标注工作，并取消短时任务。 64 // 此处回调与应用的业务功能不耦合，短时任务申请成功后，正常执行应用本身的业务。 65 console.info("Request suspension delay will time out."); 66 }) 67 let id = delayInfo.requestId; 68 let time = delayInfo.actualDelayTime; 69 console.info("The requestId is: " + id); 70 console.info("The actualDelayTime is: " + time); 71} catch (error) { 72 console.error(`requestSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 73} 74``` 75 76 77## backgroundTaskManager.getRemainingDelayTime 78 79getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 80 81获取本次短时任务的剩余时间，使用callback异步回调。 82 83**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 84 85**参数**： 86 87| 参数名 | 类型 | 必填 | 说明 | 88| --------- | --------------------------- | ---- | ---------------------------------------- | 89| requestId | number | 是 | 短时任务的请求ID。 | 90| callback | AsyncCallback<number> | 是 | 回调函数，返回本次短时任务的剩余时间，单位为毫秒。 | 91 92**错误码**： 93 94以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 95 96| 错误码ID | 错误信息 | 97| --------- | ------- | 98| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 99| 9800001 | Memory operation failed. | 100| 9800002 | Parcel operation failed. | 101| 9800003 | Internal transaction failed. | 102| 9800004 | System service operation failed. | 103| 9900001 | Caller information verification failed for a transient task. | 104| 9900002 | Transient task verification failed. | 105 106 107**示例**： 108 109```ts 110import { BusinessError } from '@kit.BasicServicesKit'; 111 112let id = 1; 113backgroundTaskManager.getRemainingDelayTime(id, (error: BusinessError, res: number) => { 114 if(error) { 115 console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); 116 } else { 117 console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 118 } 119}) 120``` 121 122 123## backgroundTaskManager.getRemainingDelayTime 124 125getRemainingDelayTime(requestId: number): Promise<number> 126 127获取本次短时任务的剩余时间，使用promise异步回调。 128 129**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 130 131**参数**： 132 133| 参数名 | 类型 | 必填 | 说明 | 134| --------- | ------ | ---- | ---------- | 135| requestId | number | 是 | 短时任务的请求ID。 | 136 137**返回值**： 138 139| 类型 | 说明 | 140| --------------------- | ---------------------------------------- | 141| Promise<number> | Promise对象，返回本次短时任务的剩余时间，单位为毫秒。 | 142 143**错误码**： 144 145以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 146 147| 错误码ID | 错误信息 | 148| --------- | ------- | 149| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 150| 9800001 | Memory operation failed. | 151| 9800002 | Parcel operation failed. | 152| 9800003 | Internal transaction failed. | 153| 9800004 | System service operation failed. | 154| 9900001 | Caller information verification failed for a transient task. | 155| 9900002 | Transient task verification failed. | 156 157**示例**： 158 159```ts 160import { BusinessError } from '@kit.BasicServicesKit'; 161 162let id = 1; 163backgroundTaskManager.getRemainingDelayTime(id).then((res: number) => { 164 console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 165}).catch((error: BusinessError) => { 166 console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); 167}) 168``` 169 170 171## backgroundTaskManager.cancelSuspendDelay 172 173cancelSuspendDelay(requestId: number): void 174 175取消短时任务。 176 177**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 178 179**参数**： 180 181| 参数名 | 类型 | 必填 | 说明 | 182| --------- | ------ | ---- | ---------- | 183| requestId | number | 是 | 短时任务的请求ID。 | 184 185**错误码**： 186 187以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 188 189| 错误码ID | 错误信息 | 190| --------- | ------- | 191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 192| 9800001 | Memory operation failed. | 193| 9800002 | Parcel operation failed. | 194| 9800003 | Internal transaction failed. | 195| 9800004 | System service operation failed. | 196| 9900001 | Caller information verification failed for a transient task. | 197| 9900002 | Transient task verification failed. | 198 199**示例**： 200 201 ```js 202 import { BusinessError } from '@kit.BasicServicesKit'; 203 204 let id = 1; 205 try { 206 backgroundTaskManager.cancelSuspendDelay(id); 207 } catch (error) { 208 console.error(`cancelSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 209 } 210 ``` 211 212## backgroundTaskManager.startBackgroundRunning 213 214startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 215 216申请长时任务，支持申请一种类型，使用callback异步回调。 217 218**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 219 220**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 221 222**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 223 224**参数**： 225 226| 参数名 | 类型 | 必填 | 说明 | 227| --------- | ---------------------------------- | ---- | ---------------------------------------- | 228| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 229| bgMode | [BackgroundMode](#backgroundmode) | 是 | 长时任务类型。 | 230| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | 是 | 通知参数，用于指定点击长时任务通知后跳转的界面。 | 231| callback | AsyncCallback<void> | 是 | 回调函数，申请长时任务成功时，err为undefined，否则为错误对象。 | 232 233**错误码**： 234 235以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 236 237| 错误码ID | 错误信息 | 238| ---- | --------------------- | 239| 201 | Permission denied. | 240| 202 | Not System App. | 241| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 242| 9800001 | Memory operation failed. | 243| 9800002 | Parcel operation failed. | 244| 9800003 | Internal transaction failed. | 245| 9800004 | System service operation failed. | 246| 9800005 | Continuous task verification failed. | 247| 9800006 | Notification verification failed for a continuous task. | 248| 9800007 | Continuous task storage failed. | 249 250**示例**： 251 252```js 253import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 254import { BusinessError } from '@kit.BasicServicesKit'; 255import { wantAgent, WantAgent } from '@kit.AbilityKit'; 256import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 257 258function callback(error: BusinessError, data: void) { 259 if (error) { 260 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 261 } else { 262 console.info("Operation startBackgroundRunning succeeded"); 263 } 264} 265 266export default class EntryAbility extends UIAbility { 267 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 268 let wantAgentInfo: wantAgent.WantAgentInfo = { 269 // 点击通知后，将要执行的动作列表 270 wants: [ 271 { 272 bundleName: "com.example.myapplication", 273 abilityName: "EntryAbility" 274 } 275 ], 276 // 点击通知后，动作类型 277 actionType: wantAgent.OperationType.START_ABILITY, 278 // 使用者自定义的一个私有值 279 requestCode: 0, 280 // 点击通知后，动作执行属性 281 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 282 }; 283 284 try { 285 // 通过wantAgent模块下getWantAgent方法获取WantAgent对象 286 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 287 try { 288 backgroundTaskManager.startBackgroundRunning(this.context, 289 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback) 290 } catch (error) { 291 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 292 } 293 }); 294 } catch (error) { 295 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 296 } 297 } 298}; 299``` 300 301## backgroundTaskManager.startBackgroundRunning 302 303startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 304 305申请长时任务，支持申请一种类型，使用promise异步回调。 306 307**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 308 309**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 310 311**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 312 313**参数**： 314 315| 参数名 | 类型 | 必填 | 说明 | 316| --------- | ---------------------------------- | ---- | ---------------------------------------- | 317| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 318| bgMode | [BackgroundMode](#backgroundmode) | 是 | 长时任务类型。 | 319| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | 是 | 通知参数，用于指定点击长时任务通知后跳转的界面。 | 320 321**返回值**： 322 323| 类型 | 说明 | 324| -------------- | ---------------- | 325| Promise\<void> | 无返回结果的Promise对象。 | 326 327**错误码**： 328 329以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 330 331| 错误码ID | 错误信息 | 332| ---- | --------------------- | 333| 201 | Permission denied. | 334| 202 | Not System App. | 335| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 336| 9800001 | Memory operation failed. | 337| 9800002 | Parcel operation failed. | 338| 9800003 | Internal transaction failed. | 339| 9800004 | System service operation failed. | 340| 9800005 | Continuous task verification failed. | 341| 9800006 | Notification verification failed for a continuous task. | 342| 9800007 | Continuous task storage failed. | 343 344**示例**： 345 346```js 347import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 348import { BusinessError } from '@kit.BasicServicesKit'; 349import { wantAgent, WantAgent } from '@kit.AbilityKit'; 350import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 351 352export default class EntryAbility extends UIAbility { 353 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 354 let wantAgentInfo: wantAgent.WantAgentInfo = { 355 // 点击通知后，将要执行的动作列表 356 wants: [ 357 { 358 bundleName: "com.example.myapplication", 359 abilityName: "EntryAbility" 360 } 361 ], 362 // 点击通知后，动作类型 363 actionType: wantAgent.OperationType.START_ABILITY, 364 // 使用者自定义的一个私有值 365 requestCode: 0, 366 // 点击通知后，动作执行属性 367 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 368 }; 369 370 try { 371 // 通过wantAgent模块下getWantAgent方法获取WantAgent对象 372 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 373 try { 374 backgroundTaskManager.startBackgroundRunning(this.context, 375 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => { 376 console.info("Operation startBackgroundRunning succeeded"); 377 }).catch((error: BusinessError) => { 378 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 379 }); 380 } catch (error) { 381 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 382 } 383 }); 384 } catch (error) { 385 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 386 } 387 } 388}; 389``` 390 391## backgroundTaskManager.stopBackgroundRunning 392 393stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 394 395取消长时任务，使用callback异步回调。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 400 401**参数**： 402 403| 参数名 | 类型 | 必填 | 说明 | 404| -------- | ------------------------- | ---- | ---------------------------------------- | 405| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 406| callback | AsyncCallback<void> | 是 | 回调函数，取消长时任务成功时，err为undefined，否则为错误对象。| 407 408**错误码**： 409 410以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 411 412| 错误码ID | 错误信息 | 413| ---- | --------------------- | 414| 201 | Permission denied. | 415| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 416| 9800001 | Memory operation failed. | 417| 9800002 | Parcel operation failed. | 418| 9800003 | Internal transaction failed. | 419| 9800004 | System service operation failed. | 420| 9800005 | Continuous task verification failed. | 421| 9800006 | Notification verification failed for a continuous task. | 422| 9800007 | Continuous task storage failed. | 423 424**示例**： 425 426```js 427import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 428import { BusinessError } from '@kit.BasicServicesKit'; 429import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 430 431function callback(error: BusinessError, data: void) { 432 if (error) { 433 console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 434 } else { 435 console.info("Operation stopBackgroundRunning succeeded"); 436 } 437} 438 439export default class EntryAbility extends UIAbility { 440 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 441 try { 442 backgroundTaskManager.stopBackgroundRunning(this.context, callback); 443 } catch (error) { 444 console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 445 } 446 } 447}; 448``` 449 450## backgroundTaskManager.stopBackgroundRunning 451 452stopBackgroundRunning(context: Context): Promise<void> 453 454取消长时任务，使用promise异步回调。 455 456**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 457 458**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 459 460**参数**： 461 462| 参数名 | 类型 | 必填 | 说明 | 463| ------- | ------- | ---- | ---------------------------------------- | 464| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 465 466**返回值**： 467 468| 类型 | 说明 | 469| -------------- | ---------------- | 470| Promise\<void> | 无返回结果的Promise对象。 | 471 472**错误码**： 473 474以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 475 476| 错误码ID | 错误信息 | 477| ---- | --------------------- | 478| 201 | Permission denied. | 479| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 480| 9800001 | Memory operation failed. | 481| 9800002 | Parcel operation failed. | 482| 9800003 | Internal transaction failed. | 483| 9800004 | System service operation failed. | 484| 9800005 | Continuous task verification failed. | 485| 9800006 | Notification verification failed for a continuous task. | 486| 9800007 | Continuous task storage failed. | 487 488**示例**： 489 490```js 491import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 492import { BusinessError } from '@kit.BasicServicesKit'; 493import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 494 495export default class EntryAbility extends UIAbility { 496 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 497 try { 498 backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { 499 console.info("Operation stopBackgroundRunning succeeded"); 500 }).catch((error: BusinessError) => { 501 console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 502 }); 503 } catch (error) { 504 console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 505 } 506 } 507}; 508``` 509 510## backgroundTaskManager.startBackgroundRunning<sup>12+</sup> 511 512startBackgroundRunning(context: Context, bgModes: string[], wantAgent: WantAgent): Promise<ContinuousTaskNotification> 513 514申请长时任务，支持申请多种类型，使用promise异步回调。 515 516**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 517 518**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 519 520**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 521 522**参数**： 523 524| 参数名 | 类型 | 必填 | 说明 | 525| --------- | ---------------------------------- | ---- | ---------------------------------------- | 526| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 应用运行的上下文。 | 527| bgModes | string[] | 是 | 长时任务类型，取值范围请参考长时任务类型中的[配置项](../../task-management/continuous-task.md#使用场景)。<br> **说明：** 支持传入一个或多个类型。| 528| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | 是 | 通知参数，用于指定点击长时任务通知后跳转的界面。 | 529 530**返回值**： 531 532| 类型 | 说明 | 533| -------------- | ---------------- | 534| Promise\<ContinuousTaskNotification> | 返回[ContinuousTaskNotification](#continuoustasknotification12)类型的Promise对象。 | 535 536**错误码**： 537 538以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 539 540| 错误码ID | 错误信息 | 541| ---- | --------------------- | 542| 201 | Permission denied. | 543| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 544| 9800001 | Memory operation failed. | 545| 9800002 | Parcel operation failed. | 546| 9800003 | Internal transaction failed. | 547| 9800004 | System service operation failed. | 548| 9800005 | Continuous task verification failed. | 549| 9800006 | Notification verification failed for a continuous task. | 550| 9800007 | Continuous task storage failed. | 551 552**示例**： 553 554```js 555import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 556import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 557import { window } from '@kit.ArkUI'; 558import { BusinessError } from '@kit.BasicServicesKit'; 559import { wantAgent, WantAgent } from '@kit.AbilityKit'; 560import { notificationManager } from '@kit.NotificationKit'; 561 562export default class EntryAbility extends UIAbility { 563 id: number = 0; // 保存通知id 564 565 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 566 let wantAgentInfo: wantAgent.WantAgentInfo = { 567 // 点击通知后，将要执行的动作列表 568 wants: [ 569 { 570 bundleName: "com.example.myapplication", 571 abilityName: "EntryAbility" 572 } 573 ], 574 // 点击通知后，动作类型 575 actionType: wantAgent.OperationType.START_ABILITY, 576 // 使用者自定义的一个私有值 577 requestCode: 0, 578 // 点击通知后，动作执行属性 579 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 580 }; 581 582 try { 583 // 通过wantAgent模块下getWantAgent方法获取WantAgent对象 584 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 585 try { 586 let list: Array<string> = ["dataTransfer"]; 587 backgroundTaskManager.startBackgroundRunning(this.context, list, wantAgentObj).then((res: backgroundTaskManager.ContinuousTaskNotification) => { 588 console.info("Operation startBackgroundRunning succeeded"); 589 // 对于上传下载类的长时任务，应用可以使用res中返回的notificationId来更新通知，比如发送带进度条的模板通知。 590 this.id = res.notificationId; 591 }).catch((error: BusinessError) => { 592 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 593 }); 594 } catch (error) { 595 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 596 } 597 }); 598 } catch (error) { 599 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 600 } 601 } 602 603 // 应用更新进度 604 updateProcess(process: Number) { 605 // 应用定义下载类通知模版 606 let downLoadTemplate: notificationManager.NotificationTemplate = { 607 name: 'downloadTemplate', // 当前只支持downloadTemplate，保持不变 608 data: { 609 title: '文件下载：music.mp4', // 必填。 610 fileName: 'senTemplate', // 必填。 611 progressValue: process, // 应用更新进度值，自定义。 612 } 613 }; 614 let request: notificationManager.NotificationRequest = { 615 content: { 616 // 系统实况类型，保持不变 617 notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_SYSTEM_LIVE_VIEW, 618 systemLiveView: { 619 typeCode: 8, // 上传下载类型需要填写 8，当前仅支持此类型。保持不变 620 title: "test", // 应用自定义 621 text: "test", // 应用自定义 622 } 623 }, 624 id: this.id, // 必须是申请长时任务返回的id，否则应用更新通知失败。 625 notificationSlotType: notificationManager.SlotType.LIVE_VIEW, // 实况窗类型，保持不变 626 template: downLoadTemplate // 应用需要设置的模版名称 627 }; 628 629 try { 630 notificationManager.publish(request).then(() => { 631 console.info("publish success, id= " + this.id); 632 }).catch((err: BusinessError) => { 633 console.error(`publish fail: ${JSON.stringify(err)}`); 634 }); 635 } catch (err) { 636 console.error(`publish fail: ${JSON.stringify(err)}`); 637 } 638 } 639}; 640``` 641## backgroundTaskManager.updateBackgroundRunning<sup>12+</sup> 642 643updateBackgroundRunning(context: Context, bgModes: string[]): Promise<ContinuousTaskNotification> 644 645更新长时任务类型，使用promise异步回调。 646 647**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 648 649**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 650 651**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 652 653**参数**： 654 655| 参数名 | 类型 | 必填 | 说明 | 656| --------- | ---------------------------------- | ---- | ---------------------------------------- | 657| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 应用运行的上下文。 | 658| bgModes | string[] | 是 | 更新后的长时任务类型，取值范围请参考长时任务类型中的[配置项](../../task-management/continuous-task.md#使用场景)。<br> **说明：** 支持传入一个或多个类型。| 659 660**返回值**： 661 662| 类型 | 说明 | 663| -------------- | ---------------- | 664| Promise\<ContinuousTaskNotification> | 返回[ContinuousTaskNotification](#continuoustasknotification12)类型的Promise对象。 | 665 666**错误码**： 667 668以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 669 670| 错误码ID | 错误信息 | 671| ---- | --------------------- | 672| 201 | Permission denied. | 673| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 674| 9800001 | Memory operation failed. | 675| 9800002 | Parcel operation failed. | 676| 9800003 | Internal transaction failed. | 677| 9800004 | System service operation failed. | 678| 9800005 | Continuous task verification failed. | 679| 9800006 | Notification verification failed for a continuous task. | 680| 9800007 | Continuous task storage failed. | 681 682**示例**： 683 684```js 685import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 686import { BusinessError } from '@kit.BasicServicesKit'; 687import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 688 689export default class EntryAbility extends UIAbility { 690 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 691 try { 692 try { 693 // 必须先执行startBackgroundRunning，才能调用updateBackgroundRunning。这里假设已经申请过。 694 let list: Array<string> = ["audioPlayback"]; 695 backgroundTaskManager.updateBackgroundRunning(this.context, list).then(() => { 696 console.info("Operation updateBackgroundRunning succeeded"); 697 }).catch((error: BusinessError) => { 698 console.error(`Operation updateBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 699 }); 700 } catch (error) { 701 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 702 } 703 } catch (error) { 704 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 705 } 706 } 707}; 708``` 709 710## backgroundTaskManager.on('continuousTaskCancel')<sup>15+</sup> 711 712on(type: 'continuousTaskCancel', callback: Callback<ContinuousTaskCancelInfo>): void 713 714注册长时任务取消的监听，使用callback异步回调。 715 716**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 717 718**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 719 720**参数**： 721 722| 参数名 | 类型 | 必填 | 说明 | 723| --------- | ---------------------------------- | ---- | ---------------------------------------- | 724| type | string | 是 | 取消长时任务，固定取值为'continuousTaskCancel'。 | 725| callback | Callback\<[ContinuousTaskCancelReason](#continuoustaskcancelreason15)> | 是 | 回调函数，返回长时任务取消原因。 | 726 727**错误码**： 728 729以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 730 731| 错误码ID | 错误信息 | 732| ---- | --------------------- | 733| 201 | Permission denied. | 734| 401 | Parameter error. Possible cause: 1. Callback parameter error; 2. Register a exist callback type; 3. Parameter verification failed. | 735 736**示例**： 737 738```js 739import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 740import { BusinessError } from '@kit.BasicServicesKit'; 741import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 742 743function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) { 744 console.info('continuousTaskCancel callback id ' + info.id); 745 console.info('continuousTaskCancel callback reason ' + info.reason); 746} 747 748export default class EntryAbility extends UIAbility { 749 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 750 try { 751 backgroundTaskManager.on("continuousTaskCancel", callback); 752 } catch (error) { 753 console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 754 } 755 } 756}; 757``` 758## backgroundTaskManager.off('continuousTaskCancel')<sup>15+</sup> 759 760off(type: 'continuousTaskCancel', callback?: Callback<ContinuousTaskCancelInfo>): void 761 762解除长时任务取消的监听，使用callback异步回调。 763 764**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 765 766**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 767 768**参数**： 769 770| 参数名 | 类型 | 必填 | 说明 | 771| --------- | ---------------------------------- | ---- | ---------------------------------------- | 772| type | string | 是 | 取消长时任务，固定取值为'continuousTaskCancel'。 | 773| callback | Callback\<[ContinuousTaskCancelReason](#continuoustaskcancelreason15)> | 否 | 需要取消监听的回调函数，未传入则取消所有注册回调。 | 774 775**错误码**： 776 777以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 778 779| 错误码ID | 错误信息 | 780| ---- | --------------------- | 781| 201 | Permission denied. | 782| 401 | Parameter error. Possible cause: 1. Callback parameter error; 2. Unregister type has not register; 3. Parameter verification failed. | 783 784**示例**： 785 786```js 787import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 788import { BusinessError } from '@kit.BasicServicesKit'; 789import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 790 791function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) { 792 console.info('continuousTaskCancel callback id ' + info.id); 793 console.info('continuousTaskCancel callback reason ' + info.reason); 794} 795 796export default class EntryAbility extends UIAbility { 797 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 798 try { 799 backgroundTaskManager.off("continuousTaskCancel", callback); 800 } catch (error) { 801 console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 802 } 803 } 804}; 805``` 806 807## DelaySuspendInfo 808 809短时任务信息。 810 811**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 812 813| 名称 | 类型 | 必填 | 说明 | 814| --------------- | ------ | ---- | ---------------------------------------- | 815| requestId | number | 是 | 短时任务的请求ID。 | 816| actualDelayTime | number | 是 | 应用实际申请的短时任务时间，单位为毫秒。<br/> **说明** ：申请时间最长为3分钟，[低电量](../apis-basic-services-kit/js-apis-battery-info.md)时最长为1分钟。 | 817 818## BackgroundMode 819 820长时任务类型。 821 822**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 823 824| 名称 | 值 | 说明 | 825| ----------------------- | ---- | --------------------- | 826| DATA_TRANSFER | 1 | 数据传输。 | 827| AUDIO_PLAYBACK | 2 | 音视频播放。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 828| AUDIO_RECORDING | 3 | 录制。 | 829| LOCATION | 4 | 定位导航。 | 830| BLUETOOTH_INTERACTION | 5 | 蓝牙相关业务。 | 831| MULTI_DEVICE_CONNECTION | 6 | 多设备互联。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 832| VOIP<sup>13+</sup> | 8 | 音视频通话。 | 833| TASK_KEEPING | 9 | 计算任务（仅对2in1设备开放）。 | 834 835## ContinuousTaskNotification<sup>12+</sup> 836 837长时任务通知信息。 838 839**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 840 841| 名称 | 类型 | 只读 | 可选 | 说明 | 842| --------------- | ------ | ---- | ---- | ---------------------------------------- | 843| slotType | [notificationManager.SlotType](../apis-notification-kit/js-apis-notificationManager.md#slottype) | 否 | 否 | 长时任务通知的渠道类型。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 844| contentType | [notificationManager.ContentType](../apis-notification-kit/js-apis-notificationManager.md#contenttype) | 否 | 否 | 长时任务通知的内容类型。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 845| notificationId | number | 否 | 否 | 长时任务通知 Id。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 846| continuousTaskId<sup>15+</sup> | number | 否 | 是 | 长时任务 Id。| 847 848## ContinuousTaskCancelInfo<sup>15+</sup> 849 850长时任务取消信息。 851 852**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 853 854| 名称 | 类型 | 必填 | 说明 | 855| --------------- | ------ | ---- | ---------------------------------------- | 856| reason | [ContinuousTaskCancelReason](#continuoustaskcancelreason15) | 是 | 长时任务取消原因。| 857| id | number | 是 | 被取消的长时任务 Id。| 858 859## ContinuousTaskCancelReason<sup>15+</sup> 860 861长时任务取消原因。 862 863**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 864 865| 名称 | 值 | 说明 | 866| ----------------------- | ---- | --------------------- | 867| USER_CANCEL | 1 | 用户取消。 | 868| SYSTEM_CANCEL | 2 | 系统取消。 | 869| USER_CANCEL_REMOVE_NOTIFICATION | 3 | 用户移除通知。预留接口，暂未启用。 | 870| SYSTEM_CANCEL_DATA_TRANSFER_LOW_SPEED | 4 | 申请DATA_TRANSFER类型长时任务，但是数据传输速率低。预留接口，暂未启用。 | 871| SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_USE_AVSESSION | 5 | 申请AUDIO_PLAYBACK类型长时任务，但是未接入[AVSession](../../media/avsession/avsession-overview.md)。预留接口，暂未启用。 | 872| SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_RUNNING | 6 | 申请AUDIO_PLAYBACK类型长时任务，但是未播放音视频。预留接口，暂未启用。 | 873| SYSTEM_CANCEL_AUDIO_RECORDING_NOT_RUNNING | 7 | 申请AUDIO_RECORDING类型长时任务，但是未录制。预留接口，暂未启用。 | 874| SYSTEM_CANCEL_NOT_USE_LOCATION | 8 | 申请LOCATION类型长时任务，但是未使用定位导航。预留接口，暂未启用。 | 875| SYSTEM_CANCEL_NOT_USE_BLUETOOTH | 9 | 申请BLUETOOTH_INTERACTION类型长时任务，但是未使用蓝牙相关业务。预留接口，暂未启用。 | 876| SYSTEM_CANCEL_NOT_USE_MULTI_DEVICE | 10 | 申请MULTI_DEVICE_CONNECTION类型长时任务，但是未使用多设备互联。预留接口，暂未启用。 | 877| SYSTEM_CANCEL_USE_ILLEGALLY | 11 | 使用非法类型的长时任务，如申请AUDIO_PLAYBACK类型长时任务，但是使用音视频播放及定位导航业务。预留接口，暂未启用。 | 878 879## BackgroundSubMode<sup>16+</sup> 880 881长时任务子类型。 882 883**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 884 885| 名称 | 值 | 说明 | 886| ----------------------- | ---- | --------------------- | 887| CAR_KEY | 1 | 车钥匙。<br/>**说明：** 只有申请BLUETOOTH_INTERACTION类型的长时任务，车钥匙子类型才能生效。 | 888 889## BackgroundModeType<sup>16+</sup> 890 891长时任务类型类别。 892 893**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 894 895| 名称 | 值 | 说明 | 896| ----------------------- | ---- | --------------------- | 897| SUB_MODE | 'subMode' | 子类型。 |