js-apis-backgroundTaskManager.md 25.3 KB
Newer Older
廖康康 已提交
1 2
# 后台任务管理

廖康康 已提交
3
本模块提供后台任务管理能力。
廖康康 已提交
4

廖康康 已提交
5 6
当应用或业务模块处于后台(无可见界面)时,如果有需要继续执行或者后续执行的业务,可基于业务类型,申请短时任务延迟挂起(Suspend)或者长时任务避免进入挂起状态。

廖康康 已提交
7
应用有不可中断且短时间能完成的任务时(如,用户在文件管理器上点击垃圾文件清理,若清理未完成时退到后台,文件管理器需要申请短时任务完成清理),可以使用短时任务机制。
廖康康 已提交
8 9

应用中存在用户能够直观感受到的且需要一直在后台运行的业务时(如,后台播放音乐),可以使用长时任务机制。
廖康康 已提交
10

Z
zhangxin_T 已提交
11
对于系统特权应用,提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源,例如需要在被挂起期间仍然能够收到系统公共事件,可以使用能效资源申请接口。
Z
Zhao-PengFei35 已提交
12

H
HelloCrease 已提交
13
>  **说明:**
修改  
朱天怡 已提交
14 15
> - 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。从API version 9开始,导入模块由@ohos.backgroundTaskManager迁移至@ohos.resourceschedule.backgroundTaskManager
> - 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。
廖康康 已提交
16

修改  
朱天怡 已提交
17

修改  
朱天怡 已提交
18 19 20
## 导入模块

```js
修改  
朱天怡 已提交
21
import backgroundTaskManager from '@ohos.backgroundTaskManager';  
廖康康 已提交
22 23
```

修改  
朱天怡 已提交
24

25
## backgroundTaskManager.requestSuspendDelay<sup>7+(deprecated)</sup>
廖康康 已提交
26 27 28 29 30

requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspendInfo

后台应用申请延迟挂起。

Z
zhangxin_T 已提交
31
延迟挂起时间一般情况下默认值为180000毫秒,低电量(依据系统低电量广播)时默认值为60000毫秒。
廖康康 已提交
32

bugfix  
朱天怡 已提交
33
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.requestSuspendDelay](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerrequestsuspenddelay9)
修改  
朱天怡 已提交
34 35
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
36

Z
zhangxin_T 已提交
37 38
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Z
zhangxin_T 已提交
39
**参数**
H
HelloCrease 已提交
40 41 42 43
| 参数名      | 类型                   | 必填   | 说明                             |
| -------- | -------------------- | ---- | ------------------------------ |
| reason   | string               | 是    | 延迟挂起申请的原因。                     |
| callback | Callback&lt;void&gt; | 是    | 延迟即将超时的回调函数,一般在超时前6秒通过此回调通知应用。 |
廖康康 已提交
44

Z
zhangxin_T 已提交
45
**返回值**
H
HelloCrease 已提交
46 47 48
| 类型                                    | 说明        |
| ------------------------------------- | --------- |
| [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 |
廖康康 已提交
49

Z
zhangxin_T 已提交
50
**示例**
W
wangqing 已提交
51

Z
zhangxin_T 已提交
52
  ```js
修改  
朱天怡 已提交
53
  import backgroundTaskManager from '@ohos.backgroundTaskManager';
修改  
朱天怡 已提交
54

廖康康 已提交
55
  let myReason = 'test requestSuspendDelay';
修改  
朱天怡 已提交
56 57 58
  let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
      console.info("Request suspension delay will time out.");
  })
Z
zhangxin_T 已提交
59 60 61

  let id = delayInfo.requestId;
  let time = delayInfo.actualDelayTime;
修改  
朱天怡 已提交
62 63
  console.info("The requestId is: " + id);
  console.info("The actualDelayTime is: " + time);
廖康康 已提交
64 65 66
  ```


修改  
朱天怡 已提交
67
## backgroundTaskManager.getRemainingDelayTime<sup>7+(deprecated)</sup>
廖康康 已提交
68 69 70 71 72

getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void

获取应用程序进入挂起状态前的剩余时间,使用callback形式返回。

bugfix  
朱天怡 已提交
73
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.getRemainingDelayTime](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagergetremainingdelaytimecallback9)
修改  
朱天怡 已提交
74 75
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
76

Z
zhangxin_T 已提交
77 78
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Z
zhangxin_T 已提交
79
**参数**
H
HelloCrease 已提交
80 81
| 参数名       | 类型                          | 必填   | 说明                                       |
| --------- | --------------------------- | ---- | ---------------------------------------- |
Z
zhangxin_T 已提交
82
| requestId | number                      | 是    | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 |
H
HelloCrease 已提交
83
| callback  | AsyncCallback&lt;number&gt; | 是    | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 |
廖康康 已提交
84

Z
zhangxin_T 已提交
85
**示例**
W
wangqing 已提交
86

Z
zhangxin_T 已提交
87
  ```js
修改  
朱天怡 已提交
88
  import backgroundTaskManager from '@ohos.backgroundTaskManager';
修改  
朱天怡 已提交
89

Z
zhangxin_T 已提交
90 91
  let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {});
  backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId, (err, res) => {
修改  
朱天怡 已提交
92 93 94 95 96 97
      if(err) {
          console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code);
      } else {
          console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
      }
  })
廖康康 已提交
98 99 100
  ```


修改  
朱天怡 已提交
101
## backgroundTaskManager.getRemainingDelayTime<sup>7+(deprecated)</sup>
廖康康 已提交
102 103 104 105 106

getRemainingDelayTime(requestId: number): Promise&lt;number&gt;

获取应用程序进入挂起状态前的剩余时间,使用Promise形式返回。

bugfix  
朱天怡 已提交
107
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.getRemainingDelayTime](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagergetremainingdelaytimepromise9)
修改  
朱天怡 已提交
108 109
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
110

Z
zhangxin_T 已提交
111 112
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Z
zhangxin_T 已提交
113
**参数**
H
HelloCrease 已提交
114 115
| 参数名       | 类型     | 必填   | 说明         |
| --------- | ------ | ---- | ---------- |
Z
zhangxin_T 已提交
116
| requestId | number | 是    | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 |
廖康康 已提交
117

Z
zhangxin_T 已提交
118
**返回值**
H
HelloCrease 已提交
119 120 121
| 类型                    | 说明                                       |
| --------------------- | ---------------------------------------- |
| Promise&lt;number&gt; | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 |
廖康康 已提交
122

Z
zhangxin_T 已提交
123 124
**示例**
  ```js
Z
zhangxin_T 已提交
125 126
  let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {});
  backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId).then( res => {
修改  
朱天怡 已提交
127 128 129 130
      console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
  }).catch( err => {
      console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
  })
廖康康 已提交
131 132 133
  ```


修改  
朱天怡 已提交
134
## backgroundTaskManager.cancelSuspendDelay<sup>7+(deprecated)</sup>
廖康康 已提交
135 136 137 138 139

cancelSuspendDelay(requestId: number): void

取消延迟挂起。

bugfix  
朱天怡 已提交
140
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.cancelSuspendDelay](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagercancelsuspenddelay9)
修改  
朱天怡 已提交
141 142
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
143

Z
zhangxin_T 已提交
144 145
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Z
zhangxin_T 已提交
146
**参数**
H
HelloCrease 已提交
147 148
| 参数名       | 类型     | 必填   | 说明         |
| --------- | ------ | ---- | ---------- |
Z
zhangxin_T 已提交
149
| requestId | number | 是    | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 |
廖康康 已提交
150

Z
zhangxin_T 已提交
151 152
**示例**
  ```js
Z
zhangxin_T 已提交
153 154
  let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {});
  backgroundTaskManager.cancelSuspendDelay(delayInfo.requestId);
廖康康 已提交
155 156 157
  ```


修改  
朱天怡 已提交
158
## backgroundTaskManager.startBackgroundRunning<sup>8+(deprecated)</sup>
廖康康 已提交
159

Z
zhangxin_T 已提交
160
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
Z
zhangxin_T 已提交
161 162 163

向系统申请长时任务,使用callback形式返回结果。

bugfix  
朱天怡 已提交
164
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.startBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstartbackgroundrunningcallback9)
修改  
朱天怡 已提交
165 166
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
167

Z
zhangxin_T 已提交
168 169
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING

Z
zhangxin_T 已提交
170 171
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Z
zhangxin_T 已提交
172
**参数**
H
HelloCrease 已提交
173 174 175 176 177 178
| 参数名       | 类型                                 | 必填   | 说明                                       |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context   | Context                            | 是    | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| bgMode    | [BackgroundMode](#backgroundmode8) | 是    | 向系统申请的后台模式。                              |
| wantAgent | [WantAgent](js-apis-wantAgent.md)  | 是    | 通知参数,用于指定长时任务通知点击后跳转的界面。                 |
| callback  | AsyncCallback&lt;void&gt;          | 是    | callback形式返回启动长时任务的结果。                   |
Z
zhangxin_T 已提交
179

Z
zhangxin_T 已提交
180
**示例**
Z
zhangxin_T 已提交
181 182 183

FA模型示例:

Z
zhangxin_T 已提交
184
```js
修改  
朱天怡 已提交
185
import backgroundTaskManager from '@ohos.backgroundTaskManager';
Z
zhangxin_T 已提交
186 187 188
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';

修改  
朱天怡 已提交
189 190 191
function callback(err, data) {
    if (err) {
        console.error("Operation startBackgroundRunning failed Cause: " + err);
Z
zhangxin_T 已提交
192
    } else {
W
wangqing 已提交
193
        console.info("Operation startBackgroundRunning succeeded");
Z
zhangxin_T 已提交
194 195 196 197 198 199 200 201 202 203 204 205
    }
}

let wantAgentInfo = {
    wants: [
        {
            bundleName: "com.example.myapplication",
            abilityName: "com.example.myapplication.MainAbility"
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
W
wangqing 已提交
206
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
Z
zhangxin_T 已提交
207 208 209
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
修改  
朱天怡 已提交
210
    backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
Z
zhangxin_T 已提交
211
        backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
Z
zhangxin_T 已提交
212 213 214 215
});

```

Z
zhangxin_T 已提交
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
Stage模型示例:

```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';

function callback(err, data) {
    if (err) {
        console.error("Operation startBackgroundRunning failed Cause: " + err);
    } else {
        console.info("Operation startBackgroundRunning succeeded");
    }
}

export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        let wantAgentInfo = {
            wants: [
                {
                    bundleName: "com.example.myapplication",
                    abilityName: "com.example.myapplication.MainAbility"
                }
            ],
            operationType: wantAgent.OperationType.START_ABILITY,
            requestCode: 0,
            wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
        };

        wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
            backgroundTaskManager.startBackgroundRunning(this.context,
                backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
        });
    }
};
```

修改  
朱天怡 已提交
253
## backgroundTaskManager.startBackgroundRunning<sup>8+(deprecated)</sup>
Z
zhangxin_T 已提交
254

Z
zhangxin_T 已提交
255
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
Z
zhangxin_T 已提交
256 257 258

向系统申请长时任务,使用promise形式返回结果。

bugfix  
朱天怡 已提交
259
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.startBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstartbackgroundrunningpromise9)
修改  
朱天怡 已提交
260 261
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
262

Z
zhangxin_T 已提交
263 264
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING

Z
zhangxin_T 已提交
265 266
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Z
zhangxin_T 已提交
267
**参数**
W
wangqing 已提交
268

H
HelloCrease 已提交
269 270 271 272 273
| 参数名       | 类型                                 | 必填   | 说明                                       |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context   | Context                            | 是    | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| bgMode    | [BackgroundMode](#backgroundmode8) | 是    | 向系统申请的后台模式。                              |
| wantAgent | [WantAgent](js-apis-wantAgent.md)  | 是    | 通知参数,用于指定长时任务通知点击跳转的界面。                  |
W
wangqing 已提交
274

275
**返回值**
H
HelloCrease 已提交
276 277 278
| 类型             | 说明               |
| -------------- | ---------------- |
| Promise\<void> | 使用Promise形式返回结果。 |
Z
zhangxin_T 已提交
279

Z
zhangxin_T 已提交
280
**示例**
Z
zhangxin_T 已提交
281 282 283

FA模型示例:

Z
zhangxin_T 已提交
284
```js
修改  
朱天怡 已提交
285
import backgroundTaskManager from '@ohos.backgroundTaskManager';
Z
zhangxin_T 已提交
286 287 288 289 290 291 292 293 294 295 296 297
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';

let wantAgentInfo = {
    wants: [
        {
            bundleName: "com.example.myapplication",
            abilityName: "com.example.myapplication.MainAbility"
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
W
wangqing 已提交
298
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
Z
zhangxin_T 已提交
299 300 301
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
修改  
朱天怡 已提交
302
    backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
Z
zhangxin_T 已提交
303
        backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
修改  
朱天怡 已提交
304 305 306 307
        console.info("Operation startBackgroundRunning succeeded");
    }).catch((err) => {
        console.error("Operation startBackgroundRunning failed Cause: " + err);
    });
Z
zhangxin_T 已提交
308
});
Z
zhangxin_T 已提交
309 310 311 312 313 314 315 316
```

Stage模型示例:

```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
Z
zhangxin_T 已提交
317

Z
zhangxin_T 已提交
318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        let wantAgentInfo = {
            wants: [
                {
                    bundleName: "com.example.myapplication",
                    abilityName: "com.example.myapplication.MainAbility"
                }
            ],
            operationType: wantAgent.OperationType.START_ABILITY,
            requestCode: 0,
            wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
        };

        wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
            backgroundTaskManager.startBackgroundRunning(this.context,
                backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
                console.info("Operation startBackgroundRunning succeeded");
            }).catch((err) => {
                console.error("Operation startBackgroundRunning failed Cause: " + err);
            });
        });
    }
};
Z
zhangxin_T 已提交
342 343
```

修改  
朱天怡 已提交
344
## backgroundTaskManager.stopBackgroundRunning<sup>8+(deprecated)</sup>
Z
zhangxin_T 已提交
345

Z
zhangxin_T 已提交
346
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
Z
zhangxin_T 已提交
347 348 349

向系统申请取消长时任务,使用callback形式返回结果。

bugfix  
朱天怡 已提交
350
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.stopBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstopbackgroundrunningcallback9)
修改  
朱天怡 已提交
351 352
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
353

Z
zhangxin_T 已提交
354 355
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Z
zhangxin_T 已提交
356
**参数**
H
HelloCrease 已提交
357 358 359 360
| 参数名      | 类型                        | 必填   | 说明                                       |
| -------- | ------------------------- | ---- | ---------------------------------------- |
| context  | Context                   | 是    | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| callback | AsyncCallback&lt;void&gt; | 是    | callback形式返回启动长时任务的结果。                   |
Z
zhangxin_T 已提交
361

Z
zhangxin_T 已提交
362
**示例**
Z
zhangxin_T 已提交
363 364 365

FA模型示例:

Z
zhangxin_T 已提交
366
```js
修改  
朱天怡 已提交
367
import backgroundTaskManager from '@ohos.backgroundTaskManager';
Z
zhangxin_T 已提交
368 369
import featureAbility from '@ohos.ability.featureAbility';

修改  
朱天怡 已提交
370 371 372
function callback(err, data) {
    if (err) {
        console.error("Operation stopBackgroundRunning failed Cause: " + err);
Z
zhangxin_T 已提交
373
    } else {
W
wangqing 已提交
374
        console.info("Operation stopBackgroundRunning succeeded");
Z
zhangxin_T 已提交
375 376 377
    }
}

修改  
朱天怡 已提交
378
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);
Z
zhangxin_T 已提交
379 380 381

```

Z
zhangxin_T 已提交
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402
Stage模型示例:

```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';

function callback(err, data) {
    if (err) {
        console.error("Operation stopBackgroundRunning failed Cause: " + err);
    } else {
        console.info("Operation stopBackgroundRunning succeeded");
    }
}

export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        backgroundTaskManager.stopBackgroundRunning(this.context, callback);
    }
};
```

修改  
朱天怡 已提交
403
## backgroundTaskManager.stopBackgroundRunning<sup>8+(deprecated)</sup>
Z
zhangxin_T 已提交
404

Z
zhangxin_T 已提交
405
stopBackgroundRunning(context: Context): Promise&lt;void&gt;
Z
zhangxin_T 已提交
406 407 408

向系统申请取消长时任务,使用promise形式返回结果。

bugfix  
朱天怡 已提交
409
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.stopBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstopbackgroundrunningpromise9)
修改  
朱天怡 已提交
410 411
>
> 从 API version 7开始支持。
修改  
朱天怡 已提交
412

Z
zhangxin_T 已提交
413 414
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Z
zhangxin_T 已提交
415
**参数**
H
HelloCrease 已提交
416 417
| 参数名     | 类型      | 必填   | 说明                                       |
| ------- | ------- | ---- | ---------------------------------------- |
Z
zhangxin_T 已提交
418
| context | Context | 是    | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
Z
zhangxin_T 已提交
419

420
**返回值**
H
HelloCrease 已提交
421 422 423
| 类型             | 说明               |
| -------------- | ---------------- |
| Promise\<void> | 使用Promise形式返回结果。 |
Z
zhangxin_T 已提交
424

Z
zhangxin_T 已提交
425
**示例**
Z
zhangxin_T 已提交
426 427 428

FA模型示例:

Z
zhangxin_T 已提交
429
```js
修改  
朱天怡 已提交
430
import backgroundTaskManager from '@ohos.backgroundTaskManager';
Z
zhangxin_T 已提交
431 432
import featureAbility from '@ohos.ability.featureAbility';

修改  
朱天怡 已提交
433 434 435 436 437
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
    console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
    console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
Z
zhangxin_T 已提交
438 439 440

```

Z
zhangxin_T 已提交
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457
Stage模型示例:

```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';

export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
            console.info("Operation stopBackgroundRunning succeeded");
        }).catch((err) => {
            console.error("Operation stopBackgroundRunning failed Cause: " + err);
        });
    }
};
```

修改  
朱天怡 已提交
458
## backgroundTaskManager.applyEfficiencyResources<sup>9+(deprecated)</sup>
Z
Zhao-PengFei35 已提交
459

修改  
朱天怡 已提交
460
applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): void
Z
Zhao-PengFei35 已提交
461

Z
zhangxin_T 已提交
462
向系统申请或释放能效资源,使用boolean形式返回结果。
Z
zhangxin_T 已提交
463 464
通过EfficiencyResourcesRequest参数中的isApply变量,设置是申请还是释放。
应用使用此接口,需要向应用中心申请获得相应特权。
465
进程和它所属的应用可以同时申请某一类资源,例如CPU资源,但是应用释放资源的时候会将进程的资源一起释放。
Z
Zhao-PengFei35 已提交
466

bugfix  
朱天怡 已提交
467
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.applyEfficiencyResources](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerapplyefficiencyresources9)
修改  
朱天怡 已提交
468
>
修改  
朱天怡 已提交
469 470
> 从 API version 9开始支持。

471
**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
472

473
**系统API**: 此接口为系统接口。
Z
Zhao-PengFei35 已提交
474 475

**参数**
476

Z
Zhao-PengFei35 已提交
477 478
| 参数名     | 类型      | 必填   | 说明                                       |
| ------- | ------- | ---- | ---------------------------------------- |
479
| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是    | 请求的必要信息。包括资源类型,超时时间等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 |
Z
Zhao-PengFei35 已提交
480 481

**示例**
482

Z
Zhao-PengFei35 已提交
483
```js
修改  
朱天怡 已提交
484
import backgroundTaskManager from '@ohos.backgroundTaskManager';  
Z
Zhao-PengFei35 已提交
485 486 487

let request = {
    resourceTypes: backgroundTaskManager.ResourceType.CPU,
Z
zhangxin_T 已提交
488
    // 如果将isApply置为false,则表示释放资源
Z
Zhao-PengFei35 已提交
489 490 491 492 493 494
    isApply: true,
    timeOut: 0,
    reason: "apply",
    isPersist: true,
    isProcess: false,
};
修改  
朱天怡 已提交
495 496 497 498 499 500
try {
    backgroundTaskManager.applyEfficiencyResources(request);
    console.info("applyEfficiencyResources success. ");
} catch (error) {
    console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
Z
Zhao-PengFei35 已提交
501 502
```

修改  
朱天怡 已提交
503
## backgroundTaskManager.resetAllEfficiencyResources<sup>9+(deprecated)</sup>
Z
Zhao-PengFei35 已提交
504 505 506

resetAllEfficiencyResources(): void

507
释放所有已经申请的资源。
Z
zhangxin_T 已提交
508
应用使用此接口,需要向应用中心申请获得相应特权。
Z
Zhao-PengFei35 已提交
509

bugfix  
朱天怡 已提交
510
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.resetAllEfficiencyResources](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerresetallefficiencyresources9)
修改  
朱天怡 已提交
511
>
修改  
朱天怡 已提交
512 513
> 从 API version 9开始支持。

Z
Zhao-PengFei35 已提交
514
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
515

516
**系统API**: 此接口为系统接口。
Z
Zhao-PengFei35 已提交
517 518

**示例**
519

Z
Zhao-PengFei35 已提交
520
```js
修改  
朱天怡 已提交
521
import backgroundTaskManager from '@ohos.backgroundTaskManager';  
Z
Zhao-PengFei35 已提交
522

修改  
朱天怡 已提交
523 524 525 526 527
try {
    backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) {
    console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
Z
Zhao-PengFei35 已提交
528 529
```

修改  
朱天怡 已提交
530
## DelaySuspendInfo<sup>7+(deprecated)</sup>
Z
zhangxin_T 已提交
531 532 533

延迟挂起信息。

bugfix  
朱天怡 已提交
534
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.DelaySuspendInfo](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerdelaysuspendinfo9)
修改  
朱天怡 已提交
535 536 537
>
> 从 API version 7开始支持。

H
HelloCrease 已提交
538
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
Z
zhangxin_T 已提交
539

H
HelloCrease 已提交
540 541 542 543
| 参数名             | 类型     | 必填   | 说明                                       |
| --------------- | ------ | ---- | ---------------------------------------- |
| requestId       | number | 是    | 延迟挂起的请求ID。                               |
| actualDelayTime | number | 是    | 应用的实际挂起延迟时间,以毫秒为单位。<br/>一般情况下默认值为180000,低电量(依据系统低电量广播)时默认值为60000。 |
Z
zhangxin_T 已提交
544 545


修改  
朱天怡 已提交
546
## BackgroundMode<sup>8+(deprecated)</sup>
Z
zhangxin_T 已提交
547

H
HelloCrease 已提交
548 549 550 551
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

| 参数名                     | 参数值  | 描述                    |
| ----------------------- | ---- | --------------------- |
552 553 554 555 556 557
| DATA_TRANSFER           | 1    | 数据传输。                  |
| AUDIO_PLAYBACK          | 2    | 音频播放。                  |
| AUDIO_RECORDING         | 3    | 录音。                    |
| LOCATION                | 4    | 定位导航。                  |
| BLUETOOTH_INTERACTION   | 5    | 蓝牙相关。                  |
| MULTI_DEVICE_CONNECTION | 6    | 多设备互联。                 |
H
HelloCrease 已提交
558 559
| WIFI_INTERACTION        | 7    | WLAN相关<br />此接口为系统接口。 |
| VOIP                    | 8    | 音视频通话<br />此接口为系统接口。  |
560
| TASK_KEEPING            | 9    | 计算任务(仅在特定设备生效)。        |
Z
Zhao-PengFei35 已提交
561

修改  
朱天怡 已提交
562
## EfficiencyResourcesRequest<sup>9+(deprecated)</sup>
Z
Zhao-PengFei35 已提交
563

564
能效资源申请参数。
Z
Zhao-PengFei35 已提交
565

bugfix  
朱天怡 已提交
566
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.EfficiencyResourcesRequest](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerefficiencyresourcesrequest9)
修改  
朱天怡 已提交
567 568 569
>
> 从 API version 9开始支持。

Z
Zhao-PengFei35 已提交
570 571
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

572 573
**系统API**: 此接口为系统接口。

Z
Zhao-PengFei35 已提交
574 575 576 577
| 参数名             | 类型     | 必填   | 说明                                       |
| --------------- | ------ | ---- | ---------------------------------------- |
| resourceTypes   | number  | 是    | 申请的资源类型。                               |
| isApply         | boolean | 是    | 申请资源或者是释放资源。          |
578
| timeOut         | number  | 是    | 资源的使用时间,以毫秒为单位。                |
Z
Zhao-PengFei35 已提交
579 580 581 582
| isPersist       | boolean | 否    | 是否永久持有资源,如果是true,那么timeOut就无效。    |
| isProcess       | boolean | 否    | 应用申请或者是进程申请。          |
| reason          | string  | 是    | 申请资源的原因。                |

修改  
朱天怡 已提交
583
## ResourceType<sup>9+(deprecated)</sup>
Z
Zhao-PengFei35 已提交
584

585 586
能效资源类型。

bugfix  
朱天怡 已提交
587
> **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.ResourceType](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerresourcetype9)
修改  
朱天怡 已提交
588 589 590
>
> 从 API version 9开始支持。

Z
Zhao-PengFei35 已提交
591 592
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

593 594
**系统API**: 此接口为系统接口。

Z
Zhao-PengFei35 已提交
595 596
| 参数名                     | 参数值  | 描述                    |
| ----------------------- | ---- | --------------------- |
597 598 599 600 601 602
| CPU                     | 1    | CPU资源,申请后不被挂起。             |
| COMMON_EVENT            | 2    | 公共事件,申请后挂起状态下不被代理掉。  |
| TIMER                   | 4    | 计时器,申请后挂起状态下不被代理掉。    |
| WORK_SCHEDULER          | 8    | 延迟任务,申请后有更长的执行时间。      |
| BLUETOOTH               | 16   | 蓝牙相关,申请后挂起状态下不被代理掉。  |
| GPS                     | 32   | GPS相关,申请后挂起状态下不被代理掉。  |
修改  
朱天怡 已提交
603
| AUDIO                   | 64   | 音频资源,申请后挂起状态下不被代理掉。 |