后臺任務管理

本模塊提供后臺任務管理能力。

當應用或業務模塊處于后臺（無可見界面）時，如果有需要繼續執行或者后續執行的業務，可基于業務類型，申請短時任務延遲掛起（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

審核編輯 黃宇