diff --git a/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md b/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md index 7f469e6ad9d9269321ab85db6e7c7d9a8be2cce0..cb735794bdf0e6812b048963a653ad75a09596b3 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md +++ b/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md @@ -11,284 +11,321 @@ import workScheduler from '@ohos.workScheduler' ``` ## 系统能力 -SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask +SystemCapability.ResourceSchedule.WorkScheduler +## workScheduler.startWork -## 权限列表 +workScheduler.startWork(work: WorkInfo): boolean -长时任务需要申请如下权限： +通知WorkSchedulerService将工作添加到执行队列。 -ohos.permission.KEEP_BACKGROUND_RUNNING +- **参数**： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | work | WorkInfo | 是 | 指示要添加到执行队列的工作。 | -## backgroundTaskManager.requestSuspendDelay +- **返回值**： -requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo + | 类型 | 说明 | + | -------- | -------- | + | boolean | 如果工作成功添加到执行队列，则返回true，否则返回false。 | -后台应用申请延迟挂起。 +- **示例**： + + ``` + let workInfo = { + workId: 1, + batteryLevel:50, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension" + } + var res = workScheduler.startWork(workInfo); + console.info("workschedulerLog res:" + res); + ``` + +## workScheduler.stopWork + +stopWork(work: WorkInfo, needCancel?: boolean): boolean + +通知WorkSchedulerService停止指定工作。 -延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 - **参数**： + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | reason | string | 是 | 延迟挂起申请的原因。 | - | callback | Callback<void> | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 | + | work | WorkInfo | 是 | 指示要添加到执行队列的工作。 | + |needCancel|boolean| 是| 是否需要取消的工作。| - **返回值**： + | 类型 | 说明 | | -------- | -------- | - | [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | + | boolean | 如果成功，则返回true，否则返回false。 | - **示例**： + ``` - let myReason = 'test requestSuspendDelay'; - let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { - console.info("Request suspension delay will time out."); - }) + let workInfo = { + workId: 1, + batteryLevel:50, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension" + } + var res = workScheduler.stopWork(workInfo, false); + console.info("workschedulerLog res:" + res); ``` +## workScheduler.getWorkStatus -## backgroundTaskManager.getRemainingDelayTime +getWorkStatus(workId: number, callback : AsyncCallback): void -getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void +获取工作的最新状态，使用callback形式返回。 -获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 - **参数**： + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | requestId | number | 是 | 延迟挂起的请求ID。 | - | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | + | workId | number | 是 | work的id。 | + |callback|AsyncCallback| 是| 指定的callback回调方法。如果指定的工作Id有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。| + - **示例**： + ``` - let id = 1; - backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { - if(err.data === 0) { - console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + workScheduler.getWorkStatus(50, (err, res) => { + if (err) { + console.info('workschedulerLog getWorkStatus callback failed, because:' + err.data); } else { - console.log('promise => Operation failed. Cause: ' + err.data); + for (let item in res) { + console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]); + } } - }) + }); ``` +## workScheduler.getWorkStatus -## backgroundTaskManager.getRemainingDelayTime - -getRemainingDelayTime(requestId: number): Promise<number> +getWorkStatus(workID: number): Promise -获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 +获取工作的最新状态，使用Promise形式返回。 - **参数**： + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | requestId | number | 是 | 延迟挂起的请求ID。 | + | workId | number | 是 | work的id。 | - **返回值**： + | 类型 | 说明 | | -------- | -------- | - | Promise<number> | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | + | Promise | 指定的Promise回调方法。如果指定的工作ID有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。 | - **示例**： + ``` - let id = 1; - backgroundTaskManager.getRemainingDelayTime(id).then( res => { - console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); - }).catch( err => { - console.log('promise => Operation failed. Cause: ' + err.data); - }) + workScheduler.getWorkStatus(50).then((res) => { + for (let item in res) { + console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]); + } + }).catch((err) => { + console.info('workschedulerLog getWorkStatus promise failed, err'); + console.info('workschedulerLog getWorkStatus promise failed, because:' + err.data); + }) ``` +## workScheduler.obtainAllWorks -## backgroundTaskManager.cancelSuspendDelay +obtainAllWorks(callback : AsyncCallback): Array -cancelSuspendDelay(requestId: number): void - -取消延迟挂起。 +获取与当前应用程序关联的所有工作，使用callback形式返回。 - **参数**： + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | requestId | number | 是 | 延迟挂起的请求ID。 | - -- **示例**： - ``` - backgroundTaskManager.cancelSuspendDelay(id); - ``` + |callback|AsyncCallback| 是| 指定的callback回调方法。返回与应用程序关联的所有工作。| -#### DelaySuspendInfo - -延迟挂起信息。 +- **返回值**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| requestId | number | 是 | 延迟挂起的请求ID。 | -| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。
一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | + | 类型 | 说明 | + | -------- | -------- | + | Array | 返回与应用程序关联的所有工作。 | -## backgroundTaskManager.startBackgroundRunning +- **示例**： -[8] startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void; + ``` + workScheduler.obtainAllWorks((err, res) =>{ + if (err) { + console.info('workschedulerLog getWorkStatus promise failed, err'); + console.info('workschedulerLog getWorkStatus promise failed, because:' + err.data); + } else { + console.info('workschedulerLog obtainAllWorks callback success, data is:' + JSON.stringify(res)); + } + }); + ``` -向系统申请长时任务，使用callback形式返回结果。 +## workScheduler.obtainAllWorks -- **参数**： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | - | bgMode | BackgroundMode | 是 | 向系统申请的后台模式 | - | wantAgent | WantAgent | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。使用方式参考：[8] | - | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | +obtainAllWorks(): Promise> -- **示例**： -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; -import featureAbility from '@ohos.ability.featureAbility'; -import wantAgent from '@ohos.wantAgent'; - -function callback(err, data) { - if (err) { - console.error("Operation failed Cause: " + err); - } else { - console.info("Operation succeeded"); - } -} - -let wantAgentInfo = { - wants: [ - { - bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility" - } - ], - operationType: wantAgent.OperationType.START_ABILITY, - requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] -}; +获取与当前应用程序关联的所有工作，使用Promise形式返回。 -wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback) -}); +- **返回值**： -``` + | 类型 | 说明 | + | -------- | -------- | + | Promise> | 指定的Promise回调方法。返回与应用程序关联的所有工作。| -## backgroundTaskManager.startBackgroundRunning +- **示例**： -[8] startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> + ``` + workScheduler.obtainAllWorks().then((res) => { + console.info('workschedulerLog obtainAllWorks promise success, data is:' + JSON.stringify(res)); + }).catch((err) => { + console.info('workschedulerLog obtainAllWorks promise failed, because:' + err.data); + }) + ``` -向系统申请长时任务，使用promise形式返回结果。 +## workScheduler.stopAndClearWorks -- **参数**： - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | - | bgMode | BackgroundMode | 是 | 向系统申请的后台模式 | - | wantAgent | WantAgent | 是 | 通知参数，用于指定长时任务通知点击跳转的界面 | +stopAndClearWorks(): boolean -- **返回值** - | 类型 | 说明 | - | -------------- | ------------------------- | - | Promise\ | 使用Promise形式返回结果。 | +停止和取消与当前应用程序关联的所有工作。 - **示例**： -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; -import featureAbility from '@ohos.ability.featureAbility'; -import wantAgent from '@ohos.wantAgent'; - -let wantAgentInfo = { - wants: [ - { - bundleName: "com.example.myapplication", - abilityName: "com.example.myapplication.MainAbility" - } - ], - operationType: wantAgent.OperationType.START_ABILITY, - requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] -}; - -wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { - console.info("Operation succeeded"); - }).catch((err) => { - console.error("Operation failed Cause: " + err); - }); -}); -``` + ``` + let res = workScheduler.stopAndClearWorks(); + console.info("workschedulerLog res:" + res); + ``` -## backgroundTaskManager.stopBackgroundRunning +## workScheduler.isLastWorkTimeOut -[8] stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void; +isLastWorkTimeOut(workId: number, callback : AsyncCallback): boolean -向系统申请取消长时任务，使用callback形式返回结果。 +检查指定工作的最后一次执行是否为超时操作，使用callback形式返回。 - **参数**： + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | - | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | + | workId | number | 是 | work的id。 | + |callback|AsyncCallback| 是| 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。| -- **示例**： -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; -import featureAbility from '@ohos.ability.featureAbility'; +- **返回值**： -function callback(err, data) { - if (err) { - console.error("Operation failed Cause: " + err); - } else { - console.info("Operation succeeded"); - } -} + | 类型 | 说明 | + | -------- | -------- | + | boolean | 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 | -backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback); +- **示例**： -``` + ``` + workScheduler.isLastWorkTimeOut(500, (err, res) =>{ + if (err) { + console.info('workschedulerLog isLastWorkTimeOut callback failed, because:' + err.data); + } else { + console.info('workschedulerLog isLastWorkTimeOut callback success, data is:' + res); + } + }); + ``` -## backgroundTaskManager.stopBackgroundRunning +## workScheduler.isLastWorkTimeOut -[8] stopBackgroundRunning(context: Context): Promise<void>; +obtainAllWorks(): Promise> -向系统申请取消长时任务，使用promise形式返回结果。 +检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。 - **参数**： + | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | + | workId | number | 是 | work的id。 | + +- **返回值**： -- **返回值** - | 类型 | 说明 | - | -------------- | ------------------------- | - | Promise\ | 使用Promise形式返回结果。 | + | 类型 | 说明 | + | -------- | -------- | + | Promise | 指定的Promise回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。| - **示例**： -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; -import featureAbility from '@ohos.ability.featureAbility'; -backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { - console.info("Operation succeeded"); -}).catch((err) => { - console.error("Operation failed Cause: " + err); -}); + ``` + workScheduler.isLastWorkTimeOut(500) + .then(res => { + console.info('workschedulerLog isLastWorkTimeOut promise success, data is:' + res); + }) + .catch(err => { + console.info('workschedulerLog isLastWorkTimeOut promise failed, because:' + err.data); + }); + }) + ``` -``` +## workScheduler.WorkInfo +提供工作的具体信息。 -## [8] BackgroundMode - -| 参数名 | 参数 | 描述 | -| ----------------------- | -------- | -------- | -| DATA_TRANSFER | 1 | 数据传输 | -| AUDIO_PLAYBACK | 2 | 音频播放 | -| AUDIO_RECORDING | 3 | 录音 | -| LOCATION | 4 | 定位导航 | -| BLUETOOTH_INTERACTION | 5 | 蓝牙相关 | -| MULTI_DEVICE_CONNECTION | 6 | 多设备互联 | -| WIFI_INTERACTION | 7 | WLAN相关（系统保留） | -| VOIP | 8 | 音视频通话（系统保留） | -| TASK_KEEPING | 9 | 计算任务（仅供PC使用） | \ No newline at end of file + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + |workId |number |是 |当前工作的ID。| + |bundleName |string |是| 延迟任务包名。| + |abilityName | string| 是| 延迟任务回调通知的组件名（必填）| + |networkType | NetworkType| 否| 网络条件 | + |isCharging | bool| 否|是否充电 | + |chargerType | ChargingType| 否|充电类型 | + |batteryLevel | number| 否|电量| + |batteryStatus| BatteryStatus| 否|电池状态| + |storageRequest|StorageRequest| 否|存储状态| + |isRepeat|boolean|否|是否循环任务| + |repeatCycleTime |number|否|循环间隔| + |repeatCount |number|否|循环次数| + +## workScheduler.NetworkType +触发工作的网络类型。 + + |名称 |默认值 |说明| + | -------- | -------- | -------- | + |NETWORK_TYPE_ANY |0 |表示这个触发条件是任何类型的网络连接。| + |NETWORK_TYPE_MOBILE |1| 表示这个触发条件是Mobile网络连接。| + |NETWORK_TYPE_WIFI |2 |表示这个触发条件是Wifi类型的网络连接。| + |NETWORK_TYPE_BLUETOOTH |3 |表示这个触发条件是Bluetooth网络连接。| + |NETWORK_TYPE_WIFI_P2P |4 |表示这个触发条件是Wifi P2P网络连接。| + |NETWORK_TYPE_ETHERNET |5 |表示这个触发条件是有线网络连接。| + +## workScheduler.ChargingType +触发工作的充电类型。 + + |名称 |默认值 |说明| + | -------- | -------- | -------- | + |CHARGING_PLUGGED_ANY |0| 表示这个触发条件是任何类型的充电器连接。| + |CHARGING_PLUGGED_AC |1 |表示这个触发条件是直流充电器连接。| + |CHARGING_PLUGGED_USB |2 |表示这个触发条件是USB充连接。| + |CHARGING_PLUGGED_WIRELESS |3| 表示这个触发条件是无线充电器连接。| + +## workScheduler.BatteryStatus +触发工作的电池状态。 + + |名称 |默认值 |说明| + | -------- | -------- | -------- | + |BATTERY_STATUS_LOW |0 |表示这个触发条件是低电告警。| + |BATTERY_STATUS_OKAY |1| 表示这个触发条件是从低电恢复到正常电量。| + |BATTERY_STATUS_LOW_OR_OKAY |2 |表示这个触发条件是从低电恢复到正常电量或者低电告警。| + +## workScheduler.StorageRequest +触发工作的存储状态。 + + |名称 |默认值 |说明| + | -------- | -------- | -------- | + |STORAGE_LEVEL_LOW |0 |表示这个触发条件是存储空间不足。 + |STORAGE_LEVEL_OKAY |1 |表示这个触发条件是从存储空间不足恢复到正常。 + |STORAGE_LEVEL_LOW_OR_OKAY |2 |表示这个触发条件是从存储空间不足恢复到正常或者存储空间不足。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-workSchedulerExtension.md b/zh-cn/application-dev/reference/apis/js-apis-workSchedulerExtension.md new file mode 100644 index 0000000000000000000000000000000000000000..1a56cd1d20cf07019dfae67c376d01ab824705a9 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-workSchedulerExtension.md @@ -0,0 +1,46 @@ +# 延迟任务调度回调 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +``` +import workSchedulerExtension from '@ohos.WorkSchedulerExtension' +``` + +## 系统能力 +SystemCapability.ResourceSchedule.WorkScheduler + +## WorkSchedulerExtension.onWorkStart + +onWorkStart(workInfo: WorkInfo); + +延迟任务调度开始回调。 + +- **示例**： + + ``` + export default class MyWorkSchedulerExtension extends WorkSchedulerExtension { + onWorkStart(workInfo) { + console.log('MyWorkSchedulerExtension onWorkStart' + JSON.stringify(workInfo)); + } + } + ``` + +## WorkSchedulerExtension.onWorkStop + +onWorkStop(workInfo: WorkInfo); + +延迟任务调度结束回调。 + +- **示例**： + + ``` + export default class MyWorkSchedulerExtension extends WorkSchedulerExtension { + onWorkStop(workInfo) { + console.log('MyWorkSchedulerExtension onWorkStop' + JSON.stringify(workInfo)); + } + } + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/work-scheduler/work-scheduler-dev-guide.md b/zh-cn/application-dev/work-scheduler/work-scheduler-dev-guide.md index 1900b8b3c163acadfdb9d9e672f8281fb7acc73d..ca2855356a08f802ec09117d757978a5fb814015 100644 --- a/zh-cn/application-dev/work-scheduler/work-scheduler-dev-guide.md +++ b/zh-cn/application-dev/work-scheduler/work-scheduler-dev-guide.md @@ -106,7 +106,7 @@ function onWorkStop(work: WorkInfo): void; | 延迟调度任务结束回调 bundleName: "com.example.myapplication", abilityName: "MyExtension" } - var res = workScheduler.stopWork(workInfo); + var res = workScheduler.stopWork(workInfo, false); console.info("workschedulerLog res:" + res); diff --git a/zh-cn/application-dev/work-scheduler/work-scheduler-overview.md b/zh-cn/application-dev/work-scheduler/work-scheduler-overview.md index e58c2d43c139c5b6543263f88607055583771706..eeae563e7d40d0d98502ef2ec5bf8cf835609f48 100644 --- a/zh-cn/application-dev/work-scheduler/work-scheduler-overview.md +++ b/zh-cn/application-dev/work-scheduler/work-scheduler-overview.md @@ -10,7 +10,7 @@ 延迟调度任务的使用需要遵从如下约束和规则： -- **超时**：每次最长运行120秒，超时之后，系统会主动停止。 +- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。 - **WorkInfo设置参数约束** （1） workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。