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