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