diff --git a/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md b/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md index 59f2b5f535283e04d6f1b499ee4e9e733f204da8..66b855752571479e85800e5568fe62d7497d158c 100644 --- a/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md +++ b/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md @@ -1,12 +1,18 @@ # Work Scheduler Callbacks -> **NOTE**
-> The initial APIs of this module are supported since API version 9. API version 9 is a canary version for trial use. The APIs of this version may be unstable. +The **WorkSchedulerExtensionAbility** module provides callbacks for Work Scheduler tasks. + +When developing an application, you can override the APIs of this module and add your own task logic to the APIs. + +> **NOTE** +> +> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs of this module can be used only in the stage model. ## Modules to Import -``` +```ts import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility' ``` @@ -20,13 +26,13 @@ Triggered when the Work Scheduler task starts. **Parameters** -| Name | Type | Mandatory | Description | -| ---- | --------------------- | ---- | -------------- | -| work | [workScheduler.WorkInfo](js-apis-workScheduler.md#workinfo) | Yes | Task to be added to the execution queue.| +| Name | Type | Mandatory | Description | +| ---- | ---------------------------------------- | ---- | -------------- | +| work | [workScheduler.WorkInfo](js-apis-workScheduler.md#workinfo) | Yes | Target task. | **Example** - ``` + ```ts export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { onWorkStart(workInfo) { console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); @@ -44,14 +50,14 @@ Triggered when the Work Scheduler task stops. **Parameters** -| Name | Type | Mandatory | Description | -| ---- | --------------------- | ---- | -------------- | -| work | [workScheduler.WorkInfo](js-apis-workScheduler.md#workinfo) | Yes | Task to be added to the execution queue.| +| Name | Type | Mandatory | Description | +| ---- | ---------------------------------------- | ---- | -------------- | +| work | [workScheduler.WorkInfo](js-apis-workScheduler.md#workinfo) | Yes | Target task. | **Example** - ``` + ```ts export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { onWorkStop(workInfo) { console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); diff --git a/en/application-dev/reference/apis/js-apis-workScheduler.md b/en/application-dev/reference/apis/js-apis-workScheduler.md index 964b63aa2ec47a0cceaaac8457f77f3a916051f7..725b313ba88bedca924f0f5f1d2f6166308d2b8f 100644 --- a/en/application-dev/reference/apis/js-apis-workScheduler.md +++ b/en/application-dev/reference/apis/js-apis-workScheduler.md @@ -1,12 +1,18 @@ # Work Scheduler -> **NOTE**
-> The initial APIs of this module are supported since API version 9. API version 9 is a canary version for trial use. The APIs of this version may be unstable. +The **workScheduler** module provides the APIs for registering, canceling, and querying Work Scheduler tasks, which do not have real-time constraints. + +The system executes Work Scheduler tasks at an appropriate time, subject to the storage space, power consumption, temperature, and more. + +> **NOTE** +> +> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs of this module can be used only in the stage model. ## Modules to Import -``` +```js import workScheduler from '@ohos.workScheduler' ``` @@ -31,15 +37,20 @@ Instructs the **WorkSchedulerService** to add the specified task to the executio **Example** -``` +```js let workInfo = { workId: 1, - batteryLevel:50, batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, isRepeat: false, isPersisted: true, bundleName: "com.example.myapplication", - abilityName: "MyExtension" + abilityName: "MyExtension", + parameters: { + mykey0: 1, + mykey1: "string value", + mykey2: true, + mykey3: 1.5 + } } var res = workScheduler.startWork(workInfo); console.info("workschedulerLog res:" + res); @@ -67,15 +78,20 @@ Instructs the **WorkSchedulerService** to stop the specified task. **Example** -``` +```js let workInfo = { workId: 1, - batteryLevel:50, batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, isRepeat: false, isPersisted: true, bundleName: "com.example.myapplication", - abilityName: "MyExtension" + abilityName: "MyExtension", + parameters: { + mykey0: 1, + mykey1: "string value", + mykey2: true, + mykey3: 1.5 + } } var res = workScheduler.stopWork(workInfo, false); console.info("workschedulerLog res:" + res); @@ -97,7 +113,7 @@ Obtains the latest task status. This API uses an asynchronous callback to return **Example** -``` +```js workScheduler.getWorkStatus(50, (err, res) => { if (err) { console.info('workschedulerLog getWorkStatus failed, because:' + err.code); @@ -130,7 +146,7 @@ Obtains the latest task status. This API uses a promise to return the result. **Example** -``` +```js workScheduler.getWorkStatus(50).then((res) => { for (let item in res) { console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); @@ -151,7 +167,7 @@ Obtains all tasks associated with this application. This API uses an asynchronou | Name | Type | Mandatory | Description | | -------- | -------------------- | ---- | ------------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return all tasks associated with the current application. | +| callback | AsyncCallback\ | Yes | Callback used to return all tasks associated with the current application.| **Return value** @@ -161,7 +177,7 @@ Obtains all tasks associated with this application. This API uses an asynchronou **Example** -``` +```js workScheduler.obtainAllWorks((err, res) =>{ if (err) { console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); @@ -182,11 +198,11 @@ Obtains all tasks associated with this application. This API uses a promise to r | Type | Description | | -------------------------------------- | ------------------------------ | -| Promise> | Promise used to return all tasks associated with the current application. | +| Promise> | Promise used to return all tasks associated with the current application.| **Example** -``` +```js workScheduler.obtainAllWorks().then((res) => { console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); }).catch((err) => { @@ -203,7 +219,7 @@ Stops and cancels all tasks associated with the current application. **Example** -``` +```js let res = workScheduler.stopAndClearWorks(); console.info("workschedulerLog res:" + res); ``` @@ -230,7 +246,7 @@ Checks whether the last execution of the specified task timed out. This API uses **Example** -``` +```js workScheduler.isLastWorkTimeOut(500, (err, res) =>{ if (err) { console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code); @@ -261,7 +277,7 @@ Checks whether the last execution of the specified task timed out. This API uses **Example** -``` +```js workScheduler.isLastWorkTimeOut(500) .then(res => { console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); @@ -272,27 +288,28 @@ Checks whether the last execution of the specified task timed out. This API uses ``` ## WorkInfo -Provides detailed information about the task. +Provides detailed information about the task. For details about the constraints on configuring **WorkInfo**, see [Work Scheduler Overview](../../task-management/work-scheduler-overview.md). **System capability**: SystemCapability.ResourceSchedule.WorkScheduler -| Name | Type | Mandatory| Description | -| --------------- | --------------------------------- | ---- | -------------------------------- | -| workId | number | Yes | Task ID. | -| bundleName | string | Yes | Name of the Work Scheduler task bundle. | -| abilityName | string | Yes | Name of the component to be notified by a Work Scheduler callback.| -| networkType | [NetworkType](#networktype) | No | Network type. | -| isCharging | boolean | No | Whether the device is charging. | -| chargerType | [ChargingType](#chargingtype) | No | Charging type. | -| batteryLevel | number | No | Battery level. | -| batteryStatus | [BatteryStatus](#batterystatus) | No | Battery status. | -| storageRequest | [StorageRequest](#storagerequest) | No | Storage status. | -| isRepeat | boolean | No | Whether the task is repeated. | -| repeatCycleTime | number | No | Repeat interval. | -| repeatCount | number | No | Number of repeat times. | -| isPersisted | boolean | No | Whether to enable persistent storage for the task. | -| isDeepIdle | boolean | No | Whether the device needs to enter the idle state. | -| idleWaitTime | number | No | Time to wait in the idle state. | +| Name | Type | Mandatory | Description | +| --------------- | --------------------------------- | ---- | ---------------- | +| workId | number | Yes | Task ID. | +| bundleName | string | Yes | Name of the Work Scheduler task bundle. | +| abilityName | string | Yes | Name of the component to be notified by a Work Scheduler callback.| +| networkType | [NetworkType](#networktype) | No | Network type. | +| isCharging | boolean | No | Whether the device is charging. | +| chargerType | [ChargingType](#chargingtype) | No | Charging type. | +| batteryLevel | number | No | Battery level. | +| batteryStatus | [BatteryStatus](#batterystatus) | No | Battery status. | +| storageRequest | [StorageRequest](#storagerequest) | No | Storage status. | +| isRepeat | boolean | No | Whether the task is repeated. | +| repeatCycleTime | number | No | Repeat interval. | +| repeatCount | number | No | Number of repeat times. | +| isPersisted | boolean | No | Whether to enable persistent storage for the task. | +| isDeepIdle | boolean | No | Whether the device needs to enter the idle state. | +| idleWaitTime | number | No | Time to wait in the idle state. | +| parameters | {[key: string]: any} | No | Carried parameters. | ## NetworkType Enumerates the network types that can trigger the task. @@ -336,8 +353,8 @@ Enumerates the storage states that can trigger the task. **System capability**: SystemCapability.ResourceSchedule.WorkScheduler - |Name |Default Value |Description| - | -------- | -------- | -------- | - |STORAGE_LEVEL_LOW |0 |The storage space is insufficient. - |STORAGE_LEVEL_OKAY |1 |The storage space is restored from insufficient to normal. - |STORAGE_LEVEL_LOW_OR_OKAY |2 |The storage space is restored from insufficient to normal, or the storage space is insufficient. +| Name | Default Value | Description | +| ------------------------- | ---- | ------------------------------ | +| STORAGE_LEVEL_LOW | 0 | The storage space is insufficient. | +| STORAGE_LEVEL_OKAY | 1 | The storage space is restored from insufficient to normal. | +| STORAGE_LEVEL_LOW_OR_OKAY | 2 | The storage space is restored from insufficient to normal, or the storage space is insufficient.| diff --git a/en/application-dev/reference/arkui-ts/ts-universal-events-key.md b/en/application-dev/reference/arkui-ts/ts-universal-events-key.md index 77f563ad5781a1acbd502023a4be8d2e965247a8..16ac5240527857a6afe19ce3bb9314caadda0872 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-events-key.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-events-key.md @@ -22,15 +22,15 @@ None ## KeyEvent - Attributes - | Name | Type | Description | - | -------- | -------- | -------- | - | type | [KeyType](#keytype-enums) | Type of a key. | - | keyCode | number | Key code. | - | keyText | string | Key value. | - | keySource | [KeySource](#keysource-enums) | Type of the input device that triggers the key event. | - | deviceId | number | ID of the input device that triggers the key event. | - | metaKey | number | State of the metakey when the key is pressed. The value **1** means the pressed state, and **0** means the unpressed state. | - | timestamp | number | Timestamp when the key is pressed. | + | Name | Type | Description | + | ------------------------------------- | --------------------------- | -------------------------- | + | type | [KeyType](#keytype-enums) | Type of a key. | + | [keyCode](../apis/js-apis-keycode.md) | number | Key code. | + | keyText | string | Key value. | + | keySource | [KeySource](#keysource-enums) | Type of the input device that triggers the key event. | + | deviceId | number | ID of the input device that triggers the key event. | + | metaKey | number | State of the metakey when the key is pressed. The value **1** means the pressed state, and **0** means the unpressed state. | + | timestamp | number | Timestamp when the key is pressed. | - APIs | Name | Description | @@ -48,20 +48,10 @@ None ## KeySource Enums | Name | Description | | -------- | -------- | -| Unknown | Unknown input device. | -| [KeyCode](#common-keycode-enums) | The input device is a keyboard. | +| Unknown | Unknown input device. | +| Keyboard | The input device is a keyboard. | -## Common KeyCode Enums -| Value | Behavior | Physical Button | -| -------- | -------- | -------- | -| 19 | Upward | Up button. | -| 20 | Downward | Down button. | -| 21 | Leftward | Left button. | -| 22 | Rightward | Right button. | -| 23 | OK | **OK** key on a remote control. | -| 66 | OK | **Enter** key on a keyboard. | -| 160 | OK | **Enter** button on the numeric keypad. | ## Example diff --git a/en/application-dev/task-management/work-scheduler-dev-guide.md b/en/application-dev/task-management/work-scheduler-dev-guide.md index dfa30e4a5d03af24e4c2e75a5f0569bd1b30fa07..20a22b7613403e76e8efd0acc127733e4a85e628 100644 --- a/en/application-dev/task-management/work-scheduler-dev-guide.md +++ b/en/application-dev/task-management/work-scheduler-dev-guide.md @@ -20,25 +20,29 @@ import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; **Table 1** Major workScheduler APIs -API | Description ----------------------------------------------------------|----------------------------------------- -function startWork(work: WorkInfo): boolean; | Starts a Work Scheduler task. -function stopWork(work: WorkInfo, needCancel?: boolean): boolean; | Stops a Work Scheduler task. -function getWorkStatus(workId: number, callback: AsyncCallback): void;| Obtains the status of a Work Scheduler task. This method uses an asynchronous callback to return the result. -function getWorkStatus(workId: number): Promise; | Obtains the status of a Work Scheduler task. This method uses a promise to return the result. -function obtainAllWorks(callback: AsyncCallback): Array;| Obtains Work Scheduler tasks. This method uses an asynchronous callback to return the result. -function obtainAllWorks(): Promise>;| Obtains Work Scheduler tasks. This method uses a promise to return the result. -function stopAndClearWorks(): boolean;| Stops and clears Work Scheduler tasks. -function isLastWorkTimeOut(workId: number, callback: AsyncCallback): boolean;| Checks whether the last execution of the specified task has timed out. This method uses an asynchronous callback to return the result. It is applicable to repeated tasks. -function isLastWorkTimeOut(workId: number): Promise;| Checks whether the last execution of the specified task has timed out. This method uses a promise to return the result. It is applicable to repeated tasks. + Name | Description + ------------------------------------------------------------ | ------------------------------------------------------------ + startWork(work: WorkInfo): boolean; | Starts a Work Scheduler task. + stopWork(work: WorkInfo, needCancel?: boolean): boolean; | Stops a Work Scheduler task. + getWorkStatus(workId: number, callback: AsyncCallback\): void; | Obtains the status of a Work Scheduler task. This API uses an asynchronous callback to return the result. + getWorkStatus(workId: number): Promise\; | Obtains the status of a Work Scheduler task. This API uses a promise to return the result. + obtainAllWorks(callback: AsyncCallback\): Array\; | Obtains Work Scheduler tasks. This API uses an asynchronous callback to return the result. + obtainAllWorks(): Promise>; | Obtains Work Scheduler tasks. This API uses a promise to return the result. + stopAndClearWorks(): boolean; | Stops and clears Work Scheduler tasks. + isLastWorkTimeOut(workId: number, callback: AsyncCallback\): boolean; | Checks whether the last execution of the specified task has timed out. This API uses an asynchronous callback to return the result. It is applicable to repeated tasks. + isLastWorkTimeOut(workId: number): Promise\; | Checks whether the last execution of the specified task has timed out. This API uses a promise to return the result. It is applicable to repeated tasks. **Table 2** WorkInfo parameters -API|Description|Type +> **NOTE** +> +> For details about the constraints on configuring WorkInfo, see [Work Scheduler Overview](./work-scheduler-overview.md). + +Name|Description|Type ---------------------------------------------------------|-----------------------------------------|--------------------------------------------------------- workId | Work ID. Mandatory.|number bundleName | Name of the Work Scheduler task bundle. Mandatory.|string -abilityName | Name of the component to be notified by a Work Scheduler callback.|string +abilityName | Name of the component to be notified by a Work Scheduler callback. Mandatory.|string networkType | Network type.| NetworkType isCharging | Whether the device is charging.| boolean chargerType | Charging type.| ChargingType @@ -48,20 +52,21 @@ storageRequest|Storage status.| StorageRequest isRepeat|Whether the task is repeated.| boolean repeatCycleTime |Repeat interval.| number repeatCount |Number of repeat times.| number +parameters |Carried parameters.| {[key: string]: any} **Table 3** Work Scheduler callbacks -API | Description ----------------------------------------------------------|----------------------------------------- -function onWorkStart(work: WorkInfo): void; | Triggered when the Work Scheduler task starts. -function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler task stops. + Name | Description + ------------------------------------------- | ---------------------------------------------- + onWorkStart(work: WorkInfo): void; | Triggered when the Work Scheduler task starts. + onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler task stops. ### How to Develop **Implementing WorkSchedulerExtensionAbility** import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; - + export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { onWorkStart(workInfo) { console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); @@ -74,18 +79,21 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t **Registering a Work Scheduler Task** - - import workScheduler from '@ohos.workScheduler'; - + let workInfo = { workId: 1, - batteryLevel:50, batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, isRepeat: false, isPersisted: true, bundleName: "com.example.myapplication", - abilityName: "MyExtension" + abilityName: "MyExtension", + parameters: { + mykey0: 1, + mykey1: "string value", + mykey2: true, + mykey3: 1.5 + } } var res = workScheduler.startWork(workInfo); console.info("workschedulerLog res:" + res); @@ -95,15 +103,20 @@ function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler t import workScheduler from '@ohos.workScheduler'; - + let workInfo = { workId: 1, - batteryLevel:50, batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, isRepeat: false, isPersisted: true, bundleName: "com.example.myapplication", - abilityName: "MyExtension" + abilityName: "MyExtension", + parameters: { + mykey0: 1, + mykey1: "string value", + mykey2: true, + mykey3: 1.5 + } } var res = workScheduler.stopWork(workInfo, false); console.info("workschedulerLog res:" + res); diff --git a/en/application-dev/task-management/work-scheduler-overview.md b/en/application-dev/task-management/work-scheduler-overview.md index b6c2fec6ec66b369832930fd5dc520603209788f..c5fda53bfc0de1c8f38bed6cfdc9bf60e7d1e861 100644 --- a/en/application-dev/task-management/work-scheduler-overview.md +++ b/en/application-dev/task-management/work-scheduler-overview.md @@ -11,10 +11,23 @@ If your application needs to execute a non-real-time task, for example, data lea The use of the Work Scheduler must comply with the following restrictions and rules: - **Timeout**: The Work Scheduler callback can run only within the specified period of time. After the timeout, the callback automatically stops. +- **Execution frequency**: The system controls the execution frequency of Work Scheduler tasks based on the activity level of their respective applications. + + Application Group | Work Scheduler Task Execution Frequency + --------------------|------------------------- + Active| At a minimum interval of 2 hours + Used every day| At a minimum interval of 4 hours + Frequently used| At a minimum interval of 24 hours + Infrequently used| At a minimum interval of 48 hours + Restricted| Prohibited + Unused| Prohibited + - **WorkInfo setting** -(1) **workId**, **bundleName**, and **abilityName** are mandatory. **bundleName** must be set to the name of the current application. Otherwise, the verification will fail. + - **workId**, **bundleName**, and **abilityName** are mandatory. **bundleName** must be set to the name of the current application. Otherwise, the verification will fail. + + - At least one condition must be set. -(2) At least one condition must be set. + - The repeat interval must be at least 20 minutes and must work with the Always repeat pattern or repeat times. -(3) The repeat interval must be at least 20 minutes and must work with the Always repeat pattern or repeat times. + - The carried parameters can be of the number, string, or bool type.