Skip to content

D
Docs

OpenHarmony / Docs
接近 2 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 03c7e63c 编写于 作者: W wusongqing
浏览文件
操作

updated docs 

Signed-off-by: Nwusongqing <wusongqing@huawei.com>
上级 ac7e0ecf
隐藏空白更改
内联 并排
Showing with 58 addition and 70 deletion
en/application-dev/background-task-management/background-task-dev-guide.md
浏览文件 @ 03c7e63c
...@@ -2,34 +2,22 @@ ...@@ -2,34 +2,22 @@
## When to Use ## When to Use
If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task or continuous task for delayed suspension based on the service type. If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task or continuous task for delayed suspension based on the service type.
## Available APIs
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
```
## Transient Tasks ## Transient Tasks
### Available APIs
**Table 1** Main APIs for transient tasks **Table 1** Main APIs for transient tasks
| API| Description| | API| Description|
| -------- | -------- | | -------- | -------- |
| function&nbsp;requestSuspendDelay(reason:&nbsp;string,&nbsp;callback:&nbsp;Callback&lt;void&gt;):&nbsp;**DelaySuspendInfo**; | Requests delayed suspension after the application switches to the background.<br>The default duration of delayed suspension is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level.| | requestSuspendDelay(reason:&nbsp;string,&nbsp;callback:&nbsp;Callback&lt;void&gt;):&nbsp;[DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | Requests delayed suspension after the application switches to the background.<br>The default duration value of delayed suspension is 180000 when the battery level is normal and 60000 when the battery level is low.|
| function&nbsp;getRemainingDelayTime(requestId:&nbsp;number,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):&nbsp;void;<br>function&nbsp;getRemainingDelayTime(requestId:&nbsp;number):&nbsp;Promise&lt;number&gt;; | Obtains the remaining duration before the application is suspended. (The value of **requestId** is obtained from the return value of **requestSuspendDelay**.)<br>Two asynchronous methods are provided: callback and promise.| | getRemainingDelayTime(requestId:&nbsp;number):&nbsp;Promise&lt;number&gt; | Obtains the remaining duration before the application is suspended.<br>This API uses a promise to return the task execution result.|
| function&nbsp;cancelSuspendDelay(requestId:&nbsp;number):&nbsp;void; | Cancels the suspension delay. (The value of **requestId** is obtained from the return value of **requestSuspendDelay**.)| | cancelSuspendDelay(requestId:&nbsp;number):&nbsp;void | Cancels the suspension delay.|
**Table 2** Parameters in DelaySuspendInfo
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| requestId | number | Yes| ID of the suspension delay request.|
| actualDelayTime | number | Yes| Actual suspension delay duration of the application, in milliseconds.|
## How to Develop ### How to Develop
1. Request a suspension delay. 1. Request a suspension delay.
...@@ -42,7 +30,8 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; ...@@ -42,7 +30,8 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager';
console.info("Request suspension delay will time out."); console.info("Request suspension delay will time out.");
}); });
var id = delayInfo.requestId;console.info("requestId is: " + id); var id = delayInfo.requestId;
console.info("requestId is: " + id);
``` ```
...@@ -50,9 +39,9 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; ...@@ -50,9 +39,9 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager';
```js ```js
backgroundTaskManager.getRemainingDelayTime(id).then( res => { backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => { }).catch( err => {
console.log('promise => Operation failed. Cause: ' + err.data); console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data);
}); });
``` ```
...@@ -64,7 +53,7 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; ...@@ -64,7 +53,7 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager';
``` ```
## Development Examples ### Development Examples
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
...@@ -83,9 +72,9 @@ console.info("The actualDelayTime is: " + time); ...@@ -83,9 +72,9 @@ console.info("The actualDelayTime is: " + time);
// Obtain the remaining duration before the application is suspended. // Obtain the remaining duration before the application is suspended.
backgroundTaskManager.getRemainingDelayTime(id).then( res => { backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => { }).catch( err => {
console.log('promise => Operation failed. Cause: ' + err.data); console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data);
}); });
// Cancel the suspension delay. // Cancel the suspension delay.
...@@ -98,17 +87,19 @@ backgroundTaskManager.cancelSuspendDelay(id); ...@@ -98,17 +87,19 @@ backgroundTaskManager.cancelSuspendDelay(id);
ohos.permission.KEEP_BACKGROUND_RUNNING ohos.permission.KEEP_BACKGROUND_RUNNING
**Table 3** Main APIs for continuous tasks ### Available APIs
**Table 2** Main APIs for continuous tasks
| API| Description| | API| Description|
| -------- | -------- | | -------- | -------- |
| function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void;<br>function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;; | Requests a continuous task from the system so that the application keeps running in the background.| | startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt; | Requests a continuous task from the system so that the application keeps running in the background.|
| function stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void;<br>function stopBackgroundRunning(context: Context): Promise&lt;void&gt;; | Cancels the continuous task.| | stopBackgroundRunning(context: Context): Promise&lt;void&gt; | Cancels the continuous task.|
For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantAgent.md). For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantAgent.md).
**Table 4** Background modes **Table 3** Background modes
| Name| ID Value| Description| Item| | Name| ID Value| Description| Item|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
...@@ -123,39 +114,30 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ...@@ -123,39 +114,30 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA
| TASK_KEEPING | 9 | Computing task (for specific devices only).| taskKeeping | | TASK_KEEPING | 9 | Computing task (for specific devices only).| taskKeeping |
## How to Develop ### How to Develop
1. Configure the continuous task permission and background mode type in the **config.json** file, with the ability type set to **service**. 1. Configure the continuous task permission and background mode type in the **config.json** file, with the ability type set to **service**.
```json ```json
"module": { "module": {
"package": "com.example.myapplication", "package": "com.example.myapplication",
"abilities": [ "abilities": [
{ {
"backgroundModes": [ "backgroundModes": [
"dataTransfer", "dataTransfer",
"location", "location"
], // Background mode
], "type": "service" // The ability type is service.
"type": "service"
}
],
"defPermissions": [
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
} }
], ],
"reqPermissions": [ "reqPermissions": [
{ {
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // Continuous task permission
} }
] ]
} }
``` ```
2. Request a continuous task. 2. Request a continuous task.
```js ```js
...@@ -172,16 +154,16 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ...@@ -172,16 +154,16 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA
], ],
operationType: wantAgent.OperationType.START_ABILITY, operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0, requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
}; };
// Obtain the WantAgent object by using the getWantAgent method of the wantAgent module. // Obtain the WantAgent object by using the getWantAgent method of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation succeeded"); console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation startBackgroundRunning failed Cause: " + err);
}); });
}); });
``` ```
...@@ -193,14 +175,14 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ...@@ -193,14 +175,14 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation succeeded"); console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation stopBackgroundRunning failed Cause: " + err);
}); });
``` ```
## Development Examples ### Development Examples
After a service is started, call the API for requesting a continuous task in the **onStart** callback of the Service ability to declare that the service needs to run in the background for a long time. In the **onStop** callback, call the API for canceling the continuous task. After a service is started, call the API for requesting a continuous task in the **onStart** callback of the Service ability to declare that the service needs to run in the background for a long time. In the **onStop** callback, call the API for canceling the continuous task.
In the **service.js** file: In the **service.js** file:
...@@ -220,25 +202,25 @@ function startBackgroundRunning() { ...@@ -220,25 +202,25 @@ function startBackgroundRunning() {
], ],
operationType: wantAgent.OperationType.START_ABILITY, operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0, requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
}; };
// Obtain the WantAgent object by using the getWantAgent method of the wantAgent module. // Obtain the WantAgent object by using the getWantAgent method of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation succeeded"); console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation startBackgroundRunning failed Cause: " + err);
}); });
}); });
} }
function stopBackgroundRunning() { function stopBackgroundRunning() {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation succeeded"); console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation stopBackgroundRunning failed Cause: " + err);
}); });
} }
......
en/application-dev/reference/apis/js-apis-backgroundTaskManager.md
浏览文件 @ 03c7e63c
...@@ -25,7 +25,7 @@ The default duration of delayed suspension is 180000 when the battery level is h ...@@ -25,7 +25,7 @@ The default duration of delayed suspension is 180000 when the battery level is h
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------------------- | ---- | ------------------------------ | | -------- | -------------------- | ---- | ------------------------------ |
| reason | string | Yes | Reason for delayed transition to the suspended state. | | reason | string | Yes | Reason for delayed transition to the suspended state. |
| callback | Callback&lt;void&gt; | Yes | Invoked when a delay is about to time out. Generally, this callback is used to notify the application 6 seconds before the delay times out.| | callback | Callback&lt;void&gt; | Yes | Invoked when a delay is about to time out. Generally, this callback is used to notify the application 6 seconds before the delay times out. |
**Return value** **Return value**
| Type | Description | | Type | Description |
...@@ -33,11 +33,17 @@ The default duration of delayed suspension is 180000 when the battery level is h ...@@ -33,11 +33,17 @@ The default duration of delayed suspension is 180000 when the battery level is h
| [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.| | [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.|
**Example** **Example**
```js ```js
let myReason = 'test requestSuspendDelay'; let myReason = 'test requestSuspendDelay';
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 time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
``` ```
...@@ -61,9 +67,9 @@ Obtains the remaining duration before the application is suspended. This API use ...@@ -61,9 +67,9 @@ Obtains the remaining duration before the application is suspended. This API use
let id = 1; let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
if(err.data === 0) { if(err.data === 0) {
console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
} else { } else {
console.log('promise => Operation failed. Cause: ' + err.data); console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.data);
} }
}) })
``` ```
...@@ -91,9 +97,9 @@ Obtains the remaining duration before the application is suspended. This API use ...@@ -91,9 +97,9 @@ Obtains the remaining duration before the application is suspended. This API use
```js ```js
let id = 1; let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then( res => { backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => { }).catch( err => {
console.log('promise => Operation failed. Cause: ' + err.data); console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data);
}) })
``` ```
...@@ -143,9 +149,9 @@ import wantAgent from '@ohos.wantAgent'; ...@@ -143,9 +149,9 @@ import wantAgent from '@ohos.wantAgent';
function callback(err, data) { function callback(err, data) {
if (err) { if (err) {
console.error("Operation failed Cause: " + err); console.error("Operation startBackgroundRunning failed Cause: " + err);
} else { } else {
console.info("Operation succeeded"); console.info("Operation startBackgroundRunning succeeded");
} }
} }
...@@ -158,7 +164,7 @@ let wantAgentInfo = { ...@@ -158,7 +164,7 @@ let wantAgentInfo = {
], ],
operationType: wantAgent.OperationType.START_ABILITY, operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0, requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
}; };
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
...@@ -206,15 +212,15 @@ let wantAgentInfo = { ...@@ -206,15 +212,15 @@ let wantAgentInfo = {
], ],
operationType: wantAgent.OperationType.START_ABILITY, operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0, requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
}; };
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation succeeded"); console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation startBackgroundRunning failed Cause: " + err);
}); });
}); });
...@@ -241,9 +247,9 @@ import featureAbility from '@ohos.ability.featureAbility'; ...@@ -241,9 +247,9 @@ import featureAbility from '@ohos.ability.featureAbility';
function callback(err, data) { function callback(err, data) {
if (err) { if (err) {
console.error("Operation failed Cause: " + err); console.error("Operation stopBackgroundRunning failed Cause: " + err);
} else { } else {
console.info("Operation succeeded"); console.info("Operation stopBackgroundRunning succeeded");
} }
} }
...@@ -275,9 +281,9 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; ...@@ -275,9 +281,9 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation succeeded"); console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation stopBackgroundRunning failed Cause: " + err);
}); });
``` ```
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或