Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 1ebbbd17 编写于 作者: 朱 朱天怡 提交者： Gitee
浏览文件
操作

修改 

Signed-off-by: N朱天怡 <zhutianyi2@huawei.com>
上级 3aa79ec5
显示空白变更内容
内联 并排
Showing with 1075 addition and 556 deletion
zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md
浏览文件 @ 1ebbbd17
...@@ -14,13 +14,15 @@ ...@@ -14,13 +14,15 @@
> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。从API version 9开始，导入模块由@ohos.backgroundTaskManager迁移至@ohos.resourceschedule.backgroundTaskManager > - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。从API version 9开始，导入模块由@ohos.backgroundTaskManager迁移至@ohos.resourceschedule.backgroundTaskManager
> - 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。 > - 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。
## 导入模块 ## 导入模块
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
``` ```
## backgroundTaskManager.requestSuspendDelay<sup>9+</sup>
## backgroundTaskManager.requestSuspendDelay<sup>(deprecated)</sup>
requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspendInfo requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspendInfo
...@@ -28,7 +30,9 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen ...@@ -28,7 +30,9 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen
延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.requestSuspendDelay](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerrequestsuspenddelay9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
...@@ -46,30 +50,29 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen ...@@ -46,30 +50,29 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
let myReason = 'test requestSuspendDelay'; let myReason = 'test requestSuspendDelay';
try {
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out."); console.info("Request suspension delay will time out.");
}) })
var id = delayInfo.requestId; var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime; var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id); console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time); console.info("The actualDelayTime is: " + time);
} catch (error) {
console.error(`requestSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## backgroundTaskManager.getRemainingDelayTime<sup>9+</sup> ## backgroundTaskManager.getRemainingDelayTime<sup>7+(deprecated)</sup>
getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void
获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.getRemainingDelayTime](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagergetremainingdelaytimecallback9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
...@@ -82,30 +85,28 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): ...@@ -82,30 +85,28 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;):
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
let id = 1; let id = 1;
try { backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
backgroundTaskManager.getRemainingDelayTime(id, (error, res) => { if(err) {
if(error) { console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code);
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
} else { } else {
console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
} }
}) })
} catch (error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## backgroundTaskManager.getRemainingDelayTime<sup>9+</sup> ## backgroundTaskManager.getRemainingDelayTime<sup>7+(deprecated)</sup>
getRemainingDelayTime(requestId: number): Promise&lt;number&gt; getRemainingDelayTime(requestId: number): Promise&lt;number&gt;
获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.getRemainingDelayTime](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagergetremainingdelaytimepromise9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
...@@ -121,28 +122,26 @@ getRemainingDelayTime(requestId: number): Promise&lt;number&gt; ...@@ -121,28 +122,26 @@ getRemainingDelayTime(requestId: number): Promise&lt;number&gt;
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
let id = 1; let id = 1;
try {
backgroundTaskManager.getRemainingDelayTime(id).then( res => { backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( error => { }).catch( err => {
console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
}) })
} catch (error) {
console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## backgroundTaskManager.cancelSuspendDelay<sup>9+</sup> ## backgroundTaskManager.cancelSuspendDelay<sup>7+(deprecated)</sup>
cancelSuspendDelay(requestId: number): void cancelSuspendDelay(requestId: number): void
取消延迟挂起。 取消延迟挂起。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.cancelSuspendDelay](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagercancelsuspenddelay9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
...@@ -153,24 +152,22 @@ cancelSuspendDelay(requestId: number): void ...@@ -153,24 +152,22 @@ cancelSuspendDelay(requestId: number): void
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
let id = 1; let id = 1;
try {
backgroundTaskManager.cancelSuspendDelay(id); backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## backgroundTaskManager.startBackgroundRunning<sup>9+</sup> ## backgroundTaskManager.startBackgroundRunning<sup>8+(deprecated)</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
向系统申请长时任务，使用callback形式返回结果。 向系统申请长时任务，使用callback形式返回结果。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.startBackgroundRunning](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstartbackgroundrunningcallback9)
>
> 从 API version 7开始支持。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING **需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
...@@ -186,13 +183,13 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want ...@@ -186,13 +183,13 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent'; import wantAgent from '@ohos.wantAgent';
function callback(error, data) { function callback(err, data) {
if (error) { if (err) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); console.error("Operation startBackgroundRunning failed Cause: " + err);
} else { } else {
console.info("Operation startBackgroundRunning succeeded"); console.info("Operation startBackgroundRunning succeeded");
} }
...@@ -211,23 +208,21 @@ let wantAgentInfo = { ...@@ -211,23 +208,21 @@ let wantAgentInfo = {
}; };
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback) backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback)
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}); });
``` ```
## backgroundTaskManager.startBackgroundRunning<sup>9+</sup> ## backgroundTaskManager.startBackgroundRunning<sup>8+(deprecated)</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt; startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
向系统申请长时任务，使用promise形式返回结果。 向系统申请长时任务，使用promise形式返回结果。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.startBackgroundRunning](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstartbackgroundrunningpromise9)
>
> 从 API version 7开始支持。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING **需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
...@@ -248,7 +243,7 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want ...@@ -248,7 +243,7 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent'; import wantAgent from '@ohos.wantAgent';
...@@ -265,27 +260,25 @@ let wantAgentInfo = { ...@@ -265,27 +260,25 @@ let wantAgentInfo = {
}; };
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded"); console.info("Operation startBackgroundRunning succeeded");
}).catch((error) => { }).catch((err) => {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); console.error("Operation startBackgroundRunning failed Cause: " + err);
}); });
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}); });
``` ```
## backgroundTaskManager.stopBackgroundRunning<sup>9+</sup> ## backgroundTaskManager.stopBackgroundRunning<sup>8+(deprecated)</sup>
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
向系统申请取消长时任务，使用callback形式返回结果。 向系统申请取消长时任务，使用callback形式返回结果。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.stopBackgroundRunning](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstopbackgroundrunningcallback9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
...@@ -297,32 +290,30 @@ stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): vo ...@@ -297,32 +290,30 @@ stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): vo
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
function callback(error, data) { function callback(err, data) {
if (error) { if (err) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); console.error("Operation stopBackgroundRunning failed Cause: " + err);
} else { } else {
console.info("Operation stopBackgroundRunning succeeded"); console.info("Operation stopBackgroundRunning succeeded");
} }
} }
try { backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## backgroundTaskManager.stopBackgroundRunning<sup>9+</sup> ## backgroundTaskManager.stopBackgroundRunning<sup>8+(deprecated)</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt; stopBackgroundRunning(context: Context): Promise&lt;void&gt;
向系统申请取消长时任务，使用promise形式返回结果。 向系统申请取消长时任务，使用promise形式返回结果。
> 从 API version 9开始支持。 > **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.stopBackgroundRunning](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerstopbackgroundrunningpromise9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
...@@ -338,28 +329,26 @@ stopBackgroundRunning(context: Context): Promise&lt;void&gt; ...@@ -338,28 +329,26 @@ stopBackgroundRunning(context: Context): Promise&lt;void&gt;
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
try { backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded"); console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); console.error("Operation stopBackgroundRunning failed Cause: " + err);
}); });
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## backgroundTaskManager.applyEfficiencyResources<sup>9+</sup> ## backgroundTaskManager.applyEfficiencyResources<sup>9+(deprecated)</sup>
applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): void applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): void
向系统申请能效资源，使用boolean形式返回结果。 向系统申请能效资源，使用boolean形式返回结果。
进程和它所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。 进程和它所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.applyEfficiencyResources](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerapplyefficiencyresources9)
>
> 从 API version 9开始支持。 > 从 API version 9开始支持。
**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
...@@ -375,7 +364,7 @@ applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresour ...@@ -375,7 +364,7 @@ applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresour
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
let request = { let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU, resourceTypes: backgroundTaskManager.ResourceType.CPU,
...@@ -393,12 +382,14 @@ try { ...@@ -393,12 +382,14 @@ try {
} }
``` ```
## backgroundTaskManager.resetAllEfficiencyResources<sup>9+</sup> ## backgroundTaskManager.resetAllEfficiencyResources<sup>9+(deprecated)</sup>
resetAllEfficiencyResources(): void resetAllEfficiencyResources(): void
释放所有已经申请的资源。 释放所有已经申请的资源。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.resetAllEfficiencyResources](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerresetallefficiencyresources9)
>
> 从 API version 9开始支持。 > 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
...@@ -408,7 +399,7 @@ resetAllEfficiencyResources(): void ...@@ -408,7 +399,7 @@ resetAllEfficiencyResources(): void
**示例**： **示例**：
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
try { try {
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
...@@ -417,10 +408,14 @@ try { ...@@ -417,10 +408,14 @@ try {
} }
``` ```
## DelaySuspendInfo<sup>9+</sup> ## DelaySuspendInfo<sup>7+(deprecated)</sup>
延迟挂起信息。 延迟挂起信息。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.DelaySuspendInfo](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerdelaysuspendinfo9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
...@@ -429,7 +424,7 @@ try { ...@@ -429,7 +424,7 @@ try {
| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | | actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 |
## BackgroundMode<sup>9+</sup> ## BackgroundMode<sup>8+(deprecated)</sup>
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
...@@ -445,10 +440,14 @@ try { ...@@ -445,10 +440,14 @@ try {
| VOIP | 8 | 音视频通话<br />此接口为系统接口。 | | VOIP | 8 | 音视频通话<br />此接口为系统接口。 |
| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效）。 | | TASK_KEEPING | 9 | 计算任务（仅在特定设备生效）。 |
## EfficiencyResourcesRequest<sup>9+</sup> ## EfficiencyResourcesRequest<sup>9+(deprecated)</sup>
能效资源申请参数。 能效资源申请参数。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.EfficiencyResourcesRequest](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerefficiencyresourcesrequest9)
>
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**系统API**: 此接口为系统接口。 **系统API**: 此接口为系统接口。
...@@ -462,10 +461,14 @@ try { ...@@ -462,10 +461,14 @@ try {
| isProcess | boolean | 否 | 应用申请或者是进程申请。 | | isProcess | boolean | 否 | 应用申请或者是进程申请。 |
| reason | string | 是 | 申请资源的原因。 | | reason | string | 是 | 申请资源的原因。 |
## ResourceType<sup>9+</sup> ## ResourceType<sup>9+(deprecated)</sup>
能效资源类型。 能效资源类型。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.ResourceType](../js-apis-resourceschedule-backgroundTaskManager.md/#backgroundtaskmanagerresourcetype9)
>
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**系统API**: 此接口为系统接口。 **系统API**: 此接口为系统接口。
...@@ -479,366 +482,3 @@ try { ...@@ -479,366 +482,3 @@ try {
| BLUETOOTH | 16 | 蓝牙相关，申请后挂起状态下不被代理掉。 | | BLUETOOTH | 16 | 蓝牙相关，申请后挂起状态下不被代理掉。 |
| GPS | 32 | GPS相关，申请后挂起状态下不被代理掉。 | | GPS | 32 | GPS相关，申请后挂起状态下不被代理掉。 |
| AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉。 | | AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉。 |
\ No newline at end of file
## 导入模块
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
```
## backgroundTaskManager.requestSuspendDelay<sup>(deprecated)</sup>
requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspendInfo
后台应用申请延迟挂起。
延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------ |
| reason | string | 是 | 延迟挂起申请的原因。 |
| callback | Callback&lt;void&gt; | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 |
**返回值**：
| 类型 | 说明 |
| ------------------------------------- | --------- |
| [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
})
var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
```
## backgroundTaskManager.getRemainingDelayTime<sup>7+(deprecated)</sup>
getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void
获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.getRemainingDelayTime](#backgroundtaskmanagergetremainingdelaytime9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | --------------------------- | ---- | ---------------------------------------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| callback | AsyncCallback&lt;number&gt; | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
if(err) {
console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code);
} else {
console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}
})
```
## backgroundTaskManager.getRemainingDelayTime<sup>7+(deprecated)</sup>
getRemainingDelayTime(requestId: number): Promise&lt;number&gt;
获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.getRemainingDelayTime](#backgroundtaskmanagergetremainingdelaytime9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ---------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
**返回值**：
| 类型 | 说明 |
| --------------------- | ---------------------------------------- |
| Promise&lt;number&gt; | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => {
console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
})
```
## backgroundTaskManager.cancelSuspendDelay<sup>7+(deprecated)</sup>
cancelSuspendDelay(requestId: number): void
取消延迟挂起。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.cancelSuspendDelay](#backgroundtaskmanagercancelsuspenddelay9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ---------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let id = 1;
backgroundTaskManager.cancelSuspendDelay(id);
```
## backgroundTaskManager.startBackgroundRunning<sup>8+(deprecated)</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
向系统申请长时任务，使用callback形式返回结果。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.startBackgroundRunning](#backgroundtaskmanagerstartbackgroundrunning9)
>
> 从 API version 7开始支持。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 |
| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击后跳转的界面。 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果。 |
**示例**：
```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 startBackgroundRunning failed Cause: " + err);
} else {
console.info("Operation startBackgroundRunning succeeded");
}
}
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback)
});
```
## backgroundTaskManager.startBackgroundRunning<sup>8+(deprecated)</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
向系统申请长时任务，使用promise形式返回结果。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.startBackgroundRunning](#backgroundtaskmanagerstartbackgroundrunning9)
>
> 从 API version 7开始支持。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 |
| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。 |
**返回值**：
| 类型 | 说明 |
| -------------- | ---------------- |
| 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_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
});
```
## backgroundTaskManager.stopBackgroundRunning<sup>8+(deprecated)</sup>
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
向系统申请取消长时任务，使用callback形式返回结果。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.stopBackgroundRunning](#backgroundtaskmanagerstopbackgroundrunning9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
function callback(err, data) {
if (err) {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
} else {
console.info("Operation stopBackgroundRunning succeeded");
}
}
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);
```
## backgroundTaskManager.stopBackgroundRunning<sup>8+(deprecated)</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt;
向系统申请取消长时任务，使用promise形式返回结果。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.stopBackgroundRunning](#backgroundtaskmanagerstopbackgroundrunning9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
**返回值**：
| 类型 | 说明 |
| -------------- | ---------------- |
| Promise\<void> | 使用Promise形式返回结果。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
```
## DelaySuspendInfo<sup>7+(deprecated)</sup>
延迟挂起信息。
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.DelaySuspendInfo](#backgroundtaskmanagerdelaysuspendinfo9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 参数名 | 类型 | 必填 | 说明 |
| --------------- | ------ | ---- | ---------------------------------------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 |
## BackgroundMode<sup>8+(deprecated)</sup>
> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.BackgroundMode](#backgroundtaskmanagerbackgroundmode9)
>
> 从 API version 7开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
| 参数名 | 参数值 | 描述 |
| ----------------------- | ---- | --------------------- |
| DATA_TRANSFER | 1 | 数据传输。 |
| AUDIO_PLAYBACK | 2 | 音频播放。 |
| AUDIO_RECORDING | 3 | 录音。 |
| LOCATION | 4 | 定位导航。 |
| BLUETOOTH_INTERACTION | 5 | 蓝牙相关。 |
| MULTI_DEVICE_CONNECTION | 6 | 多设备互联。 |
| WIFI_INTERACTION | 7 | WLAN相关<br />此接口为系统接口。 |
| VOIP | 8 | 音视频通话<br />此接口为系统接口。 |
| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效）。 |
zh-cn/application-dev/reference/apis/js-apis-resourceschedule-backgroundTaskManager.md 0 → 100644
浏览文件 @ 1ebbbd17
# 后台任务管理
本模块提供后台任务管理能力。
当应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。
应用有不可中断且短时间能完成的任务时（如，用户在文件管理器上点击垃圾文件清理，若清理未完成时退到后台，文件管理器需要申请短时任务完成清理），可以使用短时任务机制。
应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。
对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。
> **说明：**
> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。从API version 9开始，导入模块由@ohos.backgroundTaskManager迁移至@ohos.resourceschedule.backgroundTaskManager
> - 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。
## 导入模块
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
```
## backgroundTaskManager.requestSuspendDelay<sup>9+</sup>
requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspendInfo
后台应用申请延迟挂起。
延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------ |
| reason | string | 是 | 延迟挂起申请的原因。 |
| callback | Callback&lt;void&gt; | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 |
**返回值**：
| 类型 | 说明 |
| ------------------------------------- | --------- |
| [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
try {
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
})
var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
} catch (error) {
console.error(`requestSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.getRemainingDelayTime:callback<sup>9+</sup>
getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void
获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | --------------------------- | ---- | ---------------------------------------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| callback | AsyncCallback&lt;number&gt; | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let id = 1;
try {
backgroundTaskManager.getRemainingDelayTime(id, (error, res) => {
if(error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
} else {
console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}
})
} catch (error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.getRemainingDelayTime:promise<sup>9+</sup>
getRemainingDelayTime(requestId: number): Promise&lt;number&gt;
获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ---------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
**返回值**：
| 类型 | 说明 |
| --------------------- | ---------------------------------------- |
| Promise&lt;number&gt; | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let id = 1;
try {
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( error => {
console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
})
} catch (error) {
console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.cancelSuspendDelay<sup>9+</sup>
cancelSuspendDelay(requestId: number): void
取消延迟挂起。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ---------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let id = 1;
try {
backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.startBackgroundRunning:callback<sup>9+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
向系统申请长时任务，使用callback形式返回结果。
> 从 API version 9开始支持。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 |
| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击后跳转的界面。 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';
function callback(error, data) {
if (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
} else {
console.info("Operation startBackgroundRunning succeeded");
}
}
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback)
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
```
## backgroundTaskManager.startBackgroundRunning:promise<sup>9+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
向系统申请长时任务，使用promise形式返回结果。
> 从 API version 9开始支持。
**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 |
| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。 |
**返回值**：
| 类型 | 说明 |
| -------------- | ---------------- |
| Promise\<void> | 使用Promise形式返回结果。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.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_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((error) => {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
```
## backgroundTaskManager.stopBackgroundRunning:callback<sup>9+</sup>
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
向系统申请取消长时任务，使用callback形式返回结果。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
| callback | AsyncCallback&lt;void&gt; | 是 | callback形式返回启动长时任务的结果。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
function callback(error, data) {
if (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
} else {
console.info("Operation stopBackgroundRunning succeeded");
}
}
try {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.stopBackgroundRunning:promise<sup>9+</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt;
向系统申请取消长时任务，使用promise形式返回结果。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------- | ---- | ---------------------------------------- |
| context | Context | 是 | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
**返回值**：
| 类型 | 说明 |
| -------------- | ---------------- |
| Promise\<void> | 使用Promise形式返回结果。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
try {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.applyEfficiencyResources<sup>9+</sup>
applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): void
向系统申请能效资源，使用boolean形式返回结果。
进程和它所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。
> 从 API version 9开始支持。
**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**系统API**: 此接口为系统接口。
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------- | ---- | ---------------------------------------- |
| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是 | 请求的必要信息。包括资源类型，超时时间等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 |
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: false,
};
try {
backgroundTaskManager.applyEfficiencyResources(request);
console.info("applyEfficiencyResources success. ");
} catch (error) {
console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.resetAllEfficiencyResources<sup>9+</sup>
resetAllEfficiencyResources(): void
释放所有已经申请的资源。
> 从 API version 9开始支持。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**系统API**: 此接口为系统接口。
**示例**：
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
try {
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) {
console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
## DelaySuspendInfo<sup>9+</sup>
延迟挂起信息。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 参数名 | 类型 | 必填 | 说明 |
| --------------- | ------ | ---- | ---------------------------------------- |
| requestId | number | 是 | 延迟挂起的请求ID。 |
| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。<br/>一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 |
## BackgroundMode<sup>9+</sup>
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
| 参数名 | 参数值 | 描述 |
| ----------------------- | ---- | --------------------- |
| DATA_TRANSFER | 1 | 数据传输。 |
| AUDIO_PLAYBACK | 2 | 音频播放。 |
| AUDIO_RECORDING | 3 | 录音。 |
| LOCATION | 4 | 定位导航。 |
| BLUETOOTH_INTERACTION | 5 | 蓝牙相关。 |
| MULTI_DEVICE_CONNECTION | 6 | 多设备互联。 |
| WIFI_INTERACTION | 7 | WLAN相关<br />此接口为系统接口。 |
| VOIP | 8 | 音视频通话<br />此接口为系统接口。 |
| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效）。 |
## EfficiencyResourcesRequest<sup>9+</sup>
能效资源申请参数。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**系统API**: 此接口为系统接口。
| 参数名 | 类型 | 必填 | 说明 |
| --------------- | ------ | ---- | ---------------------------------------- |
| resourceTypes | number | 是 | 申请的资源类型。 |
| isApply | boolean | 是 | 申请资源或者是释放资源。 |
| timeOut | number | 是 | 资源的使用时间，以毫秒为单位。 |
| isPersist | boolean | 否 | 是否永久持有资源，如果是true，那么timeOut就无效。 |
| isProcess | boolean | 否 | 应用申请或者是进程申请。 |
| reason | string | 是 | 申请资源的原因。 |
## ResourceType<sup>9+</sup>
能效资源类型。
**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**系统API**: 此接口为系统接口。
| 参数名 | 参数值 | 描述 |
| ----------------------- | ---- | --------------------- |
| CPU | 1 | CPU资源，申请后不被挂起。 |
| COMMON_EVENT | 2 | 公共事件，申请后挂起状态下不被代理掉。 |
| TIMER | 4 | 计时器，申请后挂起状态下不被代理掉。 |
| WORK_SCHEDULER | 8 | 延迟任务，申请后有更长的执行时间。 |
| BLUETOOTH | 16 | 蓝牙相关，申请后挂起状态下不被代理掉。 |
| GPS | 32 | GPS相关，申请后挂起状态下不被代理掉。 |
| AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉。 |
zh-cn/application-dev/reference/apis/js-apis-resourceschedule.workScheduler.md 0 → 100644
浏览文件 @ 1ebbbd17
# 延迟任务调度
本模块提供延迟任务注册、取消、查询的能力。
开发者在开发应用时，通过调用延迟任务注册接口，注册对实时性要求不高的延迟任务，该任务默认由系统安排，在系统空闲时根据性能、功耗、热等情况进行调度执行。
> **说明：**
>
> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 本模块接口仅可在Stage模型下使用。
> - 延迟任务调度约束见[延迟任务调度概述](../../task-management/work-scheduler-overview.md)。
> - 延迟任务调度错误码见[workScheduler错误码](../errorcodes/errorcode-workScheduler.md)。
## 导入模块
```js
import workScheduler from '@ohos.resourceschedule.workScheduler';
```
## workScheduler.startWork<sup>9+</sup>
startWork(work: WorkInfo): void
通知WorkSchedulerService将工作添加到执行队列。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ---- | --------------------- | ---- | -------------- |
| work | [WorkInfo](#workinfo) | 是 | 指示要添加到执行队列的工作。 |
**示例**：
```js
let workInfo = {
workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false,
isPersisted: true,
bundleName: "com.example.myapplication",
abilityName: "MyExtension",
parameters: {
mykey0: 1,
mykey1: "string value",
mykey2: true,
mykey3: 1.5
}
}
try{
workScheduler.startWork(workInfo);
console.info('workschedulerLog startWork success');
} catch (error) {
console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.stopWork<sup>9+</sup>
stopWork(work: WorkInfo, needCancel?: boolean): void
通知WorkSchedulerService停止指定工作。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | --------------------- | ---- | ---------- |
| work | [WorkInfo](#workinfo) | 是 | 指示要停止的工作。 |
| needCancel | boolean | 是 | 是否需要取消的工作。 |
**示例**：
```js
let workInfo = {
workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false,
isPersisted: true,
bundleName: "com.example.myapplication",
abilityName: "MyExtension",
parameters: {
mykey0: 1,
mykey1: "string value",
mykey2: true,
mykey3: 1.5
}
}
try{
workScheduler.stopWork(workInfo, false);
console.info('workschedulerLog stopWork success');
} catch (error) {
console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.getWorkStatus:callback<sup>9+</sup>
getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void
获取工作的最新状态，使用Callback形式返回。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------- | ---- | ---------------------------------------- |
| workId | number | 是 | work的id。 |
| callback | AsyncCallback\<[WorkInfo](#workinfo)> | 是 | 指定的callback回调方法。如果指定的工作Id有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。 |
**示例**：
```js
try{
workScheduler.getWorkStatus(50, (error, res) => {
if (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
} else {
for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
}
}
});
} catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.getWorkStatus:promise<sup>9+</sup>
getWorkStatus(workId: number): Promise\<WorkInfo>
获取工作的最新状态，使用Promise形式返回。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------- |
| workId | number | 是 | work的id。 |
**返回值**：
| 类型 | 说明 |
| ------------------------------- | ---------------------------------------- |
| Promise\<[WorkInfo](#workinfo)> | 指定的Promise回调方法。如果指定的工作ID有效，则返回从WorkSchedulerService获取的有效工作状态；否则返回null。 |
**示例**：
```js
try{
workScheduler.getWorkStatus(50).then((res) => {
for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
}
}).catch((error) => {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
})
} catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.obtainAllWorks:callback<sup>9+</sup>
obtainAllWorks(callback : AsyncCallback\<void>): Array\<WorkInfo>
获取与当前应用程序关联的所有工作，使用Callback形式返回。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------- |
| callback | AsyncCallback\<void> | 是 | 指定的callback回调方法。返回与应用程序关联的所有工作。 |
**返回值**：
| 类型 | 说明 |
| ----------------------------- | --------------- |
| Array\<[WorkInfo](#workinfo)> | 返回与应用程序关联的所有工作。 |
**示例**：
```js
try{
workScheduler.obtainAllWorks((error, res) =>{
if (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
} else {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
}
});
} catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.obtainAllWorks:promise<sup>9+</sup>
obtainAllWorks(): Promise<Array\<WorkInfo>>
获取与当前应用程序关联的所有工作，使用Promise形式返回。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**返回值**：
| 类型 | 说明 |
| -------------------------------------- | ------------------------------ |
| Promise<Array\<[WorkInfo](#workinfo)>> | 指定的Promise回调方法。返回与应用程序关联的所有工作。 |
**示例**：
```js
try{
workScheduler.obtainAllWorks().then((res) => {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
}).catch((error) => {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
})
} catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.stopAndClearWorks
stopAndClearWorks(): void
停止和取消与当前应用程序关联的所有工作。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**示例**：
```js
try{
workScheduler.stopAndClearWorks();
console.info(`workschedulerLog stopAndClearWorks success`);
} catch (error) {
console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.isLastWorkTimeOut:callback<sup>9+</sup>
isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean
检查指定工作的最后一次执行是否为超时操作，使用Callback形式返回。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------------------- |
| workId | number | 是 | work的id。 |
| callback | AsyncCallback\<void> | 是 | 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 |
**返回值**：
| 类型 | 说明 |
| ------- | ---------------------------------------- |
| boolean | 指定的callback回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 |
**示例**：
```js
try{
workScheduler.isLastWorkTimeOut(500, (error, res) =>{
if (error) {
onsole.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
} else {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
}
});
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
}
```
## workScheduler.isLastWorkTimeOut:promise<sup>9+</sup>
isLastWorkTimeOut(workId: number): Promise\<boolean>
检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------- |
| workId | number | 是 | work的id。 |
**返回值**：
| 类型 | 说明 |
| ----------------- | ---------------------------------------- |
| Promise\<boolean> | 指定的Promise回调方法。如果指定工作的最后一次执行是超时操作，则返回true；否则返回false。 |
**示例**：
```js
try{
workScheduler.isLastWorkTimeOut(500)
.then(res => {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
})
.catch(error => {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
}
```
## WorkInfo
提供工作的具体信息。WorkInfo设置参数约束见[延迟任务调度概述](../../task-management/work-scheduler-overview.md)
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
| 参数名 | 类型 | 必填 | 说明 |
| --------------- | --------------------------------- | ---- | ---------------- |
| workId | number | 是 | 当前工作的ID |
| bundleName | string | 是 | 延迟任务包名 |
| abilityName | string | 是 | 延迟任务回调通知的组件名（必填） |
| networkType | [NetworkType](#networktype) | 否 | 网络类型 |
| isCharging | boolean | 否 | 是否充电 |
| chargerType | [ChargingType](#chargingtype) | 否 | 充电类型 |
| batteryLevel | number | 否 | 电量 |
| batteryStatus | [BatteryStatus](#batterystatus) | 否 | 电池状态 |
| storageRequest | [StorageRequest](#storagerequest) | 否 | 存储状态 |
| isRepeat | boolean | 否 | 是否循环任务 |
| repeatCycleTime | number | 否 | 循环间隔 |
| repeatCount | number | 否 | 循环次数 |
| isPersisted | boolean | 否 | 是否持久化保存工作 |
| isDeepIdle | boolean | 否 | 是否要求设备进入空闲状态 |
| idleWaitTime | number | 否 | 空闲等待时间 |
| parameters | {[key: string]: any} | 否 | 携带参数信息 |
## 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 | 表示这个触发条件是有线网络连接。 |
## ChargingType
触发工作的充电类型。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
| 名称 | 默认值 | 说明 |
| ------------------------- | ---- | -------------------- |
| CHARGING_PLUGGED_ANY | 0 | 表示这个触发条件是任何类型的充电器连接。 |
| CHARGING_PLUGGED_AC | 1 | 表示这个触发条件是直流充电器连接。 |
| CHARGING_PLUGGED_USB | 2 | 表示这个触发条件是USB充连接。 |
| CHARGING_PLUGGED_WIRELESS | 3 | 表示这个触发条件是无线充电器连接。 |
## BatteryStatus
触发工作的电池状态。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
| 名称 | 默认值 | 说明 |
| -------------------------- | ---- | -------------------------- |
| BATTERY_STATUS_LOW | 0 | 表示这个触发条件是低电告警。 |
| BATTERY_STATUS_OKAY | 1 | 表示这个触发条件是从低电恢复到正常电量。 |
| BATTERY_STATUS_LOW_OR_OKAY | 2 | 表示这个触发条件是从低电恢复到正常电量或者低电告警。 |
## 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-workScheduler.md
浏览文件 @ 1ebbbd17
...@@ -9,7 +9,6 @@ ...@@ -9,7 +9,6 @@
> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 本模块接口仅可在Stage模型下使用。 > - 本模块接口仅可在Stage模型下使用。
> - 延迟任务调度约束见[延迟任务调度概述](../../task-management/work-scheduler-overview.md)。 > - 延迟任务调度约束见[延迟任务调度概述](../../task-management/work-scheduler-overview.md)。
> - 延迟任务调度错误码见[workScheduler错误码](../errorcodes/errorcode-workScheduler.md)。
## 导入模块 ## 导入模块
...@@ -19,10 +18,14 @@ import workScheduler from '@ohos.workScheduler'; ...@@ -19,10 +18,14 @@ import workScheduler from '@ohos.workScheduler';
``` ```
## workScheduler.startWork ## workScheduler.startWork
startWork(work: WorkInfo): void startWork(work: WorkInfo): boolean
通知WorkSchedulerService将工作添加到执行队列。 通知WorkSchedulerService将工作添加到执行队列。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.startWork](../js-apis-resourceschedule-workScheduler.md/#workschedulerstartwork9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -31,6 +34,12 @@ startWork(work: WorkInfo): void ...@@ -31,6 +34,12 @@ startWork(work: WorkInfo): void
| ---- | --------------------- | ---- | -------------- | | ---- | --------------------- | ---- | -------------- |
| work | [WorkInfo](#workinfo) | 是 | 指示要添加到执行队列的工作。 | | work | [WorkInfo](#workinfo) | 是 | 指示要添加到执行队列的工作。 |
**返回值**：
| 类型 | 说明 |
| ------- | -------------------------------- |
| boolean | 如果工作成功添加到执行队列，则返回true，否则返回false。 |
**示例**： **示例**：
```js ```js
...@@ -48,19 +57,19 @@ startWork(work: WorkInfo): void ...@@ -48,19 +57,19 @@ startWork(work: WorkInfo): void
mykey3: 1.5 mykey3: 1.5
} }
} }
try{ var res = workScheduler.startWork(workInfo);
workScheduler.startWork(workInfo); console.info(`workschedulerLog res: ${res}`);
console.info('workschedulerLog startWork success');
} catch (error) {
console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.stopWork ## workScheduler.stopWork
stopWork(work: WorkInfo, needCancel?: boolean): void stopWork(work: WorkInfo, needCancel?: boolean): boolean
通知WorkSchedulerService停止指定工作。 通知WorkSchedulerService停止指定工作。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.stopWork](../js-apis-resourceschedule-workScheduler.md/#workschedulerstopwork9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -70,6 +79,12 @@ stopWork(work: WorkInfo, needCancel?: boolean): void ...@@ -70,6 +79,12 @@ stopWork(work: WorkInfo, needCancel?: boolean): void
| work | [WorkInfo](#workinfo) | 是 | 指示要停止的工作。 | | work | [WorkInfo](#workinfo) | 是 | 指示要停止的工作。 |
| needCancel | boolean | 是 | 是否需要取消的工作。 | | needCancel | boolean | 是 | 是否需要取消的工作。 |
**返回值**：
| 类型 | 说明 |
| ------- | ----------------------- |
| boolean | 如果成功，则返回true，否则返回false。 |
**示例**： **示例**：
```js ```js
...@@ -87,12 +102,8 @@ stopWork(work: WorkInfo, needCancel?: boolean): void ...@@ -87,12 +102,8 @@ stopWork(work: WorkInfo, needCancel?: boolean): void
mykey3: 1.5 mykey3: 1.5
} }
} }
try{ var res = workScheduler.stopWork(workInfo, false);
workScheduler.stopWork(workInfo, false); console.info(`workschedulerLog res: ${res}`);
console.info('workschedulerLog stopWork success');
} catch (error) {
console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.getWorkStatus ## workScheduler.getWorkStatus
...@@ -100,6 +111,10 @@ getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void ...@@ -100,6 +111,10 @@ getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void
获取工作的最新状态，使用Callback形式返回。 获取工作的最新状态，使用Callback形式返回。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.getWorkStatus](../js-apis-resourceschedule-workScheduler.md/#workschedulergetworkstatuscallback9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -112,19 +127,15 @@ getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void ...@@ -112,19 +127,15 @@ getWorkStatus(workId: number, callback : AsyncCallback\<WorkInfo>): void
**示例**： **示例**：
```js ```js
try{ workScheduler.getWorkStatus(50, (err, res) => {
workScheduler.getWorkStatus(50, (error, res) => { if (err) {
if (error) { console.info(`workschedulerLog getWorkStatus failed, because: ${err.code}`);
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
} else { } else {
for (let item in res) { for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`); console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
} }
} }
}); });
} catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.getWorkStatus ## workScheduler.getWorkStatus
...@@ -132,6 +143,10 @@ getWorkStatus(workId: number): Promise\<WorkInfo> ...@@ -132,6 +143,10 @@ getWorkStatus(workId: number): Promise\<WorkInfo>
获取工作的最新状态，使用Promise形式返回。 获取工作的最新状态，使用Promise形式返回。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.getWorkStatus](../js-apis-resourceschedule-workScheduler.md/#workschedulergetworkstatuspromise9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -149,17 +164,13 @@ getWorkStatus(workId: number): Promise\<WorkInfo> ...@@ -149,17 +164,13 @@ getWorkStatus(workId: number): Promise\<WorkInfo>
**示例**： **示例**：
```js ```js
try{
workScheduler.getWorkStatus(50).then((res) => { workScheduler.getWorkStatus(50).then((res) => {
for (let item in res) { for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`); console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
} }
}).catch((error) => { }).catch((err) => {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`); console.info(`workschedulerLog getWorkStatus failed, because: ${err.code}`);
}) })
} catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.obtainAllWorks ## workScheduler.obtainAllWorks
...@@ -167,6 +178,10 @@ obtainAllWorks(callback : AsyncCallback\<void>): Array\<WorkInfo> ...@@ -167,6 +178,10 @@ obtainAllWorks(callback : AsyncCallback\<void>): Array\<WorkInfo>
获取与当前应用程序关联的所有工作，使用Callback形式返回。 获取与当前应用程序关联的所有工作，使用Callback形式返回。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.obtainAllWorks](../js-apis-resourceschedule-workScheduler.md/#workschedulerobtainallworkscallback9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -184,17 +199,13 @@ obtainAllWorks(callback : AsyncCallback\<void>): Array\<WorkInfo> ...@@ -184,17 +199,13 @@ obtainAllWorks(callback : AsyncCallback\<void>): Array\<WorkInfo>
**示例**： **示例**：
```js ```js
try{ workScheduler.obtainAllWorks((err, res) =>{
workScheduler.obtainAllWorks((error, res) =>{ if (err) {
if (error) { console.info(`workschedulerLog obtainAllWorks failed, because: ${err.code}`);
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
} else { } else {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`); console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
} }
}); });
} catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.obtainAllWorks ## workScheduler.obtainAllWorks
...@@ -202,6 +213,10 @@ obtainAllWorks(): Promise<Array\<WorkInfo>> ...@@ -202,6 +213,10 @@ obtainAllWorks(): Promise<Array\<WorkInfo>>
获取与当前应用程序关联的所有工作，使用Promise形式返回。 获取与当前应用程序关联的所有工作，使用Promise形式返回。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.obtainAllWorks](../js-apis-resourceschedule-workScheduler.md/#workschedulerobtainallworkspromise9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**返回值**： **返回值**：
...@@ -213,33 +228,29 @@ obtainAllWorks(): Promise<Array\<WorkInfo>> ...@@ -213,33 +228,29 @@ obtainAllWorks(): Promise<Array\<WorkInfo>>
**示例**： **示例**：
```js ```js
try{
workScheduler.obtainAllWorks().then((res) => { workScheduler.obtainAllWorks().then((res) => {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`); console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
}).catch((error) => { }).catch((err) => {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`); console.info(`workschedulerLog obtainAllWorks failed, because: ${err.code}`);
}) })
} catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.stopAndClearWorks ## workScheduler.stopAndClearWorks
stopAndClearWorks(): void stopAndClearWorks(): boolean
停止和取消与当前应用程序关联的所有工作。 停止和取消与当前应用程序关联的所有工作。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.stopAndClearWorks](../js-apis-resourceschedule-workScheduler.md/#workschedulerstopandclearworks9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**示例**： **示例**：
```js ```js
try{ let res = workScheduler.stopAndClearWorks();
workScheduler.stopAndClearWorks(); console.info(`workschedulerLog res: ${res}`);
console.info(`workschedulerLog stopAndClearWorks success`);
} catch (error) {
console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.isLastWorkTimeOut ## workScheduler.isLastWorkTimeOut
...@@ -247,6 +258,10 @@ isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean ...@@ -247,6 +258,10 @@ isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean
检查指定工作的最后一次执行是否为超时操作，使用Callback形式返回。 检查指定工作的最后一次执行是否为超时操作，使用Callback形式返回。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.isLastWorkTimeOut](../js-apis-resourceschedule-workScheduler.md/#workschedulerisLastworktimeoutcallback9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -265,17 +280,13 @@ isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean ...@@ -265,17 +280,13 @@ isLastWorkTimeOut(workId: number, callback : AsyncCallback\<void>): boolean
**示例**： **示例**：
```js ```js
try{ workScheduler.isLastWorkTimeOut(500, (err, res) =>{
workScheduler.isLastWorkTimeOut(500, (error, res) =>{ if (err) {
if (error) { console.info(`workschedulerLog isLastWorkTimeOut failed, because: ${err.code}`);
onsole.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
} else { } else {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`); console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
} }
}); });
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## workScheduler.isLastWorkTimeOut ## workScheduler.isLastWorkTimeOut
...@@ -283,6 +294,10 @@ isLastWorkTimeOut(workId: number): Promise\<boolean> ...@@ -283,6 +294,10 @@ isLastWorkTimeOut(workId: number): Promise\<boolean>
检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。 检查指定工作的最后一次执行是否为超时操作，使用Promise形式返回。
> **说明：** 从API version 9开始废弃，建议使用[workScheduler.isLastWorkTimeOut](../js-apis-resourceschedule-workScheduler.md/#workschedulerisLastworktimeoutpromise9)
>
> 从 API version 9开始支持。
**系统能力**：SystemCapability.ResourceSchedule.WorkScheduler **系统能力**：SystemCapability.ResourceSchedule.WorkScheduler
**参数**： **参数**：
...@@ -300,17 +315,13 @@ isLastWorkTimeOut(workId: number): Promise\<boolean> ...@@ -300,17 +315,13 @@ isLastWorkTimeOut(workId: number): Promise\<boolean>
**示例**： **示例**：
```js ```js
try{
workScheduler.isLastWorkTimeOut(500) workScheduler.isLastWorkTimeOut(500)
.then(res => { .then(res => {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`); console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
}) })
.catch(error => { .catch(err => {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`); console.info(`workschedulerLog isLastWorkTimeOut failed, because: ${err.code}`);
}); });
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
}
``` ```
## WorkInfo ## WorkInfo
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或