后臺任務(wù)管理

本模塊提供后臺任務(wù)管理能力。

當(dāng)應(yīng)用或業(yè)務(wù)模塊處于后臺（無可見界面）時(shí)，如果有需要繼續(xù)執(zhí)行或者后續(xù)執(zhí)行的業(yè)務(wù)，可基于業(yè)務(wù)類型，申請短時(shí)任務(wù)延遲掛起（Suspend）或者長時(shí)任務(wù)避免進(jìn)入掛起狀態(tài)。

應(yīng)用有不可中斷且短時(shí)間能完成的任務(wù)時(shí)（如，用戶在文件管理器上點(diǎn)擊垃圾文件清理，若清理未完成時(shí)退到后臺，文件管理器需要申請短時(shí)任務(wù)完成清理），可以使用短時(shí)任務(wù)機(jī)制。

應(yīng)用中存在用戶能夠直觀感受到的且需要一直在后臺運(yùn)行的業(yè)務(wù)時(shí)（如，后臺播放音樂），可以使用長時(shí)任務(wù)機(jī)制。

說明： 本模塊首批接口從API version 7開始支持。后續(xù)版本的新增接口，采用上角標(biāo)單獨(dú)標(biāo)記接口的起始版本。 開發(fā)前請熟悉鴻蒙開發(fā)指導(dǎo)文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

導(dǎo)入模塊

import backgroundTaskManager from '@ohos.backgroundTaskManager';

backgroundTaskManager.requestSuspendDelay

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

后臺應(yīng)用申請延遲掛起。

延遲掛起時(shí)間一般情況下默認(rèn)值為180000，低電量（依據(jù)系統(tǒng)低電量廣播）時(shí)默認(rèn)值為60000。

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

參數(shù) ：

返回值 ：

示例 ：

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

獲取應(yīng)用程序進(jìn)入掛起狀態(tài)前的剩余時(shí)間，使用callback形式返回。

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

參數(shù) ：

示例 ：

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

獲取應(yīng)用程序進(jìn)入掛起狀態(tài)前的剩余時(shí)間，使用Promise形式返回。

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

參數(shù) ：

返回值 ：

示例 ：

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

取消延遲掛起。

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

參數(shù) ：

示例 ：

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

backgroundTaskManager.startBackgroundRunning8+

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

向系統(tǒng)申請長時(shí)任務(wù)，使用callback形式返回結(jié)果。

需要權(quán)限: ohos.permission.KEEP_BACKGROUND_RUNNING

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

參數(shù) ：

示例 ：

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

向系統(tǒng)申請長時(shí)任務(wù)，使用promise形式返回結(jié)果。

需要權(quán)限: ohos.permission.KEEP_BACKGROUND_RUNNING

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

參數(shù) ：

返回值

示例 ：

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

向系統(tǒng)申請取消長時(shí)任務(wù)，使用callback形式返回結(jié)果。

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

參數(shù) ：

示例 ：

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

向系統(tǒng)申請取消長時(shí)任務(wù)，使用promise形式返回結(jié)果。

系統(tǒng)能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

參數(shù) ：

返回值

示例 ：

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

延遲掛起信息。

系統(tǒng)能力: 以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

BackgroundMode8+

系統(tǒng)能力: 以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

審核編輯 黃宇