1# 后台任务管理 2 3本模块提供后台任务管理能力。 4 5当应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。 6 7应用有不可中断且短时间能完成的任务时（如，用户在文件管理器上点击垃圾文件清理，若清理未完成时退到后台，文件管理器需要申请短时任务完成清理），可以使用短时任务机制。 8 9应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。 10 11>  **说明：** 12> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13 14 15## 导入模块 16 17``` 18import backgroundTaskManager from '@ohos.backgroundTaskManager'; 19``` 20 21 22## backgroundTaskManager.requestSuspendDelay 23 24requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo 25 26后台应用申请延迟挂起。 27 28延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 29 30**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 31 32**参数**： 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | -------------------- | ---- | ------------------------------ | 35| reason | string | 是 | 延迟挂起申请的原因。 | 36| callback | Callback<void> | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 | 37 38**返回值**： 39| 类型 | 说明 | 40| ------------------------------------- | --------- | 41| [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | 42 43**示例**： 44 45 ```js 46 let myReason = 'test requestSuspendDelay'; 47 let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { 48 console.info("Request suspension delay will time out."); 49 }) 50 51 var id = delayInfo.requestId; 52 var time = delayInfo.actualDelayTime; 53 console.info("The requestId is: " + id); 54 console.info("The actualDelayTime is: " + time); 55 ``` 56 57 58## backgroundTaskManager.getRemainingDelayTime 59 60getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 61 62获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 63 64**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 65 66**参数**： 67| 参数名 | 类型 | 必填 | 说明 | 68| --------- | --------------------------- | ---- | ---------------------------------------- | 69| requestId | number | 是 | 延迟挂起的请求ID。 | 70| callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | 71 72**示例**： 73 74 ```js 75 let id = 1; 76 backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { 77 if(err) { 78 console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code); 79 } else { 80 console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 81 } 82 }) 83 ``` 84 85 86## backgroundTaskManager.getRemainingDelayTime 87 88getRemainingDelayTime(requestId: number): Promise<number> 89 90获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 91 92**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 93 94**参数**： 95| 参数名 | 类型 | 必填 | 说明 | 96| --------- | ------ | ---- | ---------- | 97| requestId | number | 是 | 延迟挂起的请求ID。 | 98 99**返回值**： 100| 类型 | 说明 | 101| --------------------- | ---------------------------------------- | 102| Promise<number> | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | 103 104**示例**： 105 ```js 106 let id = 1; 107 backgroundTaskManager.getRemainingDelayTime(id).then( res => { 108 console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 109 }).catch( err => { 110 console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); 111 }) 112 ``` 113 114 115## backgroundTaskManager.cancelSuspendDelay 116 117cancelSuspendDelay(requestId: number): void 118 119取消延迟挂起。 120 121**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 122 123**参数**： 124| 参数名 | 类型 | 必填 | 说明 | 125| --------- | ------ | ---- | ---------- | 126| requestId | number | 是 | 延迟挂起的请求ID。 | 127 128**示例**： 129 ```js 130 let id = 1; 131 backgroundTaskManager.cancelSuspendDelay(id); 132 ``` 133 134 135## backgroundTaskManager.startBackgroundRunning<sup>8+</sup> 136 137startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 138 139向系统申请长时任务，使用callback形式返回结果。 140 141**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 142 143**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 144 145**参数**： 146| 参数名 | 类型 | 必填 | 说明 | 147| --------- | ---------------------------------- | ---- | ------------------------ | 148| context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文。 | 149| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | 150| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击后跳转的界面。 | 151| callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | 152 153**示例**： 154```js 155import backgroundTaskManager from '@ohos.backgroundTaskManager'; 156import featureAbility from '@ohos.ability.featureAbility'; 157import wantAgent from '@ohos.wantAgent'; 158 159function callback(err, data) { 160 if (err) { 161 console.error("Operation startBackgroundRunning failed Cause: " + err); 162 } else { 163 console.info("Operation startBackgroundRunning succeeded"); 164 } 165} 166 167let wantAgentInfo = { 168 wants: [ 169 { 170 bundleName: "com.example.myapplication", 171 abilityName: "com.example.myapplication.MainAbility" 172 } 173 ], 174 operationType: wantAgent.OperationType.START_ABILITY, 175 requestCode: 0, 176 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 177}; 178 179wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 180 backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), 181 backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback) 182}); 183 184``` 185 186## backgroundTaskManager.startBackgroundRunning<sup>8+</sup> 187 188startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 189 190向系统申请长时任务，使用promise形式返回结果。 191 192**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 193 194**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 195 196**参数**： 197 198| 参数名 | 类型 | 必填 | 说明 | 199| --------- | ---------------------------------- | ---- | ----------------------- | 200| context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文。 | 201| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | 202| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。 | 203 204**返回值** 205| 类型 | 说明 | 206| -------------- | ---------------- | 207| Promise\<void> | 使用Promise形式返回结果。 | 208 209**示例**： 210```js 211import backgroundTaskManager from '@ohos.backgroundTaskManager'; 212import featureAbility from '@ohos.ability.featureAbility'; 213import wantAgent from '@ohos.wantAgent'; 214 215let wantAgentInfo = { 216 wants: [ 217 { 218 bundleName: "com.example.myapplication", 219 abilityName: "com.example.myapplication.MainAbility" 220 } 221 ], 222 operationType: wantAgent.OperationType.START_ABILITY, 223 requestCode: 0, 224 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 225}; 226 227wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 228 backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), 229 backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { 230 console.info("Operation startBackgroundRunning succeeded"); 231 }).catch((err) => { 232 console.error("Operation startBackgroundRunning failed Cause: " + err); 233 }); 234}); 235 236``` 237 238## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup> 239 240stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 241 242向系统申请取消长时任务，使用callback形式返回结果。 243 244**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 245 246**参数**： 247| 参数名 | 类型 | 必填 | 说明 | 248| -------- | ----------------------------- | ---- | ---------------------- | 249| context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文。 | 250| callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | 251 252**示例**： 253```js 254import backgroundTaskManager from '@ohos.backgroundTaskManager'; 255import featureAbility from '@ohos.ability.featureAbility'; 256 257function callback(err, data) { 258 if (err) { 259 console.error("Operation stopBackgroundRunning failed Cause: " + err); 260 } else { 261 console.info("Operation stopBackgroundRunning succeeded"); 262 } 263} 264 265backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback); 266 267``` 268 269## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup> 270 271stopBackgroundRunning(context: Context): Promise<void> 272 273向系统申请取消长时任务，使用promise形式返回结果。 274 275**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 276 277**参数**： 278| 参数名 | 类型 | 必填 | 说明 | 279| ------- | ----------------------------- | ---- | --------- | 280| context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文。 | 281 282**返回值** 283| 类型 | 说明 | 284| -------------- | ---------------- | 285| Promise\<void> | 使用Promise形式返回结果。 | 286 287**示例**： 288```js 289import backgroundTaskManager from '@ohos.backgroundTaskManager'; 290import featureAbility from '@ohos.ability.featureAbility'; 291 292backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { 293 console.info("Operation stopBackgroundRunning succeeded"); 294}).catch((err) => { 295 console.error("Operation stopBackgroundRunning failed Cause: " + err); 296}); 297 298``` 299 300## DelaySuspendInfo 301 302延迟挂起信息。 303 304**系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 305 306| 参数名 | 类型 | 必填 | 说明 | 307| --------------- | ------ | ---- | ---------------------------------------- | 308| requestId | number | 是 | 延迟挂起的请求ID。 | 309| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | 310 311 312## BackgroundMode<sup>8+</sup> 313 314**系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 315 316| 参数名 | 参数值 | 描述 | 317| ----------------------- | ------ | ------------------------------------------------------------ | 318| DATA_TRANSFER | 1 | 数据传输 | 319| AUDIO_PLAYBACK | 2 | 音频播放 | 320| AUDIO_RECORDING | 3 | 录音 | 321| LOCATION | 4 | 定位导航 | 322| BLUETOOTH_INTERACTION | 5 | 蓝牙相关 | 323| MULTI_DEVICE_CONNECTION | 6 | 多设备互联 | 324| WIFI_INTERACTION | 7 | WLAN相关<br />**系统API**：此接口为系统接口，三方应用不支持调用。 | 325| VOIP | 8 | 音视频通话<br />**系统API**：此接口为系统接口，三方应用不支持调用。 | 326| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效） |
