1# @ohos.resourceschedule.workScheduler (延迟任务调度) 2 3本模块提供延迟任务注册、取消、查询的能力。在开发过程中，对于实时性要求不高的任务，可以调用本模块接口注册延迟任务，在系统空闲时根据性能、功耗、热等情况进行调度执行。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块接口仅可在Stage模型下使用。 10 11## 导入模块 12 13```ts 14import { workScheduler } from '@kit.BackgroundTasksKit'; 15``` 16 17## workScheduler.startWork 18 19startWork(work: WorkInfo): void 20 21申请延迟任务。 22 23**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 24 25**参数**： 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ---- | --------------------- | ---- | -------------- | 29| work | [WorkInfo](#workinfo) | 是 | 要添加到执行队列的延迟任务。 | 30 31**错误码**： 32 33以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 34 35| 错误码ID | 错误信息 | 36| ---- | --------------------- | 37| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 38| 9700001 | Memory operation failed. | 39| 9700002 | Parcel operation failed. | 40| 9700003 | System service operation failed. | 41| 9700004 | Check on workInfo failed. | 42| 9700005 | Calling startWork failed | 43 44**示例**： 45 46```ts 47 import { BusinessError } from '@kit.BasicServicesKit'; 48 49 let workInfo: workScheduler.WorkInfo = { 50 workId: 1, 51 batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, 52 isRepeat: false, 53 isPersisted: true, 54 bundleName: "com.example.myapplication", 55 abilityName: "MyExtension", 56 parameters: { 57 mykey0: 1, 58 mykey1: "string value", 59 mykey2: true, 60 mykey3: 1.5 61 } 62 } 63 try{ 64 workScheduler.startWork(workInfo); 65 console.info('workschedulerLog startWork success'); 66 } catch (error) { 67 console.error(`workschedulerLog startwork failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 68 } 69``` 70 71## workScheduler.stopWork 72 73stopWork(work: WorkInfo, needCancel?: boolean): void 74 75取消延迟任务。 76 77**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 78 79**参数**： 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ---------- | --------------------- | ---- | ---------- | 83| work | [WorkInfo](#workinfo) | 是 | 要停止或移除的延迟任务。 | 84| needCancel | boolean | 否 | 是否需要移除任务。<br>true表示停止并移除，false表示只停止不移除。默认为false。| 85 86**错误码**： 87 88以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 89 90| 错误码ID | 错误信息 | 91| ---- | --------------------- | 92| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 93| 9700001 | Memory operation failed. | 94| 9700002 | Parcel operation failed. | 95| 9700003 | System service operation failed. | 96| 9700004 | Check on workInfo failed. | 97 98**示例**： 99 100```ts 101 import { BusinessError } from '@kit.BasicServicesKit'; 102 103 let workInfo: workScheduler.WorkInfo = { 104 workId: 1, 105 batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, 106 isRepeat: false, 107 isPersisted: true, 108 bundleName: "com.example.myapplication", 109 abilityName: "MyExtension", 110 parameters: { 111 mykey0: 1, 112 mykey1: "string value", 113 mykey2: true, 114 mykey3: 1.5 115 } 116 } 117 try{ 118 workScheduler.stopWork(workInfo, false); 119 console.info('workschedulerLog stopWork success'); 120 } catch (error) { 121 console.error(`workschedulerLog stopWork failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 122 } 123``` 124 125## workScheduler.getWorkStatus 126 127getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void 128 129通过workId获取延迟任务，使用Callback异步回调。 130 131**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 132 133**参数**： 134 135| 参数名 | 类型 | 必填 | 说明 | 136| -------- | ------------------------------------- | ---- | ---------------------------------------- | 137| workId | number | 是 | 延迟任务Id。 | 138| callback | AsyncCallback\<[WorkInfo](#workinfo)> | 是 | 回调函数。如果workId有效，则返回从WorkSchedulerService获取的任务，否则抛出异常。 | 139 140**错误码**： 141 142以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 143 144| 错误码ID | 错误信息 | 145| ---- | --------------------- | 146| 401 | Parameter error. Possible causes: Parameter verification failed. | 147| 9700001 | Memory operation failed. | 148| 9700002 | Parcel operation failed. | 149| 9700003 | System service operation failed. | 150| 9700004 | Check on workInfo failed. | 151 152**示例**： 153 154```ts 155 import { BusinessError } from '@kit.BasicServicesKit'; 156 157 workScheduler.getWorkStatus(50, (error: BusinessError, res: workScheduler.WorkInfo) => { 158 if (error) { 159 console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`); 160 } else { 161 console.info(`workschedulerLog getWorkStatus success, ${JSON.stringify(res)}`); 162 } 163 }); 164``` 165 166## workScheduler.getWorkStatus 167 168getWorkStatus(workId: number): Promise\<WorkInfo> 169 170通过workId获取延迟任务，使用Promise异步回调。 171 172**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 173 174**参数**： 175 176| 参数名 | 类型 | 必填 | 说明 | 177| ------ | ------ | ---- | -------- | 178| workId | number | 是 | 延迟任务Id。 | 179 180**返回值**： 181 182| 类型 | 说明 | 183| ------------------------------- | ---------------------------------------- | 184| Promise\<[WorkInfo](#workinfo)> | Promise对象，如果workId有效，则返回从WorkSchedulerService获取的任务，否则抛出异常。 | 185 186**错误码**： 187 188以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 189 190| 错误码ID | 错误信息 | 191| ---- | --------------------- | 192| 401 | Parameter error. Possible causes: Parameter verification failed. | 193| 9700001 | Memory operation failed. | 194| 9700002 | Parcel operation failed. | 195| 9700003 | System service operation failed. | 196| 9700004 | Check on workInfo failed. | 197 198**示例**： 199 200```ts 201 import { BusinessError } from '@kit.BasicServicesKit'; 202 203 workScheduler.getWorkStatus(50).then((res: workScheduler.WorkInfo) => { 204 console.info(`workschedulerLog getWorkStatus success, ${JSON.stringify(res)}`); 205 }).catch((error: BusinessError) => { 206 console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`); 207 }) 208``` 209 210## workScheduler.obtainAllWorks<sup>deprecated<sup> 211 212obtainAllWorks(callback : AsyncCallback\<void>) : Array\<WorkInfo> 213> 从API version 10开始不再维护，建议使用[workScheduler.obtainAllWorks<sup>10+<sup>](#workschedulerobtainallworks10)替代 214 215获取当前应用所有的延迟任务，使用Callback异步回调。 216 217**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 218 219**参数**： 220 221| 参数名 | 类型 | 必填 | 说明 | 222| -------- | -------------------- | ---- | ------------------------------- | 223| callback | AsyncCallback\<void> | 是 | 回调函数，获取成功时，err为undefined，否则为错误对象。 | 224 225**错误码**： 226 227以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 228 229| 错误码ID | 错误信息 | 230| ---- | --------------------- | 231| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 232| 9700001 | Memory operation failed. | 233| 9700002 | Parcel operation failed. | 234| 9700003 | System service operation failed. | 235 236## workScheduler.obtainAllWorks<sup>10+<sup> 237 238obtainAllWorks(callback : AsyncCallback<Array<WorkInfo>>): void 239 240获取当前应用所有的延迟任务，使用Callback异步回调。 241 242**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 243 244**参数**： 245 246| 参数名 | 类型 | 必填 | 说明 | 247| -------- | -------------------- | ---- | ------------------------------- | 248| callback | AsyncCallback<Array<WorkInfo>> | 是 | 回调函数，获取成功时，err为undefined，否则为错误对象。 | 249 250**错误码**： 251 252以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 253 254| 错误码ID | 错误信息 | 255| ---- | --------------------- | 256| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 257| 9700001 | Memory operation failed. | 258| 9700002 | Parcel operation failed. | 259| 9700003 | System service operation failed. | 260 261**示例**： 262 263```ts 264 import { BusinessError } from '@kit.BasicServicesKit'; 265 266 workScheduler.obtainAllWorks((error: BusinessError, res: Array<workScheduler.WorkInfo>) =>{ 267 if (error) { 268 console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`); 269 } else { 270 console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`); 271 } 272 }); 273``` 274 275## workScheduler.obtainAllWorks 276 277obtainAllWorks(): Promise\<Array\<WorkInfo>> 278 279获取当前应用所有的延迟任务，使用Promise异步回调。 280 281**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 282 283**返回值**： 284 285| 类型 | 说明 | 286| -------------------------------------- | ------------------------------ | 287| Promise<Array\<[WorkInfo](#workinfo)>> | Promise对象，返回当前应用所有的延迟任务。 | 288 289**错误码**： 290 291以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 292 293| 错误码ID | 错误信息 | 294| ---- | --------------------- | 295| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 296| 9700001 | Memory operation failed. | 297| 9700002 | Parcel operation failed. | 298| 9700003 | System service operation failed. | 299 300**示例**： 301 302```ts 303 import { BusinessError } from '@kit.BasicServicesKit'; 304 305 workScheduler.obtainAllWorks().then((res: Array<workScheduler.WorkInfo>) => { 306 console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`); 307 }).catch((error: BusinessError) => { 308 console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`); 309 }) 310``` 311 312## workScheduler.stopAndClearWorks 313 314stopAndClearWorks(): void 315 316停止和取消当前应用所有的延迟任务。 317 318**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 319 320**错误码**： 321 322以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 323 324| 错误码ID | 错误信息 | 325| ---- | --------------------- | 326| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 327| 9700001 | Memory operation failed. | 328| 9700002 | Parcel operation failed. | 329| 9700003 | System service operation failed. | 330 331**示例**： 332 333```ts 334 import { BusinessError } from '@kit.BasicServicesKit'; 335 336 try{ 337 workScheduler.stopAndClearWorks(); 338 console.info(`workschedulerLog stopAndClearWorks success`); 339 } catch (error) { 340 console.error(`workschedulerLog stopAndClearWorks failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 341 } 342``` 343 344## workScheduler.isLastWorkTimeOut<sup>deprecated<sup> 345 346isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean 347 348> 从API version 10开始不再维护，建议使用[workScheduler.isLastWorkTimeOut<sup>10+<sup>](#workschedulerislastworktimeout10)替代 349 350检查延迟任务的最后一次执行是否超时，使用Callback异步回调。 351 352**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 353 354**参数**： 355 356| 参数名 | 类型 | 必填 | 说明 | 357| -------- | -------------------- | ---- | ---------------------------------------- | 358| workId | number | 是 | 指定延迟任务的Id。 | 359| callback | AsyncCallback\<void> | 是 | 回调函数。 | 360 361**错误码**： 362 363以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 364 365| 错误码ID | 错误信息 | 366| ---- | --------------------- | 367| 401 | Parameter error. Possible causes: Parameter verification failed. | 368| 9700001 | Memory operation failed. | 369| 9700002 | Parcel operation failed. | 370| 9700003 | System service operation failed. | 371| 9700004 | Check on workInfo failed. | 372 373## workScheduler.isLastWorkTimeOut<sup>10+<sup> 374 375isLastWorkTimeOut(workId: number, callback : AsyncCallback\<boolean>): void 376 377检查延迟任务的最后一次执行是否超时，使用Callback异步回调。 378 379**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 380 381**参数**： 382 383| 参数名 | 类型 | 必填 | 说明 | 384| -------- | -------------------- | ---- | ---------------------------------------- | 385| workId | number | 是 | 指定延迟任务的Id。 | 386| callback | AsyncCallback\<boolean> | 是 | 回调函数。 | 387 388**错误码**： 389 390以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 391 392| 错误码ID | 错误信息 | 393| ---- | --------------------- | 394| 401 | Parameter error. Possible causes: Parameter verification failed. | 395| 9700001 | Memory operation failed. | 396| 9700002 | Parcel operation failed. | 397| 9700003 | System service operation failed. | 398| 9700004 | Check on workInfo failed. | 399 400**示例**： 401 402```ts 403 import { BusinessError } from '@kit.BasicServicesKit'; 404 405 workScheduler.isLastWorkTimeOut(500, (error: BusinessError, res: boolean) =>{ 406 if (error) { 407 console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`); 408 } else { 409 console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`); 410 } 411 }); 412``` 413 414## workScheduler.isLastWorkTimeOut 415 416isLastWorkTimeOut(workId: number): Promise\<boolean> 417 418检查延迟任务的最后一次执行是否超时，使用Promise形式返回。 419 420**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 421 422**参数**： 423 424| 参数名 | 类型 | 必填 | 说明 | 425| ------ | ------ | ---- | -------- | 426| workId | number | 是 | 指定延迟任务的Id。 | 427 428**返回值**： 429 430| 类型 | 说明 | 431| ----------------- | ---------------------------------------- | 432| Promise\<boolean> | Promise对象。返回true表示指定任务的最后一次执行超时，false表示未超时。 | 433 434**错误码**： 435 436以下错误码的详细介绍请参见[workScheduler错误码](errorcode-workScheduler.md)和[通用错误码](../errorcode-universal.md)。 437 438| 错误码ID | 错误信息 | 439| ---- | --------------------- | 440| 401 | Parameter error. Possible causes: Parameter verification failed. | 441| 9700001 | Memory operation failed. | 442| 9700002 | Parcel operation failed. | 443| 9700003 | System service operation failed. | 444| 9700004 | Check on workInfo failed. | 445 446**示例**： 447 448```ts 449 import { BusinessError } from '@kit.BasicServicesKit'; 450 451 workScheduler.isLastWorkTimeOut(500) 452 .then((res: boolean) => { 453 console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`); 454 }) 455 .catch((error: BusinessError) => { 456 console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`); 457 }); 458``` 459 460## WorkInfo 461 462延迟任务的具体信息。 463 464**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 465 466| 名称 | 类型 | 必填 | 说明 | 467| --------------- | --------------------------------- | ---- | ---------------- | 468| workId | number | 是 | 延迟任务ID。 | 469| bundleName | string | 是 | 延迟任务所在应用的包名。 | 470| abilityName | string | 是 | 包内ability名称。 | 471| networkType | [NetworkType](#networktype) | 否 | 网络类型。 | 472| isCharging | boolean | 否 | 是否充电。<br>- true表示充电触发延迟回调，false表示不充电触发延迟回调。| 473| chargerType | [ChargingType](#chargingtype) | 否 | 充电类型。 | 474| batteryLevel | number | 否 | 电量。 | 475| batteryStatus | [BatteryStatus](#batterystatus) | 否 | 电池状态。 | 476| storageRequest | [StorageRequest](#storagerequest) | 否 | 存储状态。 | 477| isRepeat | boolean | 否 | 是否循环任务。<br>- true表示循环任务，false表示非循环任务。 | 478| repeatCycleTime | number | 否 | 循环间隔，单位为毫秒。 | 479| repeatCount | number | 否 | 循环次数。 | 480| isPersisted | boolean | 否 | 注册的延迟任务是否可保存在系统中。<br>- true表示可保存，即系统重启后，任务可恢复。false表示不可保存。| 481| isDeepIdle | boolean | 否 | 是否要求设备进入空闲状态。<br>- true表示需要，false表示不需要。 | 482| idleWaitTime | number | 否 | 空闲等待时间，单位为毫秒。 | 483| parameters | Record<string, number \| string \| boolean> | 否 | 携带参数信息。 | 484 485## NetworkType 486 487触发延迟回调的网络类型。 488 489**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 490 491| 名称 | 值 | 说明 | 492| ---------------------- | ---- | ----------------------- | 493| NETWORK_TYPE_ANY | 0 | 表示这个触发条件是任何类型的网络连接。 | 494| NETWORK_TYPE_MOBILE | 1 | 表示这个触发条件是Mobile网络连接。 | 495| NETWORK_TYPE_WIFI | 2 | 表示这个触发条件是Wifi类型的网络连接。 | 496| NETWORK_TYPE_BLUETOOTH | 3 | 表示这个触发条件是Bluetooth网络连接。 | 497| NETWORK_TYPE_WIFI_P2P | 4 | 表示这个触发条件是Wifi P2P网络连接。 | 498| NETWORK_TYPE_ETHERNET | 5 | 表示这个触发条件是有线网络连接。 | 499 500## ChargingType 501 502触发延迟回调的充电类型。 503 504**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 505 506| 名称 | 值 | 说明 | 507| ------------------------- | ---- | -------------------- | 508| CHARGING_PLUGGED_ANY | 0 | 表示这个触发条件是任何类型的充电器连接。 | 509| CHARGING_PLUGGED_AC | 1 | 表示这个触发条件是直流充电器连接。 | 510| CHARGING_PLUGGED_USB | 2 | 表示这个触发条件是USB充连接。 | 511| CHARGING_PLUGGED_WIRELESS | 3 | 表示这个触发条件是无线充电器连接。 | 512 513## BatteryStatus 514 515触发延迟回调的电池状态。 516 517**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 518 519| 名称 | 值 | 说明 | 520| -------------------------- | ---- | -------------------------- | 521| BATTERY_STATUS_LOW | 0 | 表示这个触发条件是低电告警。 | 522| BATTERY_STATUS_OKAY | 1 | 表示这个触发条件是从低电恢复到正常电量。 | 523| BATTERY_STATUS_LOW_OR_OKAY | 2 | 表示这个触发条件是从低电恢复到正常电量或者低电告警。 | 524 525## StorageRequest 526 527触发延迟回调的存储状态。 528 529**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 530 531| 名称 | 值 | 说明 | 532| ------------------------- | ---- | ------------------------------ | 533| STORAGE_LEVEL_LOW | 0 | 表示这个触发条件是存储空间不足。 | 534| STORAGE_LEVEL_OKAY | 1 | 表示这个触发条件是从存储空间不足恢复到正常。 | 535| STORAGE_LEVEL_LOW_OR_OKAY | 2 | 表示这个触发条件是存储空间不足或者从存储空间不足恢复到正常。 |