鸿蒙API14开发【@ohos.resourceschedule.workScheduler (延迟任务调度)】后台任务开发

本模块提供延迟任务注册、取消、查询的能力。在开发过程中,对于实时性要求不高的任务,可以调用本模块接口注册延迟任务,在系统空闲时根据性能、功耗、热等情况进行调度执行。

说明:

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

本模块接口仅可在Stage模型下使用。

导入模块

import { workScheduler } from '@kit.BackgroundTasksKit';
ts

workScheduler.startWork

startWork(work: WorkInfo): void

申请延迟任务。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
work[WorkInfo]要添加到执行队列的延迟任务。
错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.
9700005Calling startWork failed.

示例

  import { BusinessError } from '@kit.BasicServicesKit';
  
  let workInfo: workScheduler.WorkInfo = {
      workId: 1,
      batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
      isRepeat: false,
      isPersisted: true,
      bundleName: "com.example.myapplication",
      abilityName: "MyExtension",
      parameters: {
          mykey0: 1,
          mykey1: "string value",
          mykey2: true,
          mykey3: 1.5
      }
  }
  try{
    workScheduler.startWork(workInfo);
    console.info('workschedulerLog startWork success');
  } catch (error) {
    console.error(`workschedulerLog startwork failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
  }
ts

workScheduler.stopWork

stopWork(work: WorkInfo, needCancel?: boolean): void

取消延迟任务。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
work[WorkInfo]要停止或移除的延迟任务。
needCancelboolean是否需要移除任务。 true表示停止并移除,false表示只停止不移除。默认为false。
错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.

示例

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

  let workInfo: workScheduler.WorkInfo = {
      workId: 1,
      batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
      isRepeat: false,
      isPersisted: true,
      bundleName: "com.example.myapplication",
      abilityName: "MyExtension",
      parameters: {
          mykey0: 1,
          mykey1: "string value",
          mykey2: true,
          mykey3: 1.5
      }
     }
  try{
    workScheduler.stopWork(workInfo, false);
    console.info('workschedulerLog stopWork success');
  } catch (error) {
    console.error(`workschedulerLog stopWork failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
  }
ts

workScheduler.getWorkStatus

getWorkStatus(workId: number, callback : AsyncCallback): void

通过workId获取延迟任务,使用Callback异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
workIdnumber延迟任务Id。
callbackAsyncCallback<[WorkInfo]>回调函数。如果workId有效,则返回从WorkSchedulerService获取的任务,否则抛出异常。
错误码ID错误信息
401Parameter error. Possible causes: Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.

示例

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

  workScheduler.getWorkStatus(50, (error: BusinessError, res: workScheduler.WorkInfo) => {
    if (error) {
      console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
    } else {
      console.info(`workschedulerLog getWorkStatus success, ${JSON.stringify(res)}`);
    }
  });
ts

workScheduler.getWorkStatus

getWorkStatus(workId: number): Promise

通过workId获取延迟任务,使用Promise异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
workIdnumber延迟任务Id。

返回值

类型说明
Promise<[WorkInfo]>Promise对象,如果workId有效,则返回从WorkSchedulerService获取的任务,否则抛出异常。
错误码ID错误信息
401Parameter error. Possible causes: Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.

示例

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

  workScheduler.getWorkStatus(50).then((res: workScheduler.WorkInfo) => {
    console.info(`workschedulerLog getWorkStatus success, ${JSON.stringify(res)}`);
  }).catch((error: BusinessError) => {
    console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
  })
ts

workScheduler.obtainAllWorksdeprecated

obtainAllWorks(callback : AsyncCallback) : Array

从API version 10开始不再维护,建议使用[workScheduler.obtainAllWorks10+]替代

获取当前应用所有的延迟任务,使用Callback异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
callbackAsyncCallback回调函数,获取成功时,err为undefined,否则为错误对象。
错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.

workScheduler.obtainAllWorks10+

obtainAllWorks(callback : AsyncCallback<Array>): void

获取当前应用所有的延迟任务,使用Callback异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
callbackAsyncCallback<Array>回调函数,获取成功时,err为undefined,否则为错误对象。
错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.

示例

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

  workScheduler.obtainAllWorks((error: BusinessError, res: Array<workScheduler.WorkInfo>) =>{
    if (error) {
      console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
    } else {
      console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
    }
  });
ts

workScheduler.obtainAllWorks

obtainAllWorks(): Promise<Array>

获取当前应用所有的延迟任务,使用Promise异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

返回值

类型说明
Promise<Array<[WorkInfo])>>Promise对象,返回当前应用所有的延迟任务。
错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.

示例

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

  workScheduler.obtainAllWorks().then((res: Array<workScheduler.WorkInfo>) => {
    console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
  }).catch((error: BusinessError) => {
    console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
  })
ts

workScheduler.stopAndClearWorks

stopAndClearWorks(): void

停止和取消当前应用所有的延迟任务。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.

示例

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

  try{
    workScheduler.stopAndClearWorks();
    console.info(`workschedulerLog stopAndClearWorks success`);
  } catch (error) {
    console.error(`workschedulerLog stopAndClearWorks failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
  }
ts

workScheduler.isLastWorkTimeOutdeprecated

isLastWorkTimeOut(workId: number, callback : AsyncCallback): boolean

检查延迟任务的最后一次执行是否超时,使用Callback异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
workIdnumber指定延迟任务的Id。
callbackAsyncCallback回调函数。
错误码ID错误信息
401Parameter error. Possible causes: Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.

workScheduler.isLastWorkTimeOut10+

isLastWorkTimeOut(workId: number, callback : AsyncCallback): void

检查延迟任务的最后一次执行是否超时,使用Callback异步回调。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
workIdnumber指定延迟任务的Id。
callbackAsyncCallback回调函数。
错误码ID错误信息
401Parameter error. Possible causes: Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.

示例

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

  workScheduler.isLastWorkTimeOut(500, (error: BusinessError, res: boolean) =>{
    if (error) {
      console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
    } else {
      console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
    }
  });
ts

workScheduler.isLastWorkTimeOut

isLastWorkTimeOut(workId: number): Promise

检查延迟任务的最后一次执行是否超时,使用Promise形式返回。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

参数

参数名类型必填说明
workIdnumber指定延迟任务的Id。

返回值

类型说明
PromisePromise对象。返回true表示指定任务的最后一次执行超时,false表示未超时。
错误码ID错误信息
401Parameter error. Possible causes: Parameter verification failed.
9700001Memory operation failed.
9700002Parcel operation failed.
9700003System service operation failed.
9700004Check on workInfo failed.

示例

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

  workScheduler.isLastWorkTimeOut(500)
    .then((res: boolean) => {
      console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
    })
    .catch((error: BusinessError) =>  {
      console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
    });
ts

WorkInfo

延迟任务的具体信息。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

名称类型必填说明
workIdnumber延迟任务ID。
bundleNamestring延迟任务所在应用的包名。
abilityNamestring包内ability名称。
networkType[NetworkType]网络类型。
isChargingboolean是否充电。 - true表示充电触发延迟回调。 - false表示不充电触发延迟回调。
chargerType[ChargingType]充电类型。
batteryLevelnumber电量。
batteryStatus[BatteryStatus]电池状态。
storageRequest[StorageRequest]存储状态。
isRepeatboolean是否循环任务。 - true表示循环任务。 - false表示非循环任务。
repeatCycleTimenumber循环间隔,单位为毫秒。
repeatCountnumber循环次数。
isPersistedboolean注册的延迟任务是否可保存在系统中。 - true表示可保存,即系统重启后,任务可恢复。 - false表示不可保存。
isDeepIdleboolean是否要求设备进入空闲状态。 - true表示需要。 - false表示不需要。
idleWaitTimenumber空闲等待时间,单位为毫秒。
parametersRecord<string, numberstringboolean>

NetworkType

触发延迟回调的网络类型。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

名称说明
NETWORK_TYPE_ANY0表示这个触发条件是任何类型的网络连接。
NETWORK_TYPE_MOBILE1表示这个触发条件是Mobile网络连接。
NETWORK_TYPE_WIFI2表示这个触发条件是Wifi类型的网络连接。
NETWORK_TYPE_BLUETOOTH3表示这个触发条件是Bluetooth网络连接。
NETWORK_TYPE_WIFI_P2P4表示这个触发条件是Wifi P2P网络连接。
NETWORK_TYPE_ETHERNET5表示这个触发条件是有线网络连接。

ChargingType

触发延迟回调的充电类型。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

名称说明
CHARGING_PLUGGED_ANY0表示这个触发条件是任何类型的充电器连接。
CHARGING_PLUGGED_AC1表示这个触发条件是直流充电器连接。
CHARGING_PLUGGED_USB2表示这个触发条件是USB充连接。
CHARGING_PLUGGED_WIRELESS3表示这个触发条件是无线充电器连接。

BatteryStatus

触发延迟回调的电池状态。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

名称说明
BATTERY_STATUS_LOW0表示这个触发条件是低电告警。
BATTERY_STATUS_OKAY1表示这个触发条件是从低电恢复到正常电量。
BATTERY_STATUS_LOW_OR_OKAY2表示这个触发条件是从低电恢复到正常电量或者低电告警。

StorageRequest

触发延迟回调的存储状态。

系统能力:SystemCapability.ResourceSchedule.WorkScheduler

名称说明
STORAGE_LEVEL_LOW0表示这个触发条件是存储空间不足。
STORAGE_LEVEL_OKAY1表示这个触发条件是从存储空间不足恢复到正常。
STORAGE_LEVEL_LOW_OR_OKAY2表示这个触发条件是存储空间不足或者从存储空间不足恢复到正常。

加入鸿蒙学习阵营!

除了本文,面费领《HarmonyOS应用开发》+《鸿蒙openharmony系统开发大全》 等入门进阶资料!关注我的优快云主页,持续获取:
在这里插入图片描述

最新鸿蒙技术文章
独家项目实战教程
免费直播/训练营信息
👉 下方资源区已为你备好!

评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值