1# 延迟任务调度 2 3本模块提供延迟任务注册、取消、查询的能力。 4 5开发者在开发应用时，通过调用延迟任务注册接口，注册对实时性要求不高的延迟任务，该任务默认由系统安排，在系统空闲时根据性能、功耗、热等情况进行调度执行。 6 7>  **说明：** 8> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 9 10 11## 导入模块 12 13``` 14import workScheduler from '@ohos.workScheduler' 15``` 16 17## workScheduler.startWork 18startWork(work: WorkInfo): boolean 19 20通知WorkSchedulerService将工作添加到执行队列。 21 22**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 23 24**参数**： 25 26| 参数名 | 类型 | 必填 | 说明 | 27| ---- | --------------------- | ---- | -------------- | 28| work | [WorkInfo](#workinfo) | 是 | 指示要添加到执行队列的工作。 | 29 30**返回值**： 31 32| 类型 | 说明 | 33| ------- | -------------------------------- | 34| boolean | 如果工作成功添加到执行队列，则返回true，否则返回false。 | 35 36**示例**： 37 38``` 39 let workInfo = { 40 workId: 1, 41 batteryLevel:50, 42 batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, 43 isRepeat: false, 44 isPersisted: true, 45 bundleName: "com.example.myapplication", 46 abilityName: "MyExtension" 47 } 48 var res = workScheduler.startWork(workInfo); 49 console.info("workschedulerLog res:" + res); 50``` 51 52## workScheduler.stopWork 53stopWork(work: WorkInfo, needCancel?: boolean): boolean 54 55通知WorkSchedulerService停止指定工作。 56 57**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 58 59**参数**： 60 61| 参数名 | 类型 | 必填 | 说明 | 62| ---------- | --------------------- | ---- | ---------- | 63| work | [WorkInfo](#workinfo) | 是 | 指示要停止的工作。 | 64| needCancel | boolean | 是 | 是否需要取消的工作。 | 65 66**返回值**： 67 68| 类型 | 说明 | 69| ------- | ----------------------- | 70| boolean | 如果成功，则返回true，否则返回false。 | 71 72**示例**： 73 74``` 75 let workInfo = { 76 workId: 1, 77 batteryLevel:50, 78 batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, 79 isRepeat: false, 80 isPersisted: true, 81 bundleName: "com.example.myapplication", 82 abilityName: "MyExtension" 83 } 84 var res = workScheduler.stopWork(workInfo, false); 85 console.info("workschedulerLog res:" + res); 86``` 87 88## workScheduler.getWorkStatus 89getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void 90 91获取工作的最新状态，使用Callback形式返回。 92 93**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 94 95**参数**： 96 97| 参数名 | 类型 | 必填 | 说明 | 98| -------- | ------------------------------------- | ---- | ---------------------------------------- | 99| workId | number | 是 | work的id。 | 100| callback | AsyncCallback\<[WorkInfo](#workinfo)> | 是 | 指定的callback回调方法。如果指定的工作Id有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。 | 101 102**示例**： 103 104``` 105 workScheduler.getWorkStatus(50, (err, res) => { 106 if (err) { 107 console.info('workschedulerLog getWorkStatus failed, because:' + err.data); 108 } else { 109 for (let item in res) { 110 console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); 111 } 112 } 113 }); 114``` 115 116## workScheduler.getWorkStatus 117getWorkStatus(workId: number): Promise\<WorkInfo> 118 119获取工作的最新状态，使用Promise形式返回。 120 121**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 122 123**参数**： 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ------ | ------ | ---- | -------- | 127| workId | number | 是 | work的id。 | 128 129**返回值**： 130 131| 类型 | 说明 | 132| ------------------------------- | ---------------------------------------- | 133| Promise\<[WorkInfo](#workinfo)> | 指定的Promise回调方法。如果指定的工作ID有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。 | 134 135**示例**： 136 137``` 138 workScheduler.getWorkStatus(50).then((res) => { 139 for (let item in res) { 140 console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); 141 } 142 }).catch((err) => { 143 console.info('workschedulerLog getWorkStatus failed, because:' + err.data); 144 }) 145``` 146 147## workScheduler.obtainAllWorks 148obtainAllWorks(callback : AsyncCallback\<void>): Array\<WorkInfo> 149 150获取与当前应用程序关联的所有工作，使用Callback形式返回。 151 152**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 153 154**参数**： 155 156| 参数名 | 类型 | 必填 | 说明 | 157| -------- | -------------------- | ---- | ------------------------------- | 158| callback | AsyncCallback\<void> | 是 | 指定的callback回调方法。返回与应用程序关联的所有工作。 | 159 160**返回值**： 161 162| 类型 | 说明 | 163| ----------------------------- | --------------- | 164| Array\<[WorkInfo](#workinfo)> | 返回与应用程序关联的所有工作。 | 165 166**示例**： 167 168``` 169 workScheduler.obtainAllWorks((err, res) =>{ 170 if (err) { 171 console.info('workschedulerLog obtainAllWorks failed, because:' + err.data); 172 } else { 173 console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); 174 } 175 }); 176``` 177 178## workScheduler.obtainAllWorks 179obtainAllWorks(): Promise<Array\<WorkInfo>> 180 181获取与当前应用程序关联的所有工作，使用Promise形式返回。 182 183**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 184 185**返回值**： 186 187| 类型 | 说明 | 188| -------------------------------------- | ------------------------------ | 189| Promise<Array\<[WorkInfo](#workinfo)>> | 指定的Promise回调方法。返回与应用程序关联的所有工作。 | 190 191**示例**： 192 193``` 194 workScheduler.obtainAllWorks().then((res) => { 195 console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); 196 }).catch((err) => { 197 console.info('workschedulerLog obtainAllWorks failed, because:' + err.data); 198 }) 199``` 200 201## workScheduler.stopAndClearWorks 202stopAndClearWorks(): boolean 203 204停止和取消与当前应用程序关联的所有工作。 205 206**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 207 208**示例**： 209 210``` 211 let res = workScheduler.stopAndClearWorks(); 212 console.info("workschedulerLog res:" + res); 213``` 214 215## workScheduler.isLastWorkTimeOut 216isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean 217 218检查指定工作的最后一次执行是否为超时操作，使用Callback形式返回。 219 220**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 221 222**参数**： 223 224| 参数名 | 类型 | 必填 | 说明 | 225| -------- | -------------------- | ---- | ---------------------------------------- | 226| workId | number | 是 | work的id。 | 227| callback | AsyncCallback\<void> | 是 | 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 | 228 229**返回值**： 230 231| 类型 | 说明 | 232| ------- | ---------------------------------------- | 233| boolean | 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 | 234 235**示例**： 236 237``` 238 workScheduler.isLastWorkTimeOut(500, (err, res) =>{ 239 if (err) { 240 console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data); 241 } else { 242 console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); 243 } 244 }); 245``` 246 247## workScheduler.isLastWorkTimeOut 248isLastWorkTimeOut(workId: number): Promise\<boolean> 249 250检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。 251 252**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler 253 254**参数**： 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------ | ------ | ---- | -------- | 258| workId | number | 是 | work的id。 | 259 260**返回值**： 261 262| 类型 | 说明 | 263| ----------------- | ---------------------------------------- | 264| Promise\<boolean> | 指定的Promise回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 | 265 266**示例**： 267 268``` 269 workScheduler.isLastWorkTimeOut(500) 270 .then(res => { 271 console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); 272 }) 273 .catch(err => { 274 console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data); 275 }); 276``` 277 278## WorkInfo 279提供工作的具体信息。WorkInfo设置参数约束见[延迟任务调度概述](../../task-management/work-scheduler-overview.md) 280 281**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.WorkScheduler 282 283| 参数名 | 类型 | 必填 | 说明 | 284| --------------- | --------------------------------- | ---- | -------------------------------- | 285| workId | number | 是 | 当前工作的ID | 286| bundleName | string | 是 | 延迟任务包名 | 287| abilityName | string | 是 | 延迟任务回调通知的组件名（必填） | 288| networkType | [NetworkType](#networktype) | 否 | 网络类型 | 289| isCharging | boolean | 否 | 是否充电 | 290| chargerType | [ChargingType](#chargingtype) | 否 | 充电类型 | 291| batteryLevel | number | 否 | 电量 | 292| batteryStatus | [BatteryStatus](#batterystatus) | 否 | 电池状态 | 293| storageRequest | [StorageRequest](#storagerequest) | 否 | 存储状态 | 294| isRepeat | boolean | 否 | 是否循环任务 | 295| repeatCycleTime | number | 否 | 循环间隔 | 296| repeatCount | number | 否 | 循环次数 | 297| isPersisted | boolean | 否 | 是否持久化保存工作 | 298 299## NetworkType 300触发工作的网络类型。 301 302**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.WorkScheduler 303 304| 名称 | 默认值 | 说明 | 305| ---------------------- | ---- | ----------------------- | 306| NETWORK_TYPE_ANY | 0 | 表示这个触发条件是任何类型的网络连接。 | 307| NETWORK_TYPE_MOBILE | 1 | 表示这个触发条件是Mobile网络连接。 | 308| NETWORK_TYPE_WIFI | 2 | 表示这个触发条件是Wifi类型的网络连接。 | 309| NETWORK_TYPE_BLUETOOTH | 3 | 表示这个触发条件是Bluetooth网络连接。 | 310| NETWORK_TYPE_WIFI_P2P | 4 | 表示这个触发条件是Wifi P2P网络连接。 | 311| NETWORK_TYPE_ETHERNET | 5 | 表示这个触发条件是有线网络连接。 | 312 313## ChargingType 314触发工作的充电类型。 315 316**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.WorkScheduler 317 318| 名称 | 默认值 | 说明 | 319| ------------------------- | ---- | -------------------- | 320| CHARGING_PLUGGED_ANY | 0 | 表示这个触发条件是任何类型的充电器连接。 | 321| CHARGING_PLUGGED_AC | 1 | 表示这个触发条件是直流充电器连接。 | 322| CHARGING_PLUGGED_USB | 2 | 表示这个触发条件是USB充连接。 | 323| CHARGING_PLUGGED_WIRELESS | 3 | 表示这个触发条件是无线充电器连接。 | 324 325## BatteryStatus 326触发工作的电池状态。 327 328**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.WorkScheduler 329 330| 名称 | 默认值 | 说明 | 331| -------------------------- | ---- | -------------------------- | 332| BATTERY_STATUS_LOW | 0 | 表示这个触发条件是低电告警。 | 333| BATTERY_STATUS_OKAY | 1 | 表示这个触发条件是从低电恢复到正常电量。 | 334| BATTERY_STATUS_LOW_OR_OKAY | 2 | 表示这个触发条件是从低电恢复到正常电量或者低电告警。 | 335 336## StorageRequest 337触发工作的存储状态。 338 339**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.WorkScheduler 340 341 |名称 |默认值 |说明| 342 | -------- | -------- | -------- | 343 |STORAGE_LEVEL_LOW |0 |表示这个触发条件是存储空间不足。 344 |STORAGE_LEVEL_OKAY |1 |表示这个触发条件是从存储空间不足恢复到正常。 345 |STORAGE_LEVEL_LOW_OR_OKAY |2 |表示这个触发条件是从存储空间不足恢复到正常或者存储空间不足。
