提交 3d16f54a 编写于 作者: E ester.zhou

update docs (7430)

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 dec56aef
# Work Scheduler Callbacks
> **NOTE**<br/>
> 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));
......
# Work Scheduler
> **NOTE**<br/>
> 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\<void> | Yes | Callback used to return all tasks associated with the current application. |
| callback | AsyncCallback\<void> | 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<Array\<[WorkInfo](#workinfo)>> | Promise used to return all tasks associated with the current application. |
| Promise<Array\<[WorkInfo](#workinfo)>> | 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.|
......@@ -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
......
......@@ -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<WorkInfo>): void;| Obtains the status of a Work Scheduler task. This method uses an asynchronous callback to return the result.
function getWorkStatus(workId: number): Promise<WorkInfo>; | Obtains the status of a Work Scheduler task. This method uses a promise to return the result.
function obtainAllWorks(callback: AsyncCallback<void>): Array<WorkInfo>;| Obtains Work Scheduler tasks. This method uses an asynchronous callback to return the result.
function obtainAllWorks(): Promise<Array<WorkInfo>>;| 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<void>): 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<boolean>;| 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\<WorkInfo>): void; | Obtains the status of a Work Scheduler task. This API uses an asynchronous callback to return the result.
getWorkStatus(workId: number): Promise\<WorkInfo>; | Obtains the status of a Work Scheduler task. This API uses a promise to return the result.
obtainAllWorks(callback: AsyncCallback\<void>): Array\<WorkInfo>; | Obtains Work Scheduler tasks. This API uses an asynchronous callback to return the result.
obtainAllWorks(): Promise<Array\<WorkInfo>>; | 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\<void>): 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\<boolean>; | 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);
......
......@@ -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.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册