提交 fb306202 编写于 作者: Z zhangxin_T

modify doc

Signed-off-by: Nzhangxin_T <zhangxin312@huawei.com>
上级 720f46ab
# 后台任务概述 # 后台任务概述
对于有用户交互的OS来说,资源优先分配给与用户交互的业务进程,换句话说,在支撑OS运行的进程以外,用户能感知到的业务进程优先级最高,所以后台任务管理的范围是用户感知不到的业务进程 后台应用频繁活动,会造成用户设备耗电快、卡顿等现象。因此,为了支撑性能、功耗诉求,系统仅允许应用在后台执行规范内的活动,规范外的活动默认会被挂起,当资源不足时会被回收
## 后台任务类型 ## 后台任务类型
...@@ -11,7 +11,7 @@ ...@@ -11,7 +11,7 @@
2. 短时任务:退后台后,如果有紧急不可推迟且短时间能完成的任务,如应用退后台要进行数据压缩,不可中断,则使用短时任务申请延迟进入挂起(Suspend)状态。 2. 短时任务:退后台后,如果有紧急不可推迟且短时间能完成的任务,如应用退后台要进行数据压缩,不可中断,则使用短时任务申请延迟进入挂起(Suspend)状态。
3. 长时任务:如果是用户发起的可感知业务需要长时间后台运行的,如后台播放音乐、导航、上传下载、设备连接、VoIP等,则使用长时任务避免进入挂起(Suspend)状态。 3. 长时任务:如果是用户发起的可感知业务需要长时间后台运行的,如后台播放音乐、导航、设备连接、VoIP等,则使用长时任务避免进入挂起(Suspend)状态。
## 短时任务 ## 短时任务
...@@ -55,7 +55,7 @@ OpenHarmony提供了九种后台模式,供需要在后台做长时任务的业 ...@@ -55,7 +55,7 @@ OpenHarmony提供了九种后台模式,供需要在后台做长时任务的业
| taskKeeping | 计算任务 | 正在运行计算任务 | PC特有,仅在PC申请生效 | | taskKeeping | 计算任务 | 正在运行计算任务 | PC特有,仅在PC申请生效 |
### 长时任务使用约束 ### 长时任务使用约束
- 如果用户选择可感知业务(如播音、导航、上传下载等),触发对应后台模式,在任务启动时,系统会强制弹出通知提醒用户。 - 如果用户选择可感知业务(如播音、导航等),触发对应后台模式,在任务启动时,系统会强制弹出通知提醒用户。
- 如果任务结束,应用应主动退出后台模式。若在后台运行期间,系统检测到应用并未使用对应后台模式的资源,则会被挂起(Suspend)。 - 如果任务结束,应用应主动退出后台模式。若在后台运行期间,系统检测到应用并未使用对应后台模式的资源,则会被挂起(Suspend)。
- 避免不合理地申请后台长时任务,长时任务类型要与应用的业务类型匹配。如果执行的任务和申请的类型不匹配,也会被系统检测到并被挂起(Suspend)。 - 避免不合理地申请后台长时任务,长时任务类型要与应用的业务类型匹配。如果执行的任务和申请的类型不匹配,也会被系统检测到并被挂起(Suspend)。
- 长时任务是为了真正在后台长时间执行某个任务,如果一个应用申请了长时任务,但在实际运行过程中,并未真正运行或执行此类任务时,也会被系统检测到并被挂起(Suspend)。 - 长时任务是为了真正在后台长时间执行某个任务,如果一个应用申请了长时任务,但在实际运行过程中,并未真正运行或执行此类任务时,也会被系统检测到并被挂起(Suspend)。
......
...@@ -10,12 +10,6 @@ ...@@ -10,12 +10,6 @@
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
``` ```
## 权限列表
长时任务需要申请如下权限:
ohos.permission.KEEP_BACKGROUND_RUNNING
## backgroundTaskManager.requestSuspendDelay ## backgroundTaskManager.requestSuspendDelay
...@@ -27,19 +21,19 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen ...@@ -27,19 +21,19 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| reason | string | 是 | 延迟挂起申请的原因。 | | reason | string | 是 | 延迟挂起申请的原因。 |
| callback | Callback&lt;void&gt; | 是 | 延迟即将超时的回调函数,一般在超时前6秒通过此回调通知应用。 | | callback | Callback&lt;void&gt; | 是 | 延迟即将超时的回调函数,一般在超时前6秒通过此回调通知应用。 |
- **返回值** **返回值**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | -------- | -------- |
| [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | | [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 |
- **示例** **示例**
``` ```js
let myReason = 'test requestSuspendDelay'; let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out."); console.info("Request suspension delay will time out.");
...@@ -55,14 +49,14 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): ...@@ -55,14 +49,14 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;):
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 | | requestId | number | 是 | 延迟挂起的请求ID。 |
| callback | AsyncCallback&lt;number&gt; | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 | | callback | AsyncCallback&lt;number&gt; | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 |
- **示例** **示例**
``` ```js
let id = 1; let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
if(err.data === 0) { if(err.data === 0) {
...@@ -82,18 +76,18 @@ getRemainingDelayTime(requestId: number): Promise&lt;number&gt; ...@@ -82,18 +76,18 @@ getRemainingDelayTime(requestId: number): Promise&lt;number&gt;
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 | | requestId | number | 是 | 延迟挂起的请求ID。 |
- **返回值** **返回值**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | -------- | -------- |
| Promise&lt;number&gt; | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 | | Promise&lt;number&gt; | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 |
- **示例** **示例**
``` ```js
let id = 1; let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then( res => { backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res));
...@@ -111,45 +105,36 @@ cancelSuspendDelay(requestId: number): void ...@@ -111,45 +105,36 @@ cancelSuspendDelay(requestId: number): void
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 | | requestId | number | 是 | 延迟挂起的请求ID。 |
- **示例** **示例**
``` ```js
backgroundTaskManager.cancelSuspendDelay(id); backgroundTaskManager.cancelSuspendDelay(id);
``` ```
#### DelaySuspendInfo ## backgroundTaskManager.startBackgroundRunning <sup>8+</sup>
延迟挂起信息。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| actualDelayTime | number | 是 | 应用的实际挂起延迟时间,以毫秒为单位。<br/>一般情况下默认值为180000,低电量(依据系统低电量广播)时默认值为60000。 |
## backgroundTaskManager.startBackgroundRunning startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void; <sup>8+</sup>
向系统申请长时任务,使用callback形式返回结果。 向系统申请长时任务,使用callback形式返回结果。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| context | Context | 是 | 应用运行的上下文 | | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 |
| bgMode | BackgroundMode | 是 | 向系统申请的后台模式 | | bgMode | [BackgroundMode](#BackgroundMode<sup>8+</sup>) | 是 | 向系统申请的后台模式 |
| wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数,用于指定长时任务通知点击后跳转的界面。 | | wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数,用于指定长时任务通知点击后跳转的界面。 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果 | | callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果 |
- **示例** **示例**
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -182,28 +167,30 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { ...@@ -182,28 +167,30 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
``` ```
## backgroundTaskManager.startBackgroundRunning ## backgroundTaskManager.startBackgroundRunning <sup>8+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;; <sup>8+</sup> startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
向系统申请长时任务,使用promise形式返回结果。 向系统申请长时任务,使用promise形式返回结果。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| context | Context | 是 | 应用运行的上下文 | | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 |
| bgMode | BackgroundMode | 是 | 向系统申请的后台模式 | | bgMode | [BackgroundMode](#BackgroundMode<sup>8+</sup>) | 是 | 向系统申请的后台模式 |
| wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数,用于指定长时任务通知点击跳转的界面 | | wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数,用于指定长时任务通知点击跳转的界面 |
- **返回值** **返回值**
| 类型 | 说明 | | 类型 | 说明 |
| -------------- | ------------------------- | | -------------- | ------------------------- |
| Promise\<void> | 使用Promise形式返回结果。 | | Promise\<void> | 使用Promise形式返回结果。 |
- **示例** **示例**
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -232,21 +219,23 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { ...@@ -232,21 +219,23 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
``` ```
## backgroundTaskManager.stopBackgroundRunning ## backgroundTaskManager.stopBackgroundRunning <sup>8+</sup>
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void; <sup>8+</sup> stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
向系统申请取消长时任务,使用callback形式返回结果。 向系统申请取消长时任务,使用callback形式返回结果。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| context | Context | 是 | 应用运行的上下文 | | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果 | | callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果 |
- **示例** **示例**
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -263,25 +252,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac ...@@ -263,25 +252,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac
``` ```
## backgroundTaskManager.stopBackgroundRunning ## backgroundTaskManager.stopBackgroundRunning <sup>8+</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt;; <sup>8+</sup> stopBackgroundRunning(context: Context): Promise&lt;void&gt;
向系统申请取消长时任务,使用promise形式返回结果。 向系统申请取消长时任务,使用promise形式返回结果。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **参数** **参数**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| context | Context | 是 | 应用运行的上下文 | | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 |
- **返回值** **返回值**
| 类型 | 说明 | | 类型 | 说明 |
| -------------- | ------------------------- | | -------------- | ------------------------- |
| Promise\<void> | 使用Promise形式返回结果。 | | Promise\<void> | 使用Promise形式返回结果。 |
- **示例** **示例**
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -294,7 +285,19 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() ...@@ -294,7 +285,19 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(()
``` ```
## BackgroundMode <sup>8+</sup> ## DelaySuspendInfo
延迟挂起信息。
**系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| actualDelayTime | number | 是 | 应用的实际挂起延迟时间,以毫秒为单位。<br/>一般情况下默认值为180000,低电量(依据系统低电量广播)时默认值为60000。 |
## BackgroundMode<sup>8+</sup>
**系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册