Skip to content

D
Docs

OpenHarmony / Docs
12 个月 前同步成功

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

提交 0337850f 编写于 作者: 陈 陈明
浏览文件
操作

延迟任务调度文档更新 

Signed-off-by: N陈明 <chenming48@huawei.com>
上级 446dc0a8
隐藏空白更改
内联 并排
Showing with 267 addition and 184 deletion
zh-cn/application-dev/reference/apis/js-apis-workScheduler.md
浏览文件 @ 0337850f
......@@ -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&lt;void&gt;): 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&lt;void&gt; | 是 | 延迟即将超时的回调函数，一般在超时前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<WorkInfo>): void
getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void
获取工作的最新状态，使用callback形式返回。
获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| callback | AsyncCallback&lt;number&gt; | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 |
| workId | number | 是 | work的id。 |
|callback|AsyncCallback<WorkInfo>| 是| 指定的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&lt;number&gt;
getWorkStatus(workID: number): Promise<WorkInfo>
获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。
获取工作的最新状态，使用Promise形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| workId | number | 是 | work的id。 |
- **返回值**：
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;number&gt; | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 |
| Promise<WorkInfo> | 指定的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<void>): Array<WorkInfo>
cancelSuspendDelay(requestId: number): void
取消延迟挂起。
获取与当前应用程序关联的所有工作，使用callback形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
- **示例**：
```
backgroundTaskManager.cancelSuspendDelay(id);
```
|callback|AsyncCallback<WorkInfo>| 是| 指定的callback回调方法。返回与应用程序关联的所有工作。|
#### DelaySuspendInfo
延迟挂起信息。
- **返回值**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 |
| 类型 | 说明 |
| -------- | -------- |
| Array<WorkInfo> | 返回与应用程序关联的所有工作。 |
## backgroundTaskManager.startBackgroundRunning
- **示例**：
<sup>[8]</sup> startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): 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 | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。使用方式参考：<sup>[8]</sup> |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果 |
obtainAllWorks(): Promise<Array<WorkInfo>>
- **示例**：
```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<Array<WorkInfo>> | 指定的Promise回调方法。返回与应用程序关联的所有工作。|
## backgroundTaskManager.startBackgroundRunning
- **示例**：
<sup>[8]</sup> startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
```
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\<void> | 使用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
<sup>[8]</sup> stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void;
isLastWorkTimeOut(workId: number, callback : AsyncCallback<void>): boolean
向系统申请取消长时任务，使用callback形式返回结果。
检查指定工作的最后一次执行是否为超时操作，使用callback形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| context | Context | 是 | 应用运行的上下文 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果 |
| workId | number | 是 | work的id。 |
|callback|AsyncCallback<WorkInfo>| 是| 指定的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
<sup>[8]</sup> stopBackgroundRunning(context: Context): Promise&lt;void&gt;;
obtainAllWorks(): Promise<Array<WorkInfo>>
向系统申请取消长时任务，使用promise形式返回结果。
检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。
- **参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| context | Context | 是 | 应用运行的上下文 |
| workId | number | 是 | work的id。 |
- **返回值**：
- **返回值**
| 类型 | 说明 |
| -------------- | ------------------------- |
| Promise\<void> | 使用Promise形式返回结果。 |
| 类型 | 说明 |
| -------- | -------- |
| Promise<boolean> | 指定的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
提供工作的具体信息。
## <sup>[8]</sup> 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
zh-cn/application-dev/reference/apis/js-apis-workSchedulerExtension.md 0 → 100644
浏览文件 @ 0337850f
# 延迟任务调度回调
> ![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
zh-cn/application-dev/work-scheduler/work-scheduler-dev-guide.md
浏览文件 @ 0337850f
......@@ -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);
......
zh-cn/application-dev/work-scheduler/work-scheduler-overview.md
浏览文件 @ 0337850f
......@@ -10,7 +10,7 @@
延迟调度任务的使用需要遵从如下约束和规则：
- **超时**：每次最长运行120秒，超时之后，系统会主动停止。
- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。
- **WorkInfo设置参数约束**
（1） workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或