Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 92746cfd 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!1546 添加延迟任务调度相关文档 

Merge pull request !1546 from 陈明/master
上级 37d749bb de062ac7
隐藏空白更改
内联 并排
Showing with 635 addition and 0 deletion
zh-cn/application-dev/reference/apis/js-apis-workScheduler.md 0 → 100644
浏览文件 @ 92746cfd
# 延迟任务调度
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```
import workScheduler from '@ohos.workScheduler'
```
## workScheduler.startWork
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
workScheduler.startWork(work: WorkInfo): boolean
- **说明**：
通知WorkSchedulerService将工作添加到执行队列。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| work | WorkInfo | 是 | 指示要添加到执行队列的工作。 |
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| 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
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
stopWork(work: WorkInfo, needCancel?: boolean): boolean
- **说明**：
通知WorkSchedulerService停止指定工作。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| work | WorkInfo | 是 | 指示要停止的工作。 |
|needCancel|boolean| 是| 是否需要取消的工作。|
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| 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.stopWork(workInfo, false);
console.info("workschedulerLog res:" + res);
```
## workScheduler.getWorkStatus
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
getWorkStatus(workId: number, callback : AsyncCallback<WorkInfo>): void
- **说明**：
获取工作的最新状态，使用Callback形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| workId | number | 是 | work的id。 |
|callback|AsyncCallback<WorkInfo>| 是| 指定的callback回调方法。如果指定的工作Id有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。|
- **示例**：
```
workScheduler.getWorkStatus(50, (err, res) => {
if (err) {
console.info('workschedulerLog getWorkStatus failed, because:' + err.data);
} else {
for (let item in res) {
console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]);
}
}
});
```
## workScheduler.getWorkStatus
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
getWorkStatus(workID: number): Promise<WorkInfo>
- **说明**：
获取工作的最新状态，使用Promise形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| workId | number | 是 | work的id。 |
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| Promise<WorkInfo> | 指定的Promise回调方法。如果指定的工作ID有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。 |
- **示例**：
```
workScheduler.getWorkStatus(50).then((res) => {
for (let item in res) {
console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]);
}
}).catch((err) => {
console.info('workschedulerLog getWorkStatus failed, because:' + err.data);
})
```
## workScheduler.obtainAllWorks
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
obtainAllWorks(callback : AsyncCallback<void>): Array<WorkInfo>
- **说明**：
获取与当前应用程序关联的所有工作，使用Callback形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
|callback|AsyncCallback<WorkInfo>| 是| 指定的callback回调方法。返回与应用程序关联的所有工作。|
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| Array<WorkInfo> | 返回与应用程序关联的所有工作。 |
- **示例**：
```
workScheduler.obtainAllWorks((err, res) =>{
if (err) {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.data);
} else {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}
});
```
## workScheduler.obtainAllWorks
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
obtainAllWorks(): Promise<Array<WorkInfo>>
- **说明**：
获取与当前应用程序关联的所有工作，使用Promise形式返回。
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| Promise<Array<WorkInfo>> | 指定的Promise回调方法。返回与应用程序关联的所有工作。|
- **示例**：
```
workScheduler.obtainAllWorks().then((res) => {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}).catch((err) => {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.data);
})
```
## workScheduler.stopAndClearWorks
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
stopAndClearWorks(): boolean
- **说明**：
停止和取消与当前应用程序关联的所有工作。
- **示例**：
```
let res = workScheduler.stopAndClearWorks();
console.info("workschedulerLog res:" + res);
```
## workScheduler.isLastWorkTimeOut
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
isLastWorkTimeOut(workId: number, callback : AsyncCallback<void>): boolean
- **说明**：
检查指定工作的最后一次执行是否为超时操作，使用Callback形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| workId | number | 是 | work的id。 |
|callback|AsyncCallback<WorkInfo>| 是| 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。|
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| boolean | 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 |
- **示例**：
```
workScheduler.isLastWorkTimeOut(500, (err, res) =>{
if (err) {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data);
} else {
console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res);
}
});
```
## workScheduler.isLastWorkTimeOut
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
isLastWorkTimeOut(workId: number): Promise<boolean>
- **说明**：
检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| workId | number | 是 | work的id。 |
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| Promise<boolean> | 指定的Promise回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。|
- **示例**：
```
workScheduler.isLastWorkTimeOut(500)
.then(res => {
console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res);
})
.catch(err => {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data);
});
})
```
## workScheduler.WorkInfo
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
提供工作的具体信息。
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
|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
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
触发工作的网络类型。
|名称 |默认值 |说明|
| -------- | -------- | -------- |
|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
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
触发工作的充电类型。
|名称 |默认值 |说明|
| -------- | -------- | -------- |
|CHARGING_PLUGGED_ANY |0| 表示这个触发条件是任何类型的充电器连接。|
|CHARGING_PLUGGED_AC |1 |表示这个触发条件是直流充电器连接。|
|CHARGING_PLUGGED_USB |2 |表示这个触发条件是USB充连接。|
|CHARGING_PLUGGED_WIRELESS |3| 表示这个触发条件是无线充电器连接。|
## workScheduler.BatteryStatus
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
触发工作的电池状态。
|名称 |默认值 |说明|
| -------- | -------- | -------- |
|BATTERY_STATUS_LOW |0 |表示这个触发条件是低电告警。|
|BATTERY_STATUS_OKAY |1| 表示这个触发条件是从低电恢复到正常电量。|
|BATTERY_STATUS_LOW_OR_OKAY |2 |表示这个触发条件是从低电恢复到正常电量或者低电告警。|
## workScheduler.StorageRequest
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
触发工作的存储状态。
|名称 |默认值 |说明|
| -------- | -------- | -------- |
|STORAGE_LEVEL_LOW |0 |表示这个触发条件是存储空间不足。
|STORAGE_LEVEL_OKAY |1 |表示这个触发条件是从存储空间不足恢复到正常。
|STORAGE_LEVEL_LOW_OR_OKAY |2 |表示这个触发条件是从存储空间不足恢复到正常或者存储空间不足。
\ No newline at end of file
zh-cn/application-dev/reference/apis/js-apis-workSchedulerExtension.md 0 → 100644
浏览文件 @ 92746cfd
# 延迟任务调度回调
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```
import workSchedulerExtension from '@ohos.WorkSchedulerExtension'
```
## WorkSchedulerExtension.onWorkStart
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
onWorkStart(workInfo: WorkInfo);
- **说明**：
延迟任务调度开始回调。
- **示例**：
```
export default class MyWorkSchedulerExtension extends WorkSchedulerExtension {
onWorkStart(workInfo) {
console.log('MyWorkSchedulerExtension onWorkStart' + JSON.stringify(workInfo));
}
}
```
## WorkSchedulerExtension.onWorkStop
- **系统能力**：
SystemCapability.ResourceSchedule.WorkScheduler
- **接口**：
onWorkStop(workInfo: WorkInfo);
- **说明**：
延迟任务调度结束回调。
- **示例**：
```
export default class MyWorkSchedulerExtension extends WorkSchedulerExtension {
onWorkStop(workInfo) {
console.log('MyWorkSchedulerExtension onWorkStop' + JSON.stringify(workInfo));
}
}
```
\ No newline at end of file
zh-cn/application-dev/work-scheduler/Readme-CN.md 0 → 100644
浏览文件 @ 92746cfd
# 延迟任务调度
- 后台任务
- [延迟任务调度概述](work-scheduler-overview.md)
- [延迟任务调度开发指导](work-scheduler-dev-guide.md)
\ No newline at end of file
zh-cn/application-dev/work-scheduler/work-scheduler-dev-guide.md 0 → 100644
浏览文件 @ 92746cfd
# 延迟任务调度开发指导
## 场景介绍
应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、热等统一决策调度时间。
## 接口说明
注册相关接口包导入：
```js
import workScheduler from '@ohos.workScheduler';
```
回调相关接口包导入：
```js
import WorkSchedulerExtension from '@ohos.WorkSchedulerExtension';
```
### 延迟任务调度
**表1** workScheduler主要接口
接口名 | 接口描述
---------------------------------------------------------|-----------------------------------------
function startWork(work: WorkInfo): boolean; | 延迟调度任务申请
function stopWork(work: WorkInfo, needCancel?: boolean): boolean; | 延迟调度任务取消
function getWorkStatus(workId: number, callback: AsyncCallback<WorkInfo>): void;| 获取延迟调度任务状态（Callback形式）
function getWorkStatus(workId: number): Promise<WorkInfo>; | 获取延迟调度任务状态（Promise形式）
function obtainAllWorks(callback: AsyncCallback<void>): Array<WorkInfo>;| 获取所有延迟调度任务（Callback形式）
function obtainAllWorks(): Promise<Array<WorkInfo>>;| 获取所有延迟调度任务（Promise形式）
function stopAndClearWorks(): boolean;| 停止并清除任务
function isLastWorkTimeOut(workId: number, callback: AsyncCallback<void>): boolean;| 获取上次任务是否超时（针对RepeatWork，Callback形式）
function isLastWorkTimeOut(workId: number): Promise<boolean>;| 获取上次任务是否超时（针对RepeatWork，Promise形式）
**表2** WorkInfo包含参数
接口名|描述|类型
---------------------------------------------------------|-----------------------------------------|---------------------------------------------------------
workId | 延迟任务Id（必填）|number
bundleName | 延迟任务包名（必填）|string
abilityName | 延迟任务回调通知的组件名（必填）|string
networkType | 网络条件 | NetworkType
isCharging | 是否充电 | bool
chargerType | 充电类型 | ChargingType
batteryLevel | 电量| number
batteryStatus| 电池状态| BatteryStatus
storageRequest|存储状态| StorageRequest
isRepeat|是否循环任务| boolean
repeatCycleTime |循环间隔| number
repeatCount |循环次数| number
**表3** 延迟任务回调接口
接口名 | 接口描述
---------------------------------------------------------|-----------------------------------------
function onWorkStart(work: WorkInfo): void; | 延迟调度任务开始回调
function onWorkStop(work: WorkInfo): void; | 延迟调度任务结束回调
### 开发步骤
**开发对应的Extension**
import WorkSchedulerExtension from '@ohos.WorkSchedulerExtension';
export default class MyWorkSchedulerExtension extends WorkSchedulerExtension {
onWorkStart(workInfo) {
console.log('MyWorkSchedulerExtension onWorkStart' + JSON.stringify(workInfo));
}
onWorkStop(workInfo) {
console.log('MyWorkSchedulerExtension onWorkStop' + JSON.stringify(workInfo));
}
}
**注册延迟任务**
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"
}
var res = workScheduler.startWork(workInfo);
console.info("workschedulerLog res:" + res);
**取消延迟任务**
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"
}
var res = workScheduler.stopWork(workInfo, false);
console.info("workschedulerLog res:" + res);
**获取指定延迟任务**
1.Callback写法
workScheduler.getWorkStatus(50, (err, res) => {
if (err) {
console.info('workschedulerLog getWorkStatus failed, because:' + err.data);
} else {
for (let item in res) {
console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]);
}
}
});
2.Promise写法
workScheduler.getWorkStatus(50).then((res) => {
for (let item in res) {
console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]);
}
}).catch((err) => {
console.info('workschedulerLog getWorkStatus failed, because:' + err.data);
})
**获取所有延迟任务**
1.Callback写法
workScheduler.obtainAllWorks((err, res) =>{
if (err) {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.data);
} else {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}
});
2.Promise写法
workScheduler.obtainAllWorks().then((res) => {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}).catch((err) => {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.data);
})
**停止并清除任务**
let res = workScheduler.stopAndClearWorks();
console.info("workschedulerLog res:" + res);
**判断上次执行是否超时**
1.Callback写法
workScheduler.isLastWorkTimeOut(500, (err, res) =>{
if (err) {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data);
} else {
console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res);
}
});
2.Promise写法
workScheduler.isLastWorkTimeOut(500)
.then(res => {
console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res);
})
.catch(err => {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data);
});
})
\ No newline at end of file
zh-cn/application-dev/work-scheduler/work-scheduler-overview.md 0 → 100644
浏览文件 @ 92746cfd
# 延迟任务调度概述
延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性不高的任务。当满足设定条件的时候，任务会被放入待调度队列，当系统空闲时调度该任务。
## 使用说明
应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时机。
## 延迟任务调度约束
延迟调度任务的使用需要遵从如下约束和规则：
- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。
- **WorkInfo设置参数约束**
（1） workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。
（2）至少要设置一个满足的条件。
（3）重复任务时间间隔至少20分钟，当设置重复任务时间间隔时，必须设置始终重复和重复次数中的一个。
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或