1# @ohos.resourceschedule.backgroundTaskManager (后台任务管理) 2 3<!--Kit: Background Tasks Kit--> 4<!--Subsystem: ResourceSchedule--> 5<!--Owner: @cheng-shichang--> 6<!--Designer: @zhouben25--> 7<!--Tester: @fenglili18--> 8<!--Adviser: @Brilliantry_Rui--> 9 10本模块提供申请后台任务的接口。当应用退至后台时，开发者可以通过本模块接口为应用申请短时、长时任务，避免应用进程被终止或挂起。 11 12> **说明：** 13> 14> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16 17## 导入模块 18 19```ts 20import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 21``` 22 23## backgroundTaskManager.requestSuspendDelay 24 25requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo 26 27申请短时任务。 28 29> **说明：** 30> 31> 短时任务的申请和使用过程中的约束与限制请参考[指南](../../task-management/transient-task.md#约束与限制)。 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以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 51 52| 错误码ID | 错误信息 | 53| --------- | ------- | 54| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 55| 9800001 | Memory operation failed. | 56| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 57| 9800003 | Internal transaction failed. | 58| 9800004 | System service operation failed. | 59| 9900001 | Caller information verification failed for a transient task. | 60| 9900002 | Transient task verification failed. | 61 62**示例**： 63 64```ts 65import { BusinessError } from '@kit.BasicServicesKit'; 66import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 67 68let myReason = 'test requestSuspendDelay'; 69try { 70 let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { 71 // 回调函数。应用申请的短时任务即将超时，通过此函数回调应用，执行一些清理和标注工作，并取消短时任务 72 // 此处回调与应用的业务功能不耦合，短时任务申请成功后，正常执行应用本身的业务 73 console.info("Request suspension delay will time out."); 74 }) 75 let id = delayInfo.requestId; 76 let time = delayInfo.actualDelayTime; 77 console.info("The requestId is: " + id); 78 console.info("The actualDelayTime is: " + time); 79} catch (error) { 80 console.error(`requestSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 81} 82``` 83 84 85## backgroundTaskManager.getRemainingDelayTime 86 87getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 88 89获取本次短时任务的剩余时间，使用callback异步回调。 90 91**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 92 93**参数**： 94 95| 参数名 | 类型 | 必填 | 说明 | 96| --------- | --------------------------- | ---- | ---------------------------------------- | 97| requestId | number | 是 | 短时任务的请求ID。通过申请短时任务[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)接口获取。 | 98| callback | AsyncCallback<number> | 是 | 回调函数，返回本次短时任务的剩余时间，单位：ms。 | 99 100**错误码**： 101 102以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 103 104| 错误码ID | 错误信息 | 105| --------- | ------- | 106| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 107| 9800001 | Memory operation failed. | 108| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 109| 9800003 | Internal transaction failed. | 110| 9800004 | System service operation failed. | 111| 9900001 | Caller information verification failed for a transient task. | 112| 9900002 | Transient task verification failed. | 113 114 115**示例**： 116 117```ts 118import { BusinessError } from '@kit.BasicServicesKit'; 119import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 120 121let id = 1; 122backgroundTaskManager.getRemainingDelayTime(id, (error: BusinessError, res: number) => { 123 if(error) { 124 console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); 125 } else { 126 console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 127 } 128}) 129``` 130 131 132## backgroundTaskManager.getRemainingDelayTime 133 134getRemainingDelayTime(requestId: number): Promise<number> 135 136获取本次短时任务的剩余时间，使用promise异步回调。 137 138**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 139 140**参数**： 141 142| 参数名 | 类型 | 必填 | 说明 | 143| --------- | ------ | ---- | ---------- | 144| requestId | number | 是 | 短时任务的请求ID。通过申请短时任务[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)接口获取。 | 145 146**返回值**： 147 148| 类型 | 说明 | 149| --------------------- | ---------------------------------------- | 150| Promise<number> | Promise对象，返回本次短时任务的剩余时间，单位：ms。 | 151 152**错误码**： 153 154以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 155 156| 错误码ID | 错误信息 | 157| --------- | ------- | 158| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 159| 9800001 | Memory operation failed. | 160| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 161| 9800003 | Internal transaction failed. | 162| 9800004 | System service operation failed. | 163| 9900001 | Caller information verification failed for a transient task. | 164| 9900002 | Transient task verification failed. | 165 166**示例**： 167 168```ts 169import { BusinessError } from '@kit.BasicServicesKit'; 170import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 171 172let id = 1; 173backgroundTaskManager.getRemainingDelayTime(id).then((res: number) => { 174 console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 175}).catch((error: BusinessError) => { 176 console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); 177}) 178``` 179 180 181## backgroundTaskManager.cancelSuspendDelay 182 183cancelSuspendDelay(requestId: number): void 184 185取消短时任务。 186 187**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 188 189**参数**： 190 191| 参数名 | 类型 | 必填 | 说明 | 192| --------- | ------ | ---- | ---------- | 193| requestId | number | 是 | 短时任务的请求ID。通过申请短时任务[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)接口获取。 | 194 195**错误码**： 196 197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 198 199| 错误码ID | 错误信息 | 200| --------- | ------- | 201| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 202| 9800001 | Memory operation failed. | 203| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 204| 9800003 | Internal transaction failed. | 205| 9800004 | System service operation failed. | 206| 9900001 | Caller information verification failed for a transient task. | 207| 9900002 | Transient task verification failed. | 208 209**示例**： 210 211 ```js 212 import { BusinessError } from '@kit.BasicServicesKit'; 213 import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 214 215 let id = 1; 216 try { 217 backgroundTaskManager.cancelSuspendDelay(id); 218 } catch (error) { 219 console.error(`cancelSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 220 } 221 ``` 222 223## backgroundTaskManager.getTransientTaskInfo<sup>20+</sup> 224 225getTransientTaskInfo(): Promise<TransientTaskInfo> 226 227获取所有短时任务信息，如当日剩余总配额等，使用Promise异步回调。 228 229**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 230 231**返回值**： 232 233| 类型 | 说明 | 234|-----------------------------------------|-------------| 235| Promise<[TransientTaskInfo](#transienttaskinfo20)> | Promise对象，返回所有短时任务信息。 | 236 237**错误码**： 238 239以下错误码的详细介绍请参见[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 240 241| 错误码ID | 错误信息 | 242| --------- | ------- | 243| 9900001 | Caller information verification failed for a transient task. | 244| 9900003 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 245| 9900004 | System service operation failed. | 246 247**示例**： 248 249```ts 250import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 251import { BusinessError } from '@kit.BasicServicesKit'; 252 253try { 254 backgroundTaskManager.getTransientTaskInfo().then((res: backgroundTaskManager.TransientTaskInfo) => { 255 console.info(`Operation getTransientTaskInfo succeeded. data: ` + JSON.stringify(res)); 256 }).catch((error : BusinessError) => { 257 console.error(`Operation getTransientTaskInfo failed. code is ${error.code} message is ${error.message}`); 258 }); 259} catch (error) { 260 console.error(`Operation getTransientTaskInfo failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 261} 262``` 263 264## backgroundTaskManager.startBackgroundRunning 265 266startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 267 268申请长时任务，支持申请一种类型，使用callback异步回调。长时任务申请成功后，会有通知栏消息，没有提示音。 269 270**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 271 272**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 273 274**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 275 276**参数**： 277 278| 参数名 | 类型 | 必填 | 说明 | 279| --------- | ---------------------------------- | ---- | ---------------------------------------- | 280| 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)。 | 281| bgMode | [BackgroundMode](#backgroundmode) | 是 | 长时任务类型。 | 282| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | 是 | 通知参数，用于指定点击长时任务通知后跳转的界面。 | 283| callback | AsyncCallback<void> | 是 | 回调函数，申请长时任务成功时，err为undefined，否则为错误对象。 | 284 285**错误码**： 286 287以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 288 289| 错误码ID | 错误信息 | 290| ---- | --------------------- | 291| 201 | Permission denied. | 292| 202 | Not System App. | 293| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 294| 9800001 | Memory operation failed. | 295| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 296| 9800003 | Internal transaction failed. | 297| 9800004 | System service operation failed. | 298| 9800005 | Continuous task verification failed. | 299| 9800006 | Notification verification failed for a continuous task. | 300| 9800007 | Continuous task storage failed. | 301 302**示例**： 303 304```js 305import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 306import { BusinessError } from '@kit.BasicServicesKit'; 307import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 308import { wantAgent, WantAgent } from '@kit.AbilityKit'; 309// 在原子化服务中，请删除WantAgent导入 310 311function callback(error: BusinessError, data: void) { 312 if (error) { 313 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 314 } else { 315 console.info("Operation startBackgroundRunning succeeded"); 316 } 317} 318 319export default class EntryAbility extends UIAbility { 320 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 321 let wantAgentInfo: wantAgent.WantAgentInfo = { 322 // 点击通知后，将要执行的动作列表 323 wants: [ 324 { 325 bundleName: "com.example.myapplication", 326 abilityName: "EntryAbility" 327 } 328 ], 329 // 点击通知后，动作类型 330 actionType: wantAgent.OperationType.START_ABILITY, 331 // 使用者自定义的一个私有值 332 requestCode: 0, 333 // 点击通知后，动作执行属性 334 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 335 }; 336 337 try { 338 // 通过wantAgent模块下getWantAgent方法获取WantAgent对象 339 // 在原子化服务中，请使用wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: object) => {替换下面一行代码 340 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 341 try { 342 backgroundTaskManager.startBackgroundRunning(this.context, 343 backgroundTaskManager.BackgroundMode.AUDIO_PLAYBACK, wantAgentObj, callback) 344 } catch (error) { 345 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 346 } 347 }); 348 } catch (error) { 349 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 350 } 351 } 352}; 353``` 354 355## backgroundTaskManager.startBackgroundRunning 356 357startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 358 359申请长时任务，支持申请一种类型，使用promise异步回调。长时任务申请成功后，会有通知栏消息，没有提示音。 360 361**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 362 363**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 364 365**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 366 367**参数**： 368 369| 参数名 | 类型 | 必填 | 说明 | 370| --------- | ---------------------------------- | ---- | ---------------------------------------- | 371| 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)。 | 372| bgMode | [BackgroundMode](#backgroundmode) | 是 | 长时任务类型。 | 373| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | 是 | 通知参数，用于指定点击长时任务通知后跳转的界面。 | 374 375**返回值**： 376 377| 类型 | 说明 | 378| -------------- | ---------------- | 379| Promise\<void> | 无返回结果的Promise对象。 | 380 381**错误码**： 382 383以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 384 385| 错误码ID | 错误信息 | 386| ---- | --------------------- | 387| 201 | Permission denied. | 388| 202 | Not System App. | 389| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 390| 9800001 | Memory operation failed. | 391| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 392| 9800003 | Internal transaction failed. | 393| 9800004 | System service operation failed. | 394| 9800005 | Continuous task verification failed. | 395| 9800006 | Notification verification failed for a continuous task. | 396| 9800007 | Continuous task storage failed. | 397 398**示例**： 399 400```js 401import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 402import { BusinessError } from '@kit.BasicServicesKit'; 403import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 404import { wantAgent, WantAgent } from '@kit.AbilityKit'; 405// 在原子化服务中，请删除WantAgent导入 406 407export default class EntryAbility extends UIAbility { 408 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 409 let wantAgentInfo: wantAgent.WantAgentInfo = { 410 // 点击通知后，将要执行的动作列表 411 wants: [ 412 { 413 bundleName: "com.example.myapplication", 414 abilityName: "EntryAbility" 415 } 416 ], 417 // 点击通知后，动作类型 418 actionType: wantAgent.OperationType.START_ABILITY, 419 // 使用者自定义的一个私有值 420 requestCode: 0, 421 // 点击通知后，动作执行属性 422 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 423 }; 424 425 try { 426 // 通过wantAgent模块下getWantAgent方法获取WantAgent对象 427 // 在原子化服务中，请使用wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: object) => {替换下面一行代码 428 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 429 try { 430 backgroundTaskManager.startBackgroundRunning(this.context, 431 backgroundTaskManager.BackgroundMode.AUDIO_PLAYBACK, wantAgentObj).then(() => { 432 console.info("Operation startBackgroundRunning succeeded"); 433 }).catch((error: BusinessError) => { 434 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 435 }); 436 } catch (error) { 437 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 438 } 439 }); 440 } catch (error) { 441 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 442 } 443 } 444}; 445``` 446 447## backgroundTaskManager.stopBackgroundRunning 448 449stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 450 451取消长时任务，使用callback异步回调。 452 453**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 454 455**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 456 457**参数**： 458 459| 参数名 | 类型 | 必填 | 说明 | 460| -------- | ------------------------- | ---- | ---------------------------------------- | 461| 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)。 | 462| callback | AsyncCallback<void> | 是 | 回调函数，取消长时任务成功时，err为undefined，否则为错误对象。| 463 464**错误码**： 465 466以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 467 468| 错误码ID | 错误信息 | 469| ---- | --------------------- | 470| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 471| 9800001 | Memory operation failed. | 472| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 473| 9800003 | Internal transaction failed. | 474| 9800004 | System service operation failed. | 475| 9800005 | Continuous task verification failed. | 476| 9800006 | Notification verification failed for a continuous task. | 477| 9800007 | Continuous task storage failed. | 478 479**示例**： 480 481```js 482import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 483import { BusinessError } from '@kit.BasicServicesKit'; 484import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 485 486function callback(error: BusinessError, data: void) { 487 if (error) { 488 console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 489 } else { 490 console.info("Operation stopBackgroundRunning succeeded"); 491 } 492} 493 494export default class EntryAbility extends UIAbility { 495 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 496 try { 497 backgroundTaskManager.stopBackgroundRunning(this.context, callback); 498 } catch (error) { 499 console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 500 } 501 } 502}; 503``` 504 505## backgroundTaskManager.stopBackgroundRunning 506 507stopBackgroundRunning(context: Context): Promise<void> 508 509取消长时任务，使用promise异步回调。 510 511**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 512 513**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 514 515**参数**： 516 517| 参数名 | 类型 | 必填 | 说明 | 518| ------- | ------- | ---- | ---------------------------------------- | 519| 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)。 | 520 521**返回值**： 522 523| 类型 | 说明 | 524| -------------- | ---------------- | 525| Promise\<void> | 无返回结果的Promise对象。 | 526 527**错误码**： 528 529以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 530 531| 错误码ID | 错误信息 | 532| ---- | --------------------- | 533| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 534| 9800001 | Memory operation failed. | 535| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 536| 9800003 | Internal transaction failed. | 537| 9800004 | System service operation failed. | 538| 9800005 | Continuous task verification failed. | 539| 9800006 | Notification verification failed for a continuous task. | 540| 9800007 | Continuous task storage failed. | 541 542**示例**： 543 544```js 545import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 546import { BusinessError } from '@kit.BasicServicesKit'; 547import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 548 549export default class EntryAbility extends UIAbility { 550 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 551 try { 552 backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { 553 console.info("Operation stopBackgroundRunning succeeded"); 554 }).catch((error: BusinessError) => { 555 console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 556 }); 557 } catch (error) { 558 console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 559 } 560 } 561}; 562``` 563 564## backgroundTaskManager.startBackgroundRunning<sup>12+</sup> 565 566startBackgroundRunning(context: Context, bgModes: string[], wantAgent: WantAgent): Promise<ContinuousTaskNotification> 567 568申请长时任务，支持申请多种类型，使用promise异步回调。长时任务申请成功后，会有通知栏消息，没有提示音。 569 570**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 571 572**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 573 574**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 575 576**参数**： 577 578| 参数名 | 类型 | 必填 | 说明 | 579| --------- | ---------------------------------- | ---- | ---------------------------------------- | 580| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 应用运行的上下文。 | 581| bgModes | string[] | 是 | 长时任务类型，取值范围请参考长时任务类型中的[配置项](../../task-management/continuous-task.md#使用场景)。<br> **说明：** 支持传入一个或多个类型。| 582| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | 是 | 通知参数，用于指定点击长时任务通知后跳转的界面。 | 583 584**返回值**： 585 586| 类型 | 说明 | 587| -------------- | ---------------- | 588| Promise\<ContinuousTaskNotification> | Promise对象，返回[ContinuousTaskNotification](#continuoustasknotification12)类型对象。 | 589 590**错误码**： 591 592以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 593 594| 错误码ID | 错误信息 | 595| ---- | --------------------- | 596| 201 | Permission denied. | 597| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 598| 9800001 | Memory operation failed. | 599| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 600| 9800003 | Internal transaction failed. | 601| 9800004 | System service operation failed. | 602| 9800005 | Continuous task verification failed. | 603| 9800006 | Notification verification failed for a continuous task. | 604| 9800007 | Continuous task storage failed. | 605 606**示例**： 607 608```js 609import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 610import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 611import { BusinessError } from '@kit.BasicServicesKit'; 612import { notificationManager } from '@kit.NotificationKit'; 613import { wantAgent, WantAgent } from '@kit.AbilityKit'; 614// 在原子化服务中，请删除WantAgent导入 615 616export default class EntryAbility extends UIAbility { 617 id: number = 0; // 保存通知id 618 619 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 620 let wantAgentInfo: wantAgent.WantAgentInfo = { 621 // 点击通知后，将要执行的动作列表 622 wants: [ 623 { 624 bundleName: "com.example.myapplication", 625 abilityName: "EntryAbility" 626 } 627 ], 628 // 点击通知后，动作类型 629 actionType: wantAgent.OperationType.START_ABILITY, 630 // 使用者自定义的一个私有值 631 requestCode: 0, 632 // 点击通知后，动作执行属性 633 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 634 }; 635 636 try { 637 // 通过wantAgent模块下getWantAgent方法获取WantAgent对象 638 // 在原子化服务中，请使用wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: object) => {替换下面一行代码 639 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 640 try { 641 let list: Array<string> = ["dataTransfer"]; 642 // 在原子化服务中，let list: Array<string> = ["audioPlayback"]; 643 backgroundTaskManager.startBackgroundRunning(this.context, list, wantAgentObj).then((res: backgroundTaskManager.ContinuousTaskNotification) => { 644 console.info("Operation startBackgroundRunning succeeded"); 645 // 对于上传下载类的长时任务，应用可以使用res中返回的notificationId来更新通知，比如发送带进度条的模板通知 646 this.id = res.notificationId; 647 }).catch((error: BusinessError) => { 648 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 649 }); 650 } catch (error) { 651 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 652 } 653 }); 654 } catch (error) { 655 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 656 } 657 } 658 659 // 应用更新进度 660 updateProcess(process: number) { 661 // 应用定义下载类通知模版 662 let downLoadTemplate: notificationManager.NotificationTemplate = { 663 name: 'downloadTemplate', // 当前只支持downloadTemplate，保持不变 664 data: { 665 title: '文件下载：music.mp4', // 必填 666 fileName: 'senTemplate', // 必填 667 progressValue: process, // 应用更新进度值，自定义 668 } 669 }; 670 let request: notificationManager.NotificationRequest = { 671 content: { 672 // 系统实况类型，保持不变 673 notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_SYSTEM_LIVE_VIEW, 674 systemLiveView: { 675 typeCode: 8, // 上传下载类型需要填写 8，当前仅支持此类型。保持不变 676 title: "test", // 应用自定义 677 text: "test", // 应用自定义 678 } 679 }, 680 id: this.id, // 必须是申请长时任务返回的id，否则应用更新通知失败 681 notificationSlotType: notificationManager.SlotType.LIVE_VIEW, // 实况窗类型，保持不变 682 template: downLoadTemplate // 应用需要设置的模版名称 683 }; 684 685 try { 686 notificationManager.publish(request).then(() => { 687 console.info("publish success, id= " + this.id); 688 }).catch((err: BusinessError) => { 689 console.error(`publish fail: ${JSON.stringify(err)}`); 690 }); 691 } catch (err) { 692 console.error(`publish fail: ${JSON.stringify(err)}`); 693 } 694 } 695}; 696``` 697 698## backgroundTaskManager.updateBackgroundRunning<sup>12+</sup> 699 700updateBackgroundRunning(context: Context, bgModes: string[]): Promise<ContinuousTaskNotification> 701 702更新长时任务类型，使用promise异步回调。长时任务更新成功后，会有通知栏消息，没有提示音。 703 704**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 705 706**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 707 708**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 709 710**参数**： 711 712| 参数名 | 类型 | 必填 | 说明 | 713| --------- | ---------------------------------- | ---- | ---------------------------------------- | 714| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 应用运行的上下文。 | 715| bgModes | string[] | 是 | 更新后的长时任务类型，取值范围请参考长时任务类型中的[配置项](../../task-management/continuous-task.md#使用场景)。<br> **说明：** 支持传入一个或多个类型。| 716 717**返回值**： 718 719| 类型 | 说明 | 720| -------------- | ---------------- | 721| Promise\<ContinuousTaskNotification> | Promise对象，返回[ContinuousTaskNotification](#continuoustasknotification12)类型对象。 | 722 723**错误码**： 724 725以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 726 727| 错误码ID | 错误信息 | 728| ---- | --------------------- | 729| 201 | Permission denied. | 730| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 731| 9800001 | Memory operation failed. | 732| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 733| 9800003 | Internal transaction failed. | 734| 9800004 | System service operation failed. | 735| 9800005 | Continuous task verification failed. | 736| 9800006 | Notification verification failed for a continuous task. | 737| 9800007 | Continuous task storage failed. | 738 739**示例**： 740 741```js 742import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 743import { BusinessError } from '@kit.BasicServicesKit'; 744import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 745 746export default class EntryAbility extends UIAbility { 747 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 748 try { 749 // 必须先执行startBackgroundRunning，才能调用updateBackgroundRunning，这里假设已经申请过 750 let list: Array<string> = ["audioPlayback"]; 751 backgroundTaskManager.updateBackgroundRunning(this.context, list).then(() => { 752 console.info("Operation updateBackgroundRunning succeeded"); 753 }).catch((error: BusinessError) => { 754 console.error(`Operation updateBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 755 }); 756 } catch (error) { 757 console.error(`Operation updateBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 758 } 759 } 760}; 761``` 762 763## backgroundTaskManager.getAllContinuousTasks<sup>20+</sup> 764 765getAllContinuousTasks(context: Context): Promise<ContinuousTaskInfo[]> 766 767获取所有长时任务信息，如长时任务Id、长时任务类型等，使用Promise异步回调。 768 769**需要权限**: ohos.permission.KEEP_BACKGROUND_RUNNING 770 771**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 772 773**参数**： 774 775| 参数名 | 类型 | 必填 | 说明 | 776| --------- | ---------------------------------- | ---- | ---------------------------------------- | 777| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 应用运行的上下文。 | 778 779**返回值**： 780 781| 类型 | 说明 | 782|-----------------------------------------------|-------------| 783| Promise<[ContinuousTaskInfo](#continuoustaskinfo20)[]> | Promise对象，返回所有长时任务信息。 | 784 785**错误码**： 786 787以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 788 789| 错误码ID | 错误信息 | 790| --------- | ------- | 791| 201 | Permission denied. | 792| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 793| 9800004 | System service operation failed. | 794| 9800005 | Continuous task verification failed. | 795 796**示例**： 797 798```ts 799import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 800import { BusinessError } from '@kit.BasicServicesKit'; 801import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 802 803export default class EntryAbility extends UIAbility { 804 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 805 try { 806 // 如果当前没有申请长时任务，则获取到一个空数组 807 backgroundTaskManager.getAllContinuousTasks(this.context).then((res: backgroundTaskManager.ContinuousTaskInfo[]) => { 808 console.info(`Operation getAllContinuousTasks succeeded. data: ` + JSON.stringify(res)); 809 }).catch((error: BusinessError) => { 810 console.error(`Operation getAllContinuousTasks failed. code is ${error.code} message is ${error.message}`); 811 }); 812 } catch (error) { 813 console.error(`Operation getAllContinuousTasks failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 814 } 815 } 816}; 817``` 818 819## backgroundTaskManager.getAllContinuousTasks<sup>20+</sup> 820 821getAllContinuousTasks(context: Context, includeSuspended: boolean): Promise<ContinuousTaskInfo[]> 822 823获取所有长时任务信息，如长时任务Id、长时任务类型等。可选择是否获取暂停的长时任务信息，使用Promise异步回调。 824 825**需要权限**: ohos.permission.KEEP_BACKGROUND_RUNNING 826 827**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 828 829**参数**： 830 831| 参数名 | 类型 | 必填 | 说明 | 832| --------- | ---------------------------------- | ---- | ---------------------------------------- | 833| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 应用运行的上下文。 | 834| includeSuspended | boolean | 是 | 是否获取暂停的长时任务信息， true表示获取， false表示不获取。 | 835 836**返回值**： 837 838| 类型 | 说明 | 839|-----------------------------------------------|-------------| 840| Promise<[ContinuousTaskInfo](#continuoustaskinfo20)[]> | Promise对象，返回所有长时任务信息。 | 841 842**错误码**： 843 844以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 845 846| 错误码ID | 错误信息 | 847| --------- | ------- | 848| 201 | Permission denied. | 849| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 850| 9800004 | System service operation failed. | 851| 9800005 | Continuous task verification failed. | 852 853**示例**： 854 855```ts 856import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 857import { BusinessError } from '@kit.BasicServicesKit'; 858import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 859 860export default class EntryAbility extends UIAbility { 861 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 862 try { 863 // 如果当前没有申请长时任务，则获取到一个空数组 864 backgroundTaskManager.getAllContinuousTasks(this.context, false).then((res: backgroundTaskManager.ContinuousTaskInfo[]) => { 865 console.info(`Operation getAllContinuousTasks succeeded. data: ` + JSON.stringify(res)); 866 }).catch((error: BusinessError) => { 867 console.error(`Operation getAllContinuousTasks failed. code is ${error.code} message is ${error.message}`); 868 }); 869 } catch (error) { 870 console.error(`Operation getAllContinuousTasks failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 871 } 872 } 873}; 874``` 875 876## backgroundTaskManager.on('continuousTaskCancel')<sup>15+</sup> 877 878on(type: 'continuousTaskCancel', callback: Callback<ContinuousTaskCancelInfo>): void 879 880注册长时任务取消的监听，使用callback异步回调。 881 882**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 883 884**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 885 886**参数**： 887 888| 参数名 | 类型 | 必填 | 说明 | 889| --------- | ---------------------------------- | ---- | ---------------------------------------- | 890| type | string | 是 | 取消长时任务，固定取值为'continuousTaskCancel'。 | 891| callback | Callback\<[ContinuousTaskCancelInfo](#continuoustaskcancelinfo15)> | 是 | 回调函数，返回长时任务取消原因等信息。 | 892 893**错误码**： 894 895以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 896 897| 错误码ID | 错误信息 | 898| ---- | --------------------- | 899| 201 | Permission denied. | 900| 401 | Parameter error. Possible cause: 1. Callback parameter error; 2. Register a exist callback type; 3. Parameter verification failed. | 901 902**示例**： 903 904```js 905import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 906import { BusinessError } from '@kit.BasicServicesKit'; 907import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 908 909function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) { 910 console.info('continuousTaskCancel callback id ' + info.id); 911 console.info('continuousTaskCancel callback reason ' + info.reason); 912} 913 914export default class EntryAbility extends UIAbility { 915 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 916 try { 917 backgroundTaskManager.on("continuousTaskCancel", callback); 918 } catch (error) { 919 console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 920 } 921 } 922}; 923``` 924## backgroundTaskManager.off('continuousTaskCancel')<sup>15+</sup> 925 926off(type: 'continuousTaskCancel', callback?: Callback<ContinuousTaskCancelInfo>): void 927 928解除长时任务取消的监听，使用callback异步回调。 929 930**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 931 932**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 933 934**参数**： 935 936| 参数名 | 类型 | 必填 | 说明 | 937| --------- | ---------------------------------- | ---- | ---------------------------------------- | 938| type | string | 是 | 取消长时任务，固定取值为'continuousTaskCancel'。 | 939| callback | Callback\<[ContinuousTaskCancelInfo](#continuoustaskcancelinfo15)> | 否 | 需要取消监听的回调函数，未传入则取消所有注册回调。 | 940 941**错误码**： 942 943以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 944 945| 错误码ID | 错误信息 | 946| ---- | --------------------- | 947| 201 | Permission denied. | 948| 401 | Parameter error. Possible cause: 1. Callback parameter error; 2. Unregister type has not register; 3. Parameter verification failed. | 949 950**示例**： 951 952```js 953import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 954import { BusinessError } from '@kit.BasicServicesKit'; 955import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 956 957function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) { 958 console.info('continuousTaskCancel callback id ' + info.id); 959 console.info('continuousTaskCancel callback reason ' + info.reason); 960} 961 962export default class EntryAbility extends UIAbility { 963 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 964 try { 965 backgroundTaskManager.off("continuousTaskCancel", callback); 966 } catch (error) { 967 console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 968 } 969 } 970}; 971``` 972## backgroundTaskManager.on('continuousTaskSuspend')<sup>20+</sup> 973 974on(type: 'continuousTaskSuspend', callback: Callback<ContinuousTaskSuspendInfo>): void 975 976注册长时任务暂停的监听，使用callback异步回调。注册该回调后，如果系统首次检测到应用未执行相应的业务，不会直接取消长时任务，而是将长时任务标记为暂停状态，如果连续检测失败，仍会取消长时任务。<br>长时任务处于暂停状态时，应用退后台会被挂起，回前台自动激活。 977 978**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 979 980**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 981 982**参数**： 983 984| 参数名 | 类型 | 必填 | 说明 | 985| --------- | ---------------------------------- | ---- | ---------------------------------------- | 986| type | string | 是 | 事件回调类型，固定取值为'continuousTaskSuspend'，表示长时任务暂停。 | 987| callback | Callback\<[ContinuousTaskSuspendInfo](#continuoustasksuspendinfo20)> | 是 | 回调函数，返回长时任务暂停原因等信息。 | 988 989**错误码**： 990 991以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 992 993| 错误码ID | 错误信息 | 994| ---- | --------------------- | 995| 201 | Permission denied. | 996| 9800005 | Continuous task verification failed. | 997 998**示例**： 999 1000 1001```js 1002import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 1003import { BusinessError } from '@kit.BasicServicesKit'; 1004import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 1005 1006function callback(info: backgroundTaskManager.ContinuousTaskSuspendInfo) { 1007 console.info('continuousTaskSuspend callback continuousTaskId: ' + info.continuousTaskId); 1008 console.info('continuousTaskSuspend callback suspendState: ' + info.suspendState); 1009 console.info('continuousTaskSuspend callback suspendReason: ' + info.suspendReason); 1010} 1011 1012export default class EntryAbility extends UIAbility { 1013 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1014 try { 1015 backgroundTaskManager.on("continuousTaskSuspend", callback); 1016 } catch (error) { 1017 console.error(`Operation onContinuousTaskSuspend failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 1018 } 1019 } 1020}; 1021``` 1022## backgroundTaskManager.off('continuousTaskSuspend')<sup>20+</sup> 1023 1024off(type: 'continuousTaskSuspend', callback?: Callback<ContinuousTaskSuspendInfo>): void 1025 1026取消长时任务暂停的监听，使用callback异步回调。 1027 1028**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 1029 1030**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1031 1032**参数**： 1033 1034| 参数名 | 类型 | 必填 | 说明 | 1035| --------- | ---------------------------------- | ---- | ---------------------------------------- | 1036| type | string | 是 | 事件回调类型，固定取值为'continuousTaskSuspend'，表示长时任务暂停。 | 1037| callback | Callback\<[ContinuousTaskSuspendInfo](#continuoustasksuspendinfo20)> | 否 | 需要取消监听的回调函数，未传入则取消所有注册的暂停回调。 | 1038 1039**错误码**： 1040 1041以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 1042 1043| 错误码ID | 错误信息 | 1044| ---- | --------------------- | 1045| 201 | Permission denied. | 1046| 9800005 | Continuous task verification failed. | 1047 1048**示例**： 1049 1050```js 1051import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 1052import { BusinessError } from '@kit.BasicServicesKit'; 1053import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 1054 1055function callback(info: backgroundTaskManager.ContinuousTaskSuspendInfo) { 1056 console.info('continuousTaskSuspend callback continuousTaskId: ' + info.continuousTaskId); 1057 console.info('continuousTaskSuspend callback suspendState: ' + info.suspendState); 1058 console.info('continuousTaskSuspend callback suspendReason: ' + info.suspendReason); 1059} 1060 1061export default class EntryAbility extends UIAbility { 1062 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1063 try { 1064 backgroundTaskManager.off("continuousTaskSuspend", callback); 1065 } catch (error) { 1066 console.error(`Operation offContinuousTaskSuspend failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 1067 } 1068 } 1069}; 1070``` 1071## backgroundTaskManager.on('continuousTaskActive')<sup>20+</sup> 1072 1073on(type: 'continuousTaskActive', callback: Callback<ContinuousTaskActiveInfo>): void 1074 1075注册长时任务激活的监听，使用callback异步回调。应用回前台激活暂停的长时任务。 1076 1077**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 1078 1079**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1080 1081**参数**： 1082 1083| 参数名 | 类型 | 必填 | 说明 | 1084| --------- | ---------------------------------- | ---- | ---------------------------------------- | 1085| type | string | 是 | 事件回调类型，固定取值为'continuousTaskActive'，表示长时任务激活。 | 1086| callback | Callback\<[ContinuousTaskActiveInfo](#continuoustaskactiveinfo20)> | 是 | 回调函数，返回长时任务激活相关信息。 | 1087 1088**错误码**： 1089 1090以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 1091 1092| 错误码ID | 错误信息 | 1093| ---- | --------------------- | 1094| 201 | Permission denied. | 1095| 9800005 | Continuous task verification failed. | 1096 1097**示例**： 1098 1099```js 1100import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 1101import { BusinessError } from '@kit.BasicServicesKit'; 1102import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 1103 1104function callback(info: backgroundTaskManager.ContinuousTaskActiveInfo) { 1105 console.info('continuousTaskActive callback id: ' + info.id); 1106} 1107 1108export default class EntryAbility extends UIAbility { 1109 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1110 try { 1111 backgroundTaskManager.on("continuousTaskActive", callback); 1112 } catch (error) { 1113 console.error(`Operation onContinuousTaskActive failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 1114 } 1115 } 1116}; 1117``` 1118## backgroundTaskManager.off('continuousTaskActive')<sup>20+</sup> 1119 1120off(type: 'continuousTaskActive', callback?: Callback<ContinuousTaskActiveInfo>): void 1121 1122取消长时任务激活的监听，使用callback异步回调。 1123 1124**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 1125 1126**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1127 1128**参数**： 1129 1130| 参数名 | 类型 | 必填 | 说明 | 1131| --------- | ---------------------------------- | ---- | ---------------------------------------- | 1132| type | string | 是 | 事件回调类型，固定取值为'continuousTaskActive'，表示长时任务激活。 | 1133| callback | Callback\<[ContinuousTaskActiveInfo](#continuoustaskactiveinfo20)> | 否 | 需要取消监听的回调函数，未传入则取消所有注册的激活回调。 | 1134 1135**错误码**： 1136 1137以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 1138 1139| 错误码ID | 错误信息 | 1140| ---- | --------------------- | 1141| 201 | Permission denied. | 1142| 9800005 | Continuous task verification failed. | 1143 1144**示例**： 1145 1146```js 1147import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 1148import { BusinessError } from '@kit.BasicServicesKit'; 1149import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 1150 1151function callback(info: backgroundTaskManager.ContinuousTaskActiveInfo) { 1152 console.info('continuousTaskActive callback id: ' + info.id); 1153} 1154 1155export default class EntryAbility extends UIAbility { 1156 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1157 try { 1158 backgroundTaskManager.off("continuousTaskActive", callback); 1159 } catch (error) { 1160 console.error(`Operation offContinuousTaskActive failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 1161 } 1162 } 1163}; 1164``` 1165 1166## DelaySuspendInfo 1167 1168短时任务信息。 1169 1170**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 1171 1172| 名称 | 类型 | 只读 | 可选 | 说明 | 1173| --------------- | ------ | ---- | ---- | ---------------------------------------- | 1174| requestId | number | 否 | 否 | 短时任务的请求ID。 | 1175| actualDelayTime | number | 否 | 否 | 应用实际申请的短时任务时间，单位：ms。<br/> **说明** ：申请时间最长为3分钟，[低电量](../apis-basic-services-kit/js-apis-battery-info.md)时最长为1分钟。 | 1176 1177## TransientTaskInfo<sup>20+</sup> 1178 1179所有短时任务信息。 1180 1181**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 1182 1183| 名称 | 类型 | 只读 | 可选 | 说明 | 1184| --------------- |-----------------------------------------| ---- | ---- |-----------------| 1185| remainingQuota | number | 否 | 否 | 应用当日所剩余总配额，单位：ms。 | 1186| transientTasks | [DelaySuspendInfo](#delaysuspendinfo)[] | 否 | 否 | 当前已申请的所有短时任务信息。 | 1187 1188## BackgroundMode 1189 1190长时任务类型。 1191 1192**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1193 1194| 名称 | 值 | 说明 | 1195| ----------------------- | ---- | --------------------- | 1196| DATA_TRANSFER | 1 | 数据传输。 | 1197| AUDIO_PLAYBACK | 2 | 音视频播放。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1198| AUDIO_RECORDING | 3 | 录制。 | 1199| LOCATION | 4 | 定位导航。 | 1200| BLUETOOTH_INTERACTION | 5 | 蓝牙相关业务。 | 1201| MULTI_DEVICE_CONNECTION | 6 | 多设备互联。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1202| VOIP<sup>13+</sup> | 8 | 音视频通话。 | 1203| TASK_KEEPING | 9 | 计算任务（仅对2in1设备开放）。 | 1204 1205## ContinuousTaskNotification<sup>12+</sup> 1206 1207长时任务通知信息。 1208 1209**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1210 1211| 名称 | 类型 | 只读 | 可选 | 说明 | 1212| --------------- | ------ | ---- | ---- | ---------------------------------------- | 1213| slotType | [notificationManager.SlotType](../apis-notification-kit/js-apis-notificationManager.md#slottype) | 否 | 否 | 长时任务通知的渠道类型。<br/>**说明：** 长时任务申请或更新成功后不支持提示音。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1214| contentType | [notificationManager.ContentType](../apis-notification-kit/js-apis-notificationManager.md#contenttype) | 否 | 否 | 长时任务通知的内容类型。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1215| notificationId | number | 否 | 否 | 长时任务通知 Id。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1216| continuousTaskId<sup>15+</sup> | number | 否 | 是 | 长时任务 Id。| 1217 1218## ContinuousTaskCancelInfo<sup>15+</sup> 1219 1220长时任务取消信息。 1221 1222**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1223 1224| 名称 | 类型 | 只读 | 可选 | 说明 | 1225| --------------- | ------ | ---- | ---- | ---------------------------------------- | 1226| reason | [ContinuousTaskCancelReason](#continuoustaskcancelreason15) | 否 | 否 | 长时任务取消原因。| 1227| id | number | 否 | 否 | 被取消的长时任务 Id。| 1228 1229## ContinuousTaskCancelReason<sup>15+</sup> 1230 1231长时任务取消原因。 1232 1233**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1234 1235| 名称 | 值 | 说明 | 1236| ----------------------- | ---- | --------------------- | 1237| USER_CANCEL | 1 | 用户取消。 | 1238| SYSTEM_CANCEL | 2 | 系统取消。 | 1239| USER_CANCEL_REMOVE_NOTIFICATION | 3 | 用户移除通知。预留接口，暂未启用。 | 1240| SYSTEM_CANCEL_DATA_TRANSFER_LOW_SPEED | 4 | 申请DATA_TRANSFER类型长时任务，但是数据传输速率低。预留接口，暂未启用。 | 1241| SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_USE_AVSESSION | 5 | 申请AUDIO_PLAYBACK类型长时任务，但是未接入[AVSession](../../media/avsession/avsession-overview.md)。预留接口，暂未启用。 | 1242| SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_RUNNING | 6 | 申请AUDIO_PLAYBACK类型长时任务，但是未播放音视频。预留接口，暂未启用。 | 1243| SYSTEM_CANCEL_AUDIO_RECORDING_NOT_RUNNING | 7 | 申请AUDIO_RECORDING类型长时任务，但是未录制。预留接口，暂未启用。 | 1244| SYSTEM_CANCEL_NOT_USE_LOCATION | 8 | 申请LOCATION类型长时任务，但是未使用定位导航。预留接口，暂未启用。 | 1245| SYSTEM_CANCEL_NOT_USE_BLUETOOTH | 9 | 申请BLUETOOTH_INTERACTION类型长时任务，但是未使用蓝牙相关业务。预留接口，暂未启用。 | 1246| SYSTEM_CANCEL_NOT_USE_MULTI_DEVICE | 10 | 申请MULTI_DEVICE_CONNECTION类型长时任务，但是未使用多设备互联。预留接口，暂未启用。 | 1247| SYSTEM_CANCEL_USE_ILLEGALLY | 11 | 使用非法类型的长时任务，如申请AUDIO_PLAYBACK类型长时任务，但是使用音视频播放及定位导航业务。预留接口，暂未启用。 | 1248 1249## BackgroundSubMode<sup>16+</sup> 1250 1251长时任务子类型。 1252 1253**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1254 1255| 名称 | 值 | 说明 | 1256| ----------------------- | ---- | --------------------- | 1257| CAR_KEY | 1 | 车钥匙。<br/>**说明：** 只有申请BLUETOOTH_INTERACTION类型的长时任务，车钥匙子类型才能生效。 | 1258 1259## BackgroundModeType<sup>16+</sup> 1260 1261长时任务类型类别。 1262 1263**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1264 1265| 名称 | 值 | 说明 | 1266| ----------------------- | ---- | --------------------- | 1267| SUB_MODE | 'subMode' | 子类型。 | 1268 1269## ContinuousTaskSuspendInfo<sup>20+</sup> 1270 1271长时任务暂停信息。 1272 1273**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1274 1275| 名称 | 类型 | 只读 | 可选 | 说明 | 1276| --------------- | ------ | ---- | ---- | ---------------------------------------- | 1277| continuousTaskId | number | 否 | 否 | 被暂停的长时任务 Id。| 1278| suspendState | boolean | 否 | 否 | 长时任务状态，false表示激活，true表示暂停。| 1279| suspendReason | [ContinuousTaskSuspendReason](#continuoustasksuspendreason20) | 否 | 否 | 长时任务暂停原因。| 1280 1281## ContinuousTaskSuspendReason<sup>20+</sup> 1282 1283长时任务暂停原因。 1284 1285**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1286 1287| 名称 | 值 | 说明 | 1288| ----------------------- | ---- | --------------------- | 1289| SYSTEM_SUSPEND_DATA_TRANSFER_LOW_SPEED | 4 | 申请DATA_TRANSFER类型长时任务，但是数据传输速率低。 | 1290| SYSTEM_SUSPEND_AUDIO_PLAYBACK_NOT_USE_AVSESSION | 5 | 申请AUDIO_PLAYBACK类型长时任务，但是未接入[AVSession](../../media/avsession/avsession-overview.md)。 | 1291| SYSTEM_SUSPEND_AUDIO_PLAYBACK_NOT_RUNNING | 6 | 申请AUDIO_PLAYBACK类型长时任务，但是未播放音视频。 | 1292| SYSTEM_SUSPEND_AUDIO_RECORDING_NOT_RUNNING | 7 | 申请AUDIO_RECORDING类型长时任务，但是未录制。 | 1293| SYSTEM_SUSPEND_LOCATION_NOT_USED | 8 | 申请LOCATION类型长时任务，但是未使用定位导航。 | 1294| SYSTEM_SUSPEND_BLUETOOTH_NOT_USED | 9 | 申请BLUETOOTH_INTERACTION类型长时任务，但是未使用蓝牙相关业务。 | 1295| SYSTEM_SUSPEND_MULTI_DEVICE_NOT_USED | 10 | 申请MULTI_DEVICE_CONNECTION类型长时任务，但是未使用多设备互联。 | 1296| SYSTEM_SUSPEND_USED_ILLEGALLY | 11 | 使用非法类型的长时任务，如申请AUDIO_PLAYBACK类型长时任务，但是使用音视频播放及定位导航业务。预留接口，暂未启用。 | 1297| SYSTEM_SUSPEND_SYSTEM_LOAD_WARNING | 12 | 系统高负载暂停长时任务。预留接口，暂未启用。 | 1298 1299## ContinuousTaskActiveInfo<sup>20+</sup> 1300 1301长时任务激活信息。 1302 1303**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1304 1305| 名称 | 类型 | 只读 | 可选 | 说明 | 1306| --------------- | ------ | ---- | ---- | ---------------------------------------- | 1307| id | number | 否 | 否 | 被激活的长时任务 Id。| 1308 1309## ContinuousTaskInfo<sup>20+</sup> 1310 1311长时任务信息。 1312 1313**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 1314 1315| 名称 | 类型 | 只读 | 可选 | 说明 | 1316|-------------|----------| ---- | ---- |-----------------------| 1317| abilityName | string | 否 | 否 | UIAbility名称。 | 1318| uid | number | 否 | 否 | 应用的UID。 | 1319| pid | number | 否 | 否 | 应用进程的PID。 | 1320| isFromWebView | boolean | 否 | 否 | 是否通过Webview方式申请，即通过系统代理应用申请长时任务。 | 1321| [backgroundModes](#backgroundmode) | string[] | 否 | 否 | 长时任务类型。 | 1322| [backgroundSubModes](#backgroundsubmode16) | string[] | 否 | 否 | 长时任务子类型。 | 1323| notificationId | number | 否 | 否 | 通知 Id。 | 1324| continuousTaskId | number | 否 | 否 | 长时任务Id。 | 1325| abilityId | number | 否 | 否 | UIAbility Id。 | 1326| wantAgentBundleName | string | 否 | 否 | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) 配置的包名。WantAgent为通知参数，用于指定点击长时任务通知后跳转的界面，在申请长时任务时作为参数传入。 | 1327| wantAgentAbilityName | string | 否 | 否 | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) 配置的ability名称。WantAgent为通知参数，用于指定点击长时任务通知后跳转的界面，在申请长时任务时作为参数传入。 | 1328| suspendState | boolean | 否 | 否 | 申请的长时任务是否处于暂停状态。 |