# 后台任务管理 本模块提供后台任务管理能力。 当应用或业务模块处于后台(无可见界面)时,如果有需要继续执行或者后续执行的业务,可基于业务类型,申请短时任务延迟挂起(Suspend)或者长时任务避免进入挂起状态。 应用有不可中断且短时间能完成的任务时(如,用户在文件管理器上点击垃圾文件清理,若清理未完成时退到后台,文件管理器需要申请短时任务完成清理),可以使用短时任务机制。 应用中存在用户能够直观感受到的且需要一直在后台运行的业务时(如,后台播放音乐),可以使用长时任务机制。 对于系统特权应用,提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源,例如需要在被挂起期间仍然能够收到系统公共事件,可以使用能效资源申请接口。 > **说明:** > - 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。从API version 9开始,导入模块由@ohos.backgroundTaskManager迁移至@ohos.resourceschedule.backgroundTaskManager > - 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。 ## 导入模块 ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; ``` ## backgroundTaskManager.requestSuspendDelay7+(deprecated) requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo 后台应用申请延迟挂起。 延迟挂起时间一般情况下默认值为180000毫秒,低电量(依据系统低电量广播)时默认值为60000毫秒。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.requestSuspendDelay](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerrequestsuspenddelay9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------- | ---- | ------------------------------ | | reason | string | 是 | 延迟挂起申请的原因。 | | callback | Callback<void> | 是 | 延迟即将超时的回调函数,一般在超时前6秒通过此回调通知应用。 | **返回值**: | 类型 | 说明 | | ------------------------------------- | --------- | | [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | **示例**: ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; let myReason = 'test requestSuspendDelay'; let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { console.info("Request suspension delay will time out."); }) let id = delayInfo.requestId; let time = delayInfo.actualDelayTime; console.info("The requestId is: " + id); console.info("The actualDelayTime is: " + time); ``` ## backgroundTaskManager.getRemainingDelayTime7+(deprecated) getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 获取应用程序进入挂起状态前的剩余时间,使用callback形式返回。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.getRemainingDelayTime](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagergetremainingdelaytimecallback9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------------- | ---- | ---------------------------------------- | | requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 | **示例**: ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId, (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.getRemainingDelayTime7+(deprecated) getRemainingDelayTime(requestId: number): Promise<number> 获取应用程序进入挂起状态前的剩余时间,使用Promise形式返回。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.getRemainingDelayTime](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagergetremainingdelaytimepromise9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------- | | requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | **返回值**: | 类型 | 说明 | | --------------------- | ---------------------------------------- | | Promise<number> | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间,以毫秒为单位。 | **示例**: ```js let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId).then( res => { console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); }).catch( err => { console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); }) ``` ## backgroundTaskManager.cancelSuspendDelay7+(deprecated) cancelSuspendDelay(requestId: number): void 取消延迟挂起。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.cancelSuspendDelay](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagercancelsuspenddelay9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------- | | requestId | number | 是 | 延迟挂起的请求ID。这个值通过调用[requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay)方法获取。 | **示例**: ```js let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {}); backgroundTaskManager.cancelSuspendDelay(delayInfo.requestId); ``` ## backgroundTaskManager.startBackgroundRunning8+(deprecated) startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 向系统申请长时任务,使用callback形式返回结果。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.startBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstartbackgroundrunningcallback9) > > 从 API version 7开始支持。 **需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------- | ---- | ---------------------------------------- | | context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | | bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | | wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数,用于指定长时任务通知点击后跳转的界面。 | | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | **示例**: FA模型示例: ```js 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.LOCATION, wantAgentObj, callback) }); ``` 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) }); } }; ``` ## backgroundTaskManager.startBackgroundRunning8+(deprecated) startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 向系统申请长时任务,使用promise形式返回结果。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.startBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstartbackgroundrunningpromise9) > > 从 API version 7开始支持。 **需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------- | ---- | ---------------------------------------- | | context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | | bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | | wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数,用于指定长时任务通知点击跳转的界面。 | **返回值**: | 类型 | 说明 | | -------------- | ---------------- | | Promise\ | 使用Promise形式返回结果。 | **示例**: FA模型示例: ```js 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.LOCATION, wantAgentObj).then(() => { console.info("Operation startBackgroundRunning succeeded"); }).catch((err) => { console.error("Operation startBackgroundRunning failed Cause: " + err); }); }); ``` Stage模型示例: ```ts import Ability from '@ohos.application.Ability' import backgroundTaskManager from '@ohos.backgroundTaskManager'; import wantAgent from '@ohos.wantAgent'; 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); }); }); } }; ``` ## backgroundTaskManager.stopBackgroundRunning8+(deprecated) stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 向系统申请取消长时任务,使用callback形式返回结果。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.stopBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstopbackgroundrunningcallback9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------------------------------------- | | context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果。 | **示例**: FA模型示例: ```js 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); ``` 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); } }; ``` ## backgroundTaskManager.stopBackgroundRunning8+(deprecated) stopBackgroundRunning(context: Context): Promise<void> 向系统申请取消长时任务,使用promise形式返回结果。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.stopBackgroundRunning](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstopbackgroundrunningpromise9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **参数**: | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | ---------------------------------------- | | context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | **返回值**: | 类型 | 说明 | | -------------- | ---------------- | | Promise\ | 使用Promise形式返回结果。 | **示例**: FA模型示例: ```js 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); }); ``` 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); }); } }; ``` ## backgroundTaskManager.applyEfficiencyResources9+(deprecated) applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): void 向系统申请或释放能效资源,使用boolean形式返回结果。 通过EfficiencyResourcesRequest参数中的isApply变量,设置是申请还是释放。 应用使用此接口,需要向应用中心申请获得相应特权。 进程和它所属的应用可以同时申请某一类资源,例如CPU资源,但是应用释放资源的时候会将进程的资源一起释放。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.applyEfficiencyResources](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerapplyefficiencyresources9) > > 从 API version 9开始支持。 **系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统API**: 此接口为系统接口。 **参数**: | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | ---------------------------------------- | | request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是 | 请求的必要信息。包括资源类型,超时时间等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 | **示例**: ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; let request = { resourceTypes: backgroundTaskManager.ResourceType.CPU, // 如果将isApply置为false,则表示释放资源 isApply: true, timeOut: 0, reason: "apply", isPersist: true, isProcess: false, }; try { backgroundTaskManager.applyEfficiencyResources(request); console.info("applyEfficiencyResources success. "); } catch (error) { console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); } ``` ## backgroundTaskManager.resetAllEfficiencyResources9+(deprecated) resetAllEfficiencyResources(): void 释放所有已经申请的资源。 应用使用此接口,需要向应用中心申请获得相应特权。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.resetAllEfficiencyResources](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerresetallefficiencyresources9) > > 从 API version 9开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统API**: 此接口为系统接口。 **示例**: ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; try { backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); } catch (error) { console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`); } ``` ## DelaySuspendInfo7+(deprecated) 延迟挂起信息。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.DelaySuspendInfo](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerdelaysuspendinfo9) > > 从 API version 7开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask | 参数名 | 类型 | 必填 | 说明 | | --------------- | ------ | ---- | ---------------------------------------- | | requestId | number | 是 | 延迟挂起的请求ID。 | | actualDelayTime | number | 是 | 应用的实际挂起延迟时间,以毫秒为单位。
一般情况下默认值为180000,低电量(依据系统低电量广播)时默认值为60000。 | ## BackgroundMode8+(deprecated) **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask | 参数名 | 参数值 | 描述 | | ----------------------- | ---- | --------------------- | | DATA_TRANSFER | 1 | 数据传输。 | | AUDIO_PLAYBACK | 2 | 音频播放。 | | AUDIO_RECORDING | 3 | 录音。 | | LOCATION | 4 | 定位导航。 | | BLUETOOTH_INTERACTION | 5 | 蓝牙相关。 | | MULTI_DEVICE_CONNECTION | 6 | 多设备互联。 | | WIFI_INTERACTION | 7 | WLAN相关
此接口为系统接口。 | | VOIP | 8 | 音视频通话
此接口为系统接口。 | | TASK_KEEPING | 9 | 计算任务(仅在特定设备生效)。 | ## EfficiencyResourcesRequest9+(deprecated) 能效资源申请参数。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.EfficiencyResourcesRequest](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerefficiencyresourcesrequest9) > > 从 API version 9开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统API**: 此接口为系统接口。 | 参数名 | 类型 | 必填 | 说明 | | --------------- | ------ | ---- | ---------------------------------------- | | resourceTypes | number | 是 | 申请的资源类型。 | | isApply | boolean | 是 | 申请资源或者是释放资源。 | | timeOut | number | 是 | 资源的使用时间,以毫秒为单位。 | | isPersist | boolean | 否 | 是否永久持有资源,如果是true,那么timeOut就无效。 | | isProcess | boolean | 否 | 应用申请或者是进程申请。 | | reason | string | 是 | 申请资源的原因。 | ## ResourceType9+(deprecated) 能效资源类型。 > **说明:** 从API version 9开始废弃,建议使用[backgroundTaskManager.ResourceType](./js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerresourcetype9) > > 从 API version 9开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统API**: 此接口为系统接口。 | 参数名 | 参数值 | 描述 | | ----------------------- | ---- | --------------------- | | CPU | 1 | CPU资源,申请后不被挂起。 | | COMMON_EVENT | 2 | 公共事件,申请后挂起状态下不被代理掉。 | | TIMER | 4 | 计时器,申请后挂起状态下不被代理掉。 | | WORK_SCHEDULER | 8 | 延迟任务,申请后有更长的执行时间。 | | BLUETOOTH | 16 | 蓝牙相关,申请后挂起状态下不被代理掉。 | | GPS | 32 | GPS相关,申请后挂起状态下不被代理掉。 | | AUDIO | 64 | 音频资源,申请后挂起状态下不被代理掉。 |