1# 延迟任务 2 3## 概述 4 5### 功能介绍 6 7应用退至后台后，需要执行实时性要求不高的任务，例如有网络时不定期主动获取邮件等，可以使用延迟任务。当应用满足设定条件（包括网络类型、充电类型、存储状态、电池状态、定时状态等）时，将任务添加到执行队列，系统会根据内存、功耗、设备温度、用户使用习惯等统一调度拉起应用。 8 9### 运行原理 10 11**图1** 延迟任务实现原理 12 13 14应用调用延迟任务接口注册、删除、查询延迟任务，延迟任务管理模块会根据任务设置的条件（通过WorkInfo参数设置，包括网络类型、充电类型、存储状态等）和系统状态（包括内存、功耗、设备温度、用户使用习惯等）统一决策调度时机。 15 16当满足调度条件或调度结束时，系统会回调应用[WorkSchedulerExtensionAbility](../reference/apis/js-apis-WorkSchedulerExtensionAbility.md)中 onWorkStart() 或 onWorkStop() 的方法，同时会为应用单独创建一个Extension扩展进程用以承载[WorkSchedulerExtensionAbility](../reference/apis/js-apis-WorkSchedulerExtensionAbility.md)，并给[WorkSchedulerExtensionAbility](../reference/apis/js-apis-WorkSchedulerExtensionAbility.md)一定的活动周期，开发者可以在对应回调方法中实现自己的任务逻辑。 17 18 19### 约束与限制 20 21- **数量限制**：一个应用同一时刻最多申请10个延迟任务。 22 23- **执行频率限制**：系统会根据[应用的活跃分组](../reference/apis/js-apis-resourceschedule-deviceUsageStatistics.md)，对延迟任务做分级管控，限制延迟任务调度的执行频率。通过能效资源接口申请了WORK_SCHEDULER资源的应用，会被放在能效资源豁免分组中。 24 25 **表1** 应用活跃程度分组 26 | 应用活跃分组 | 延迟任务执行频率 | 27 | -------- | -------- | 28 | 活跃分组 | 最小间隔2小时 | 29 | 经常使用分组 | 最小间隔4小时 | 30 | 常用使用 | 最小间隔24小时 | 31 | 极少使用分组 | 最小间隔48小时 | 32 | 受限使用分组 | 禁止 | 33 | 从未使用分组 | 禁止 | 34 | 能效资源豁免分组 | 不受限制 | 35 36- **超时**：WorkSchedulerExtensionAbility单次回调最长运行2分钟。如果超时不取消，系统会终止对应的Extension进程。对于系统特权应用，可以通过能效资源接口申请WORK_SCHEDULER资源，扩展单次回调运行时长，扩展后在充电状态下为20分钟，非充电状态下为10分钟。 37 38- **调度延迟**：系统会根据内存、功耗、设备温度、用户使用习惯等统一调度，如当系统内存资源不足或温度达到一定挡位时，系统将延迟调度该任务。 39 40- **WorkSchedulerExtensionAbility接口调用限制**：为实现对WorkSchedulerExtensionAbility能力的管控，在WorkSchedulerExtensionAbility中限制以下接口的调用： 41 42 [@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../reference/apis/js-apis-resourceschedule-backgroundTaskManager.md) 43 44 [@ohos.backgroundTaskManager (后台任务管理)](../reference/apis/js-apis-backgroundTaskManager.md) 45 46 [@ohos.multimedia.camera (相机管理)](../reference/apis/js-apis-camera.md) 47 48 [@ohos.multimedia.audio (音频管理)](../reference/apis/js-apis-audio.md) 49 50 [@ohos.multimedia.media (媒体服务)](../reference/apis/js-apis-media.md) 51 52 53## 接口说明 54 55**表2** 延迟任务主要接口 56 57以下是延迟任务开发使用的相关接口，更多接口及使用方式请见[延迟任务](../reference/apis/js-apis-resourceschedule-workScheduler.md)文档。 58| 接口名 | 接口描述 | 59| -------- | -------- | 60| startWork(work: WorkInfo): void; | 申请延迟任务 | 61| stopWork(work: WorkInfo, needCancel?: boolean): void; | 取消延迟任务 | 62| getWorkStatus(workId: number, callback: AsyncCallback<WorkInfo>): void; | 获取延迟任务状态（Callback形式） | 63| getWorkStatus(workId: number): Promise<WorkInfo>; | 获取延迟任务状态（Promise形式） | 64| obtainAllWorks(callback: AsyncCallback<void>): Array<WorkInfo>; | 获取所有延迟任务（Callback形式） | 65| obtainAllWorks(): Promise<Array<WorkInfo>>; | 获取所有延迟任务（Promise形式） | 66| stopAndClearWorks(): void; | 停止并清除任务 | 67| isLastWorkTimeOut(workId: number, callback: AsyncCallback<void>): boolean; | 获取上次任务是否超时（针对RepeatWork，Callback形式） | 68| isLastWorkTimeOut(workId: number): Promise<boolean>; | 获取上次任务是否超时（针对RepeatWork，Promise形式） | 69 70**表3** WorkInfo参数 71| 名称 | 类型 | 必填 | 说明 | 72| --------------- | --------------------------------- | ---- | ---------------- | 73| workId | number | 是 | 延迟任务ID。 | 74| bundleName | string | 是 | 延迟任务包名。 | 75| abilityName | string | 是 | 延迟任务回调通知的组件名。 | 76| networkType | [NetworkType](../reference/apis/js-apis-resourceschedule-workScheduler.md#networktype) | 否 | 网络类型。 | 77| isCharging | boolean | 否 | 是否充电。<br>- true表示充电触发延迟回调，false表示不充电触发延迟回调。| 78| chargerType | [ChargingType](../reference/apis/js-apis-resourceschedule-workScheduler.md#chargingtype) | 否 | 充电类型。 | 79| batteryLevel | number | 否 | 电量。 | 80| batteryStatus | [BatteryStatus](../reference/apis/js-apis-resourceschedule-workScheduler.md#batterystatus) | 否 | 电池状态。 | 81| storageRequest | [StorageRequest](../reference/apis/js-apis-resourceschedule-workScheduler.md#storagerequest) | 否 | 存储状态。 | 82| isRepeat | boolean | 否 | 是否循环任务。<br>- true表示循环任务，false表示非循环任务。 | 83| repeatCycleTime | number | 否 | 循环间隔，单位为毫秒。 | 84| repeatCount | number | 否 | 循环次数。 | 85| isPersisted | boolean | 否 | 是否持久化保存工作。<br>- true表示持久化保存工作。false表示非持久化保存工作。| 86| isDeepIdle | boolean | 否 | 是否要求设备进入空闲状态。<br>- true表示需要，false表示不需要。 | 87| idleWaitTime | number | 否 | 空闲等待时间，单位为毫秒。 | 88| parameters | [key: string]: number \| string \| boolean | 否 | 携带参数信息。 | 89 90WorkInfo参数用于设置应用条件，参数设置时需遵循以下规则： 91 92- workId、bundleName、abilityName为必填项，bundleName需为本应用包名。 93 94- 携带参数信息仅支持number、string、boolean三种类型。 95 96- 至少设置一个满足的条件，包括网络类型、充电类型、存储状态、电池状态、定时状态等。 97 98- 对于重复任务，任务执行间隔至少20分钟。设置重复任务时间间隔时，须同时设置是否循环或循环次数中的一个。 99 100**表4** 延迟任务回调接口 101 102以下是延迟任务回调开发使用的相关接口，更多接口及使用方式请见[延迟任务回调](../reference/apis/js-apis-WorkSchedulerExtensionAbility.md)文档。 103| 接口名 | 接口描述 | 104| -------- | -------- | 105| onWorkStart(work: workScheduler.WorkInfo): void | 延迟调度任务开始的回调 | 106| onWorkStop(work: workScheduler.WorkInfo): void | 延迟调度任务结束的回调 | 107 108 109## 开发步骤 110 111延迟任务调度开发步骤分为两步：实现延迟任务调度扩展能力、实现延迟任务调度。 112 1131. **延迟任务调度扩展能力**：实现WorkSchedulerExtensionAbility开始和结束的回调接口。 114 1152. **延迟任务调度**：调用延迟任务接口，实现延迟任务申请、取消等功能。 116 117### 实现延迟任务回调拓展能力 118 1191. 新建工程目录。 120 121 在工程entry Module对应的ets目录(./entry/src/main/ets)下，新建目录及ArkTS文件，例如新建一个目录并命名为extension。在extension目录下，新建一个ArkTS文件并命名为WorkSchedulerExtension.ets，用以实现延迟任务回调接口。 122 1232. 导入模块。 124 125 ```ts 126 import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; 127 import workScheduler from '@ohos.resourceschedule.workScheduler'; 128 ``` 129 1303. 实现WorkSchedulerExtension生命周期接口。 131 132 ```ts 133 export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { 134 // 延迟任务开始回调 135 onWorkStart(workInfo: workScheduler.WorkInfo) { 136 console.info(`onWorkStart, workInfo = ${JSON.stringify(workInfo)}`); 137 } 138 139 // 延迟任务结束回调 140 onWorkStop(workInfo: workScheduler.WorkInfo) { 141 console.info(`onWorkStop, workInfo is ${JSON.stringify(workInfo)}`); 142 } 143 } 144 ``` 145 1464. 在[module.json5配置文件](../quick-start/module-configuration-file.md)中注册WorkSchedulerExtensionAbility，并设置如下标签： 147 148 - type标签设置为“workScheduler”。 149 150 - srcEntry标签设置为当前ExtensionAbility组件所对应的代码路径。 151 152 ```json 153 { 154 "module": { 155 "extensionAbilities": [ 156 { 157 "name": "MyWorkSchedulerExtensionAbility", 158 "srcEntry": "./ets/WorkSchedulerExtension/WorkSchedulerExtension.ets", 159 "label": "$string:WorkSchedulerExtensionAbility_label", 160 "description": "$string:WorkSchedulerExtensionAbility_desc", 161 "type": "workScheduler" 162 } 163 ] 164 } 165 } 166 ``` 167 168 169### 实现延迟任务调度 170 1711. 导入模块。 172 173 ```ts 174 import workScheduler from '@ohos.resourceschedule.workScheduler'; 175 import { BusinessError } from '@ohos.base'; 176 ``` 177 1782. 申请延迟任务。 179 180 ```ts 181 const workInfo: workScheduler.WorkInfo = { 182 workId: 1, 183 networkType: workScheduler.NetworkType.NETWORK_TYPE_WIFI, 184 bundleName: 'com.example.application', 185 abilityName: 'MyWorkSchedulerExtensionAbility' 186 } 187 188 try { 189 workScheduler.startWork(workInfo); 190 console.info(`startWork success`); 191 } catch (error) { 192 console.error(`startWork failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 193 } 194 ``` 195 1963. 取消延迟任务。 197 198 ```ts 199 const workInfo: workScheduler.WorkInfo = { 200 workId: 1, 201 networkType: workScheduler.NetworkType.NETWORK_TYPE_WIFI, 202 bundleName: 'com.example.application', 203 abilityName: 'MyWorkSchedulerExtensionAbility' 204 } 205 206 try { 207 workScheduler.stopWork(workInfo); 208 console.info(`stopWork success`); 209 } catch (error) { 210 console.error(`stopWork failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 211 } 212 ``` 213 214## 相关实例 215 216针对延迟任务调度的开发，有以下相关示例可供参考： 217 218- [延迟任务调度（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Release/code/BasicFeature/TaskManagement/WorkScheduler)
