后台任务管理

本模块提供后台任务管理能力。

当应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。

应用有不可中断且短时间能完成的任务时（如，用户在文件管理器上点击垃圾文件清理，若清理未完成时退到后台，文件管理器需要申请短时任务完成清理），可以使用短时任务机制。

应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。

说明： 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 开发前请熟悉鸿蒙开发指导文档 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

导入模块

import backgroundTaskManager from '@ohos.backgroundTaskManager';

backgroundTaskManager.requestSuspendDelay

requestSuspendDelay(reason: string, callback: Callback): DelaySuspendInfo

后台应用申请延迟挂起。

延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数 ：

返回值 ：

示例 ：

let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () = > {
    console.info("Request suspension delay will time out.");
})

var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);

backgroundTaskManager.getRemainingDelayTime

getRemainingDelayTime(requestId: number, callback: AsyncCallback): void

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

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数 ：

示例 ：

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (err, res) = > {
    if(err) {
        console.log('callback = > Operation getRemainingDelayTime failed. Cause: ' + err.code);
    } else {
        console.log('callback = > Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
    }
})

backgroundTaskManager.getRemainingDelayTime

getRemainingDelayTime(requestId: number): Promise

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

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数 ：

返回值 ：

示例 ：

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then( res = > {
    console.log('promise = > Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err = > {
    console.log('promise = > Operation getRemainingDelayTime failed. Cause: ' + err.code);
})

backgroundTaskManager.cancelSuspendDelay

cancelSuspendDelay(requestId: number): void

取消延迟挂起。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数 ：

示例 ：

let id = 1;
backgroundTaskManager.cancelSuspendDelay(id);

backgroundTaskManager.startBackgroundRunning8+

startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback): void

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

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数 ：

示例 ：

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';

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

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(featureAbility.getContext(),
        backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback)
});

backgroundTaskManager.startBackgroundRunning8+

startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise

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

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数 ：

返回值

示例 ：

import backgroundTaskManager from '@ohos.backgroundTaskManager';
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,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) = > {
    backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
        backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() = > {
        console.info("Operation startBackgroundRunning succeeded");
    }).catch((err) = > {
        console.error("Operation startBackgroundRunning failed Cause: " + err);
    });
});

backgroundTaskManager.stopBackgroundRunning8+

stopBackgroundRunning(context: Context, callback: AsyncCallback): void

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

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数 ：

示例 ：

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';

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

backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);

backgroundTaskManager.stopBackgroundRunning8+

stopBackgroundRunning(context: Context): Promise

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

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数 ：

返回值

示例 ：

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';

backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() = > {
    console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) = > {
    console.error("Operation stopBackgroundRunning failed Cause: " + err);
});

DelaySuspendInfo

延迟挂起信息。

系统能力: 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

BackgroundMode8+

系统能力: 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

审核编辑 黄宇