openharmony 鸿蒙 js-apis-resourceschedule-backgroundTaskManager

2025-06-12 浏览 (1)

@ohos.resourceschedule.backgroundTaskManager (后台任务管理)

本模块提供申请后台任务的接口。当应用退至后台时，开发者可以通过本模块接口为应用申请短时、长时任务，避免应用进程被终止或挂起。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';

backgroundTaskManager.requestSuspendDelay

requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo

申请短时任务。

说明：

短时任务的申请和使用过程中的约束与限制请参考指南。

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

参数：

参数名类型必填说明
reasonstring是申请短时任务的原因。
callbackCallback<void>是短时任务即将超时的回调函数，一般在超时前6秒，通过此回调通知应用。

返回值：

类型说明
DelaySuspendInfo返回短时任务信息。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9900001Caller information verification failed for a transient task.
9900002Transient task verification failed.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let myReason = 'test requestSuspendDelay';
try {
    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);
} catch (error) {
    console.error(`requestSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

backgroundTaskManager.getRemainingDelayTime

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

获取本次短时任务的剩余时间，使用callback异步回调。

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

参数：

参数名类型必填说明
requestIdnumber是短时任务的请求ID。
callbackAsyncCallback<number>是回调函数，返回本次短时任务的剩余时间，单位为毫秒。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9900001Caller information verification failed for a transient task.
9900002Transient task verification failed.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (error: BusinessError, res: number) => {
    if(error) {
        console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
    } else {
        console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
    }
})

backgroundTaskManager.getRemainingDelayTime

getRemainingDelayTime(requestId: number): Promise<number>

获取本次短时任务的剩余时间，使用promise异步回调。

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

参数：

参数名类型必填说明
requestIdnumber是短时任务的请求ID。

返回值：

类型说明
Promise<number>Promise对象，返回本次短时任务的剩余时间，单位为毫秒。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9900001Caller information verification failed for a transient task.
9900002Transient task verification failed.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then((res: number) => {
    console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch((error: BusinessError) => {
    console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
})

backgroundTaskManager.cancelSuspendDelay

cancelSuspendDelay(requestId: number): void

取消短时任务。

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

参数：

参数名类型必填说明
requestIdnumber是短时任务的请求ID。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9900001Caller information verification failed for a transient task.
9900002Transient task verification failed.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let id = 1;
try {
  backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
  console.error(`cancelSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

backgroundTaskManager.getTransientTaskInfo20+

getTransientTaskInfo(): Promise<TransientTaskInfo>

获取所有短时任务信息，如当日剩余总配额等，使用Promise异步回调。

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

返回值：

类型说明
Promise<TransientTaskInfo>Promise对象，返回所有短时任务信息。

错误码：

以下错误码的详细介绍请参见backgroundTaskManager错误码。

错误码ID错误信息
9900001Caller information verification failed for a transient task.
9900003Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9900004System service operation failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
    backgroundTaskManager.getTransientTaskInfo().then((res: backgroundTaskManager.TransientTaskInfo) => {
        console.info(`Operation getTransientTaskInfo succeeded. data: ` + JSON.stringify(res));
    }).catch((error : BusinessError) => {
        console.error(`Operation getTransientTaskInfo failed. code is ${error.code} message is ${error.message}`);
    });
} catch (error) {
    console.error(`Operation getTransientTaskInfo failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

backgroundTaskManager.startBackgroundRunning

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

申请长时任务，支持申请一种类型，使用callback异步回调。长时任务申请成功后，会有通知栏消息，没有提示音。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。
bgModeBackgroundMode是长时任务类型。
wantAgentWantAgent是通知参数，用于指定点击长时任务通知后跳转的界面。
callbackAsyncCallback<void>是回调函数，申请长时任务成功时，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
202Not System App.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9800005Continuous task verification failed.
9800006Notification verification failed for a continuous task.
9800007Continuous task storage failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { wantAgent, WantAgent } from '@kit.AbilityKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(error: BusinessError, data: void) {
    if (error) {
        console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
    } else {
        console.info("Operation startBackgroundRunning succeeded");
    }
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        let wantAgentInfo: wantAgent.WantAgentInfo = {
            // 点击通知后，将要执行的动作列表
            wants: [
                {
                    bundleName: "com.example.myapplication",
                    abilityName: "EntryAbility"
                }
            ],
            // 点击通知后，动作类型
            actionType: wantAgent.OperationType.START_ABILITY,
            // 使用者自定义的一个私有值
            requestCode: 0,
            // 点击通知后，动作执行属性
            wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
        };

        try {
            // 通过wantAgent模块下getWantAgent方法获取WantAgent对象
            wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => {
                try {
                    backgroundTaskManager.startBackgroundRunning(this.context,
                        backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
                } catch (error) {
                    console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
                }
            });
        } catch (error) {
            console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.startBackgroundRunning

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

申请长时任务，支持申请一种类型，使用promise异步回调。长时任务申请成功后，会有通知栏消息，没有提示音。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。
bgModeBackgroundMode是长时任务类型。
wantAgentWantAgent是通知参数，用于指定点击长时任务通知后跳转的界面。

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
202Not System App.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9800005Continuous task verification failed.
9800006Notification verification failed for a continuous task.
9800007Continuous task storage failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { wantAgent, WantAgent } from '@kit.AbilityKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        let wantAgentInfo: wantAgent.WantAgentInfo = {
            // 点击通知后，将要执行的动作列表
            wants: [
                {
                    bundleName: "com.example.myapplication",
                    abilityName: "EntryAbility"
                }
            ],
            // 点击通知后，动作类型
            actionType: wantAgent.OperationType.START_ABILITY,
            // 使用者自定义的一个私有值
            requestCode: 0,
            // 点击通知后，动作执行属性
            wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
        };

        try {
            // 通过wantAgent模块下getWantAgent方法获取WantAgent对象
            wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => {
                try {
                    backgroundTaskManager.startBackgroundRunning(this.context,
                        backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
                        console.info("Operation startBackgroundRunning succeeded");
                    }).catch((error: BusinessError) => {
                        console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
                    });
                } catch (error) {
                    console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
                }
            });
        } catch (error) {
            console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.stopBackgroundRunning

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

取消长时任务，使用callback异步回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。
callbackAsyncCallback<void>是回调函数，取消长时任务成功时，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9800005Continuous task verification failed.
9800006Notification verification failed for a continuous task.
9800007Continuous task storage failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(error: BusinessError, data: void) {
    if (error) {
        console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
    } else {
        console.info("Operation stopBackgroundRunning succeeded");
    }
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.stopBackgroundRunning(this.context, callback);
        } catch (error) {
            console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.stopBackgroundRunning

stopBackgroundRunning(context: Context): Promise<void>

取消长时任务，使用promise异步回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9800005Continuous task verification failed.
9800006Notification verification failed for a continuous task.
9800007Continuous task storage failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
                console.info("Operation stopBackgroundRunning succeeded");
            }).catch((error: BusinessError) => {
                console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
            });
        } catch (error) {
            console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.startBackgroundRunning12+

startBackgroundRunning(context: Context, bgModes: string[], wantAgent: WantAgent): Promise<ContinuousTaskNotification>

申请长时任务，支持申请多种类型，使用promise异步回调。长时任务申请成功后，会有通知栏消息，没有提示音。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
bgModesstring[]是长时任务类型，取值范围请参考长时任务类型中的配置项。
说明： 支持传入一个或多个类型。
wantAgentWantAgent是通知参数，用于指定点击长时任务通知后跳转的界面。

返回值：

类型说明
Promise<ContinuousTaskNotification>返回ContinuousTaskNotification类型的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9800005Continuous task verification failed.
9800006Notification verification failed for a continuous task.
9800007Continuous task storage failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { wantAgent, WantAgent } from '@kit.AbilityKit';
import { notificationManager } from '@kit.NotificationKit';

export default class EntryAbility extends UIAbility {
  id: number = 0; // 保存通知id

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    let wantAgentInfo: wantAgent.WantAgentInfo = {
      // 点击通知后，将要执行的动作列表
      wants: [
        {
          bundleName: "com.example.myapplication",
          abilityName: "EntryAbility"
        }
      ],
      // 点击通知后，动作类型
      actionType: wantAgent.OperationType.START_ABILITY,
      // 使用者自定义的一个私有值
      requestCode: 0,
      // 点击通知后，动作执行属性
      wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
    };

    try {
      // 通过wantAgent模块下getWantAgent方法获取WantAgent对象
      wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => {
        try {
          let list: Array<string> = ["dataTransfer"];
          backgroundTaskManager.startBackgroundRunning(this.context, list, wantAgentObj).then((res: backgroundTaskManager.ContinuousTaskNotification) => {
            console.info("Operation startBackgroundRunning succeeded");
            // 对于上传下载类的长时任务，应用可以使用res中返回的notificationId来更新通知，比如发送带进度条的模板通知。
            this.id = res.notificationId;
          }).catch((error: BusinessError) => {
            console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
          });
        } catch (error) {
          console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
      });
    } catch (error) {
      console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
    }
  }

  // 应用更新进度
  updateProcess(process: Number) {
    // 应用定义下载类通知模版
    let downLoadTemplate: notificationManager.NotificationTemplate = {
      name: 'downloadTemplate', // 当前只支持downloadTemplate，保持不变
      data: {
        title: '文件下载：music.mp4', // 必填。
        fileName: 'senTemplate', // 必填。
        progressValue: process, // 应用更新进度值，自定义。
      }
    };
    let request: notificationManager.NotificationRequest = {
      content: {
        // 系统实况类型，保持不变
        notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_SYSTEM_LIVE_VIEW,
        systemLiveView: {
          typeCode: 8, // 上传下载类型需要填写 8，当前仅支持此类型。保持不变
          title: "test", // 应用自定义
          text: "test", // 应用自定义
        }
      },
      id: this.id, // 必须是申请长时任务返回的id，否则应用更新通知失败。
      notificationSlotType: notificationManager.SlotType.LIVE_VIEW, // 实况窗类型，保持不变
      template: downLoadTemplate // 应用需要设置的模版名称
    };

    try {
      notificationManager.publish(request).then(() => {
        console.info("publish success, id= " + this.id);
      }).catch((err: BusinessError) => {
        console.error(`publish fail: ${JSON.stringify(err)}`);
      });
    } catch (err) {
      console.error(`publish fail: ${JSON.stringify(err)}`);
    }
  }
};

backgroundTaskManager.updateBackgroundRunning12+

updateBackgroundRunning(context: Context, bgModes: string[]): Promise<ContinuousTaskNotification>

更新长时任务类型，使用promise异步回调。长时任务更新成功后，会有通知栏消息，没有提示音。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
bgModesstring[]是更新后的长时任务类型，取值范围请参考长时任务类型中的配置项。
说明： 支持传入一个或多个类型。

返回值：

类型说明
Promise<ContinuousTaskNotification>返回ContinuousTaskNotification类型的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001Memory operation failed.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003Internal transaction failed.
9800004System service operation failed.
9800005Continuous task verification failed.
9800006Notification verification failed for a continuous task.
9800007Continuous task storage failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
                try {
                    // 必须先执行startBackgroundRunning，才能调用updateBackgroundRunning。这里假设已经申请过。
                    let list: Array<string> = ["audioPlayback"];
                    backgroundTaskManager.updateBackgroundRunning(this.context, list).then(() => {
                        console.info("Operation updateBackgroundRunning succeeded");
                    }).catch((error: BusinessError) => {
                        console.error(`Operation updateBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
                    });
                } catch (error) {
                    console.error(`Operation updateBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
                }
        } catch (error) {
            console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.getAllContinuousTasks20+

getAllContinuousTasks(context: Context): Promise<ContinuousTaskInfo[]>

获取所有长时任务信息，如长时任务Id、长时任务类型等，使用Promise异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。

返回值：

类型说明
Promise<ContinuousTaskInfo[]>Promise对象，返回所有长时任务信息。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
9800002Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800004System service operation failed.
9800005Continuous task verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            try {
                // 如果当前没有申请长时任务，则获取到一个空数组
                backgroundTaskManager.getAllContinuousTasks(this.context).then((res: backgroundTaskManager.ContinuousTaskInfo[]) => {
                    console.info(`Operation getAllContinuousTasks succeeded. data: ` + JSON.stringify(res));
                }).catch((error: BusinessError) => {
                    console.error(`Operation getAllContinuousTasks failed. code is ${error.code} message is ${error.message}`);
                });
            } catch (error) {
                console.error(`Operation getAllContinuousTasks failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
            }
        } catch (error) {
            console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.on('continuousTaskCancel')15+

on(type: 'continuousTaskCancel', callback: Callback<ContinuousTaskCancelInfo>): void

注册长时任务取消的监听，使用callback异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
typestring是取消长时任务，固定取值为'continuousTaskCancel'。
callbackCallback<ContinuousTaskCancelInfo>是回调函数，返回长时任务取消原因等信息。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error. Possible cause: 1. Callback parameter error; 2. Register a exist callback type; 3. Parameter verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) {
  console.info('continuousTaskCancel callback id ' + info.id);
  console.info('continuousTaskCancel callback reason ' + info.reason);
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.on("continuousTaskCancel", callback);
        } catch (error) {
            console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.off('continuousTaskCancel')15+

off(type: 'continuousTaskCancel', callback?: Callback<ContinuousTaskCancelInfo>): void

解除长时任务取消的监听，使用callback异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
typestring是取消长时任务，固定取值为'continuousTaskCancel'。
callbackCallback<ContinuousTaskCancelInfo>否需要取消监听的回调函数，未传入则取消所有注册回调。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error. Possible cause: 1. Callback parameter error; 2. Unregister type has not register; 3. Parameter verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) {
  console.info('continuousTaskCancel callback id ' + info.id);
  console.info('continuousTaskCancel callback reason ' + info.reason);
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.off("continuousTaskCancel", callback);
        } catch (error) {
            console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.on('continuousTaskSuspend')20+

on(type: 'continuousTaskSuspend', callback: Callback<ContinuousTaskSuspendInfo>): void

注册长时任务暂停的监听，使用callback异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
typestring是事件回调类型，固定取值为'continuousTaskSuspend'，表示长时任务暂停。
callbackCallback<ContinuousTaskSuspendInfo>是回调函数，返回长时任务暂停原因等信息。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
9800005Continuous task verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(info: backgroundTaskManager.ContinuousTaskSuspendInfo) {
  console.info('continuousTaskSuspend callback continuousTaskId: ' + info.continuousTaskId);
  console.info('continuousTaskSuspend callback suspendState: ' + info.suspendState);
  console.info('continuousTaskSuspend callback suspendReason: ' + info.suspendReason);
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.on("continuousTaskSuspend", callback);
        } catch (error) {
            console.error(`Operation onContinuousTaskSuspend failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.off('continuousTaskSuspend')20+

off(type: 'continuousTaskSuspend', callback?: Callback<ContinuousTaskSuspendInfo>): void

取消长时任务暂停的监听，使用callback异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
typestring是事件回调类型，固定取值为'continuousTaskSuspend'，表示长时任务暂停。
callbackCallback<ContinuousTaskSuspendInfo>否需要取消监听的回调函数，未传入则取消所有注册的暂停回调。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
9800005Continuous task verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(info: backgroundTaskManager.ContinuousTaskSuspendInfo) {
  console.info('continuousTaskSuspend callback continuousTaskId: ' + info.continuousTaskId);
  console.info('continuousTaskSuspend callback suspendState: ' + info.suspendState);
  console.info('continuousTaskSuspend callback suspendReason: ' + info.suspendReason);
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.off("continuousTaskSuspend", callback);
        } catch (error) {
            console.error(`Operation offContinuousTaskSuspend failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.on('continuousTaskActive')20+

on(type: 'continuousTaskActive', callback: Callback<ContinuousTaskActiveInfo>): void

注册长时任务激活的监听，使用callback异步回调。应用回前台激活暂停的长时任务。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
typestring是事件回调类型，固定取值为'continuousTaskActive'，表示长时任务激活。
callbackCallback<ContinuousTaskActiveInfo>是回调函数，返回长时任务激活相关信息。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
9800005Continuous task verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(info: backgroundTaskManager.ContinuousTaskActiveInfo) {
  console.info('continuousTaskActive callback id: ' + info.id);
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.on("continuousTaskActive", callback);
        } catch (error) {
            console.error(`Operation onContinuousTaskActive failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.off('continuousTaskActive')20+

off(type: 'continuousTaskActive', callback?: Callback<ContinuousTaskActiveInfo>): void

取消长时任务激活的监听，使用callback异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
typestring是事件回调类型，固定取值为'continuousTaskActive'，表示长时任务激活。
callbackCallback<ContinuousTaskActiveInfo>否需要取消监听的回调函数，未传入则取消所有注册的激活回调。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID错误信息
201Permission denied.
9800005Continuous task verification failed.

示例：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

function callback(info: backgroundTaskManager.ContinuousTaskActiveInfo) {
  console.info('continuousTaskActive callback id: ' + info.id);
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.off("continuousTaskActive", callback);
        } catch (error) {
            console.error(`Operation offContinuousTaskActive failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

DelaySuspendInfo

短时任务信息。

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

名称类型必填说明
requestIdnumber是短时任务的请求ID。
actualDelayTimenumber是应用实际申请的短时任务时间，单位为毫秒。
说明 ：申请时间最长为3分钟，低电量时最长为1分钟。

TransientTaskInfo20+

所有短时任务信息。

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

名称类型只读可选说明
remainingQuotanumber否否应用当日所剩余总配额，单位：ms。
transientTasksDelaySuspendInfo[]否否当前已申请的所有短时任务信息。

BackgroundMode

长时任务类型。

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

名称值说明
DATA_TRANSFER1数据传输。
AUDIO_PLAYBACK2音视频播放。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
AUDIO_RECORDING3录制。
LOCATION4定位导航。
BLUETOOTH_INTERACTION5蓝牙相关业务。
MULTI_DEVICE_CONNECTION6多设备互联。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
VOIP13+8音视频通话。
TASK_KEEPING9计算任务（仅对2in1设备开放）。

ContinuousTaskNotification12+

长时任务通知信息。

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

名称类型只读可选说明
slotTypenotificationManager.SlotType否否长时任务通知的渠道类型。
说明： 长时任务申请或更新成功后不支持提示音。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
contentTypenotificationManager.ContentType否否长时任务通知的内容类型。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
notificationIdnumber否否长时任务通知 Id。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
continuousTaskId15+number否是长时任务 Id。

ContinuousTaskCancelInfo15+

长时任务取消信息。

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

名称类型必填说明
reasonContinuousTaskCancelReason是长时任务取消原因。
idnumber是被取消的长时任务 Id。

ContinuousTaskCancelReason15+

长时任务取消原因。

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

名称值说明
USER_CANCEL1用户取消。
SYSTEM_CANCEL2系统取消。
USER_CANCEL_REMOVE_NOTIFICATION3用户移除通知。预留接口，暂未启用。
SYSTEM_CANCEL_DATA_TRANSFER_LOW_SPEED4申请DATA_TRANSFER类型长时任务，但是数据传输速率低。预留接口，暂未启用。
SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_USE_AVSESSION5申请AUDIO_PLAYBACK类型长时任务，但是未接入AVSession。预留接口，暂未启用。
SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_RUNNING6申请AUDIO_PLAYBACK类型长时任务，但是未播放音视频。预留接口，暂未启用。
SYSTEM_CANCEL_AUDIO_RECORDING_NOT_RUNNING7申请AUDIO_RECORDING类型长时任务，但是未录制。预留接口，暂未启用。
SYSTEM_CANCEL_NOT_USE_LOCATION8申请LOCATION类型长时任务，但是未使用定位导航。预留接口，暂未启用。
SYSTEM_CANCEL_NOT_USE_BLUETOOTH9申请BLUETOOTH_INTERACTION类型长时任务，但是未使用蓝牙相关业务。预留接口，暂未启用。
SYSTEM_CANCEL_NOT_USE_MULTI_DEVICE10申请MULTI_DEVICE_CONNECTION类型长时任务，但是未使用多设备互联。预留接口，暂未启用。
SYSTEM_CANCEL_USE_ILLEGALLY11使用非法类型的长时任务，如申请AUDIO_PLAYBACK类型长时任务，但是使用音视频播放及定位导航业务。预留接口，暂未启用。

BackgroundSubMode16+

长时任务子类型。

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

名称值说明
CAR_KEY1车钥匙。
说明： 只有申请BLUETOOTH_INTERACTION类型的长时任务，车钥匙子类型才能生效。

BackgroundModeType16+

长时任务类型类别。

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

名称值说明
SUB_MODE'subMode'子类型。

ContinuousTaskSuspendInfo20+

长时任务暂停信息。

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

名称类型必填说明
continuousTaskIdnumber是被暂停的长时任务 Id。
suspendStateboolean是长时任务状态，false表示激活，true表示暂停。
suspendReasonContinuousTaskSuspendReason是长时任务暂停原因。

ContinuousTaskSuspendReason20+

长时任务暂停原因。

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

名称值说明
SYSTEM_SUSPEND_DATA_TRANSFER_LOW_SPEED4申请DATA_TRANSFER类型长时任务，但是数据传输速率低。
SYSTEM_SUSPEND_AUDIO_PLAYBACK_NOT_USE_AVSESSION5申请AUDIO_PLAYBACK类型长时任务，但是未接入AVSession。
SYSTEM_SUSPEND_AUDIO_PLAYBACK_NOT_RUNNING6申请AUDIO_PLAYBACK类型长时任务，但是未播放音视频。
SYSTEM_SUSPEND_AUDIO_RECORDING_NOT_RUNNING7申请AUDIO_RECORDING类型长时任务，但是未录制。
SYSTEM_SUSPEND_LOCATION_NOT_USED8申请LOCATION类型长时任务，但是未使用定位导航。
SYSTEM_SUSPEND_BLUETOOTH_NOT_USED9申请BLUETOOTH_INTERACTION类型长时任务，但是未使用蓝牙相关业务。
SYSTEM_SUSPEND_MULTI_DEVICE_NOT_USED10申请MULTI_DEVICE_CONNECTION类型长时任务，但是未使用多设备互联。
SYSTEM_SUSPEND_USED_ILLEGALLY11使用非法类型的长时任务，如申请AUDIO_PLAYBACK类型长时任务，但是使用音视频播放及定位导航业务。预留接口，暂未启用。
SYSTEM_SUSPEND_SYSTEM_LOAD_WARNING12系统高负载暂停长时任务。预留接口，暂未启用。

ContinuousTaskActiveInfo20+

长时任务激活信息。

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

名称类型必填说明
idnumber是被激活的长时任务 Id。

ContinuousTaskInfo20+

长时任务信息。

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

名称类型只读可选说明
abilityNamestring否否UIAbility名称。
uidnumber否否应用的UID。
pidnumber否否应用进程的PID。
isFromWebViewboolean否否是否通过Webview方式申请，即通过系统代理应用申请长时任务。
backgroundModesstring[]否否长时任务类型。
backgroundSubModesstring[]否否长时任务子类型。
notificationIdnumber否否通知 Id。
continuousTaskIdnumber否否长时任务Id。
abilityIdnumber否否UIAbility Id。
wantAgentBundleNamestring否否WantAgent配置的包名。WantAgent为通知参数，用于指定点击长时任务通知后跳转的界面，在申请长时任务时作为参数传入。
wantAgentAbilityNamestring否否WantAgent配置的ability名称。WantAgent为通知参数，用于指定点击长时任务通知后跳转的界面，在申请长时任务时作为参数传入。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Background Tasks Kit（后台任务开发服务）

harmony 鸿蒙BackgroundProcessManager

harmony 鸿蒙TransientTask

harmony 鸿蒙TransientTask_DelaySuspendInfo

harmony 鸿蒙TransientTask_TransientTaskInfo

harmony 鸿蒙background_process_manager.h

harmony 鸿蒙DeviceUsageStatistics错误码

harmony 鸿蒙backgroundTaskManager错误码

harmony 鸿蒙reminderAgentManager错误码

harmony 鸿蒙workScheduler错误码

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/pW29oI