From fb306202c5879d36aeeef656dec45bfb7ed32d9c Mon Sep 17 00:00:00 2001 From: zhangxin_T Date: Tue, 15 Mar 2022 17:27:40 +0800 Subject: [PATCH] modify doc Signed-off-by: zhangxin_T --- .../background-task-overview.md | 6 +- .../apis/js-apis-backgroundTaskManager.md | 117 +++++++++--------- 2 files changed, 63 insertions(+), 60 deletions(-) diff --git a/zh-cn/application-dev/background-task-management/background-task-overview.md b/zh-cn/application-dev/background-task-management/background-task-overview.md index 403126992a..7ade1cd904 100644 --- a/zh-cn/application-dev/background-task-management/background-task-overview.md +++ b/zh-cn/application-dev/background-task-management/background-task-overview.md @@ -1,6 +1,6 @@ # 后台任务概述 -对于有用户交互的OS来说，资源优先分配给与用户交互的业务进程，换句话说，在支撑OS运行的进程以外，用户能感知到的业务进程优先级最高，所以后台任务管理的范围是用户感知不到的业务进程。 +后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。 ## 后台任务类型 @@ -11,7 +11,7 @@ 2. 短时任务：退后台后，如果有紧急不可推迟且短时间能完成的任务，如应用退后台要进行数据压缩，不可中断，则使用短时任务申请延迟进入挂起（Suspend）状态。 -3. 长时任务：如果是用户发起的可感知业务需要长时间后台运行的，如后台播放音乐、导航、上传下载、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 +3. 长时任务：如果是用户发起的可感知业务需要长时间后台运行的，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 ## 短时任务 @@ -55,7 +55,7 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业 | taskKeeping | 计算任务 | 正在运行计算任务 | PC特有，仅在PC申请生效 | ### 长时任务使用约束 -- 如果用户选择可感知业务（如播音、导航、上传下载等），触发对应后台模式，在任务启动时，系统会强制弹出通知提醒用户。 +- 如果用户选择可感知业务（如播音、导航等），触发对应后台模式，在任务启动时，系统会强制弹出通知提醒用户。 - 如果任务结束，应用应主动退出后台模式。若在后台运行期间，系统检测到应用并未使用对应后台模式的资源，则会被挂起（Suspend）。 - 避免不合理地申请后台长时任务，长时任务类型要与应用的业务类型匹配。如果执行的任务和申请的类型不匹配，也会被系统检测到并被挂起（Suspend）。 - 长时任务是为了真正在后台长时间执行某个任务，如果一个应用申请了长时任务，但在实际运行过程中，并未真正运行或执行此类任务时，也会被系统检测到并被挂起（Suspend）。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md index a624b6ca6e..0191b28353 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -10,12 +10,6 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; ``` -## 权限列表 - -长时任务需要申请如下权限： - -ohos.permission.KEEP_BACKGROUND_RUNNING - ## backgroundTaskManager.requestSuspendDelay @@ -27,19 +21,19 @@ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspen **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | reason | string | 是 | 延迟挂起申请的原因。 | | callback | Callback<void> | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 | -- **返回值**： +**返回值**： | 类型 | 说明 | | -------- | -------- | | [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | -- **示例**： - ``` +**示例**： + ```js let myReason = 'test requestSuspendDelay'; let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { console.info("Request suspension delay will time out."); @@ -55,14 +49,14 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | requestId | number | 是 | 延迟挂起的请求ID。 | | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | -- **示例**： - ``` +**示例**： + ```js let id = 1; backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { if(err.data === 0) { @@ -82,18 +76,18 @@ getRemainingDelayTime(requestId: number): Promise<number> **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | requestId | number | 是 | 延迟挂起的请求ID。 | -- **返回值**： +**返回值**： | 类型 | 说明 | | -------- | -------- | | Promise<number> | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | -- **示例**： - ``` +**示例**： + ```js let id = 1; backgroundTaskManager.getRemainingDelayTime(id).then( res => { console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); @@ -111,45 +105,36 @@ cancelSuspendDelay(requestId: number): void **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | requestId | number | 是 | 延迟挂起的请求ID。 | -- **示例**： - ``` +**示例**： + ```js backgroundTaskManager.cancelSuspendDelay(id); ``` -#### DelaySuspendInfo - -延迟挂起信息。 - -**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| requestId | number | 是 | 延迟挂起的请求ID。 | -| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。
一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | +## backgroundTaskManager.startBackgroundRunning 8+ -## backgroundTaskManager.startBackgroundRunning - -startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void; 8+ +startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 向系统申请长时任务，使用callback形式返回结果。 +**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | - | bgMode | BackgroundMode | 是 | 向系统申请的后台模式 | + | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 | + | bgMode | [BackgroundMode](#BackgroundMode8+) | 是 | 向系统申请的后台模式 | | wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数，用于指定长时任务通知点击后跳转的界面。 | | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | -- **示例**： +**示例**： ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -182,28 +167,30 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { ``` -## backgroundTaskManager.startBackgroundRunning +## backgroundTaskManager.startBackgroundRunning 8+ -startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void>; 8+ +startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 向系统申请长时任务，使用promise形式返回结果。 +**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | - | bgMode | BackgroundMode | 是 | 向系统申请的后台模式 | -| wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面 | + | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 | + | bgMode | [BackgroundMode](#BackgroundMode8+) | 是 | 向系统申请的后台模式 | + | wantAgent | [WantAgent](js-apis-notification.md#WantAgent接口) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面 | -- **返回值** +**返回值** | 类型 | 说明 | | -------------- | ------------------------- | | Promise\ | 使用Promise形式返回结果。 | -- **示例**： +**示例**： ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -232,21 +219,23 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { ``` -## backgroundTaskManager.stopBackgroundRunning +## backgroundTaskManager.stopBackgroundRunning 8+ -stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void; 8+ +stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 向系统申请取消长时任务，使用callback形式返回结果。 +**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | + | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 | | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | -- **示例**： +**示例**： ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -263,25 +252,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac ``` -## backgroundTaskManager.stopBackgroundRunning +## backgroundTaskManager.stopBackgroundRunning 8+ -stopBackgroundRunning(context: Context): Promise<void>; 8+ +stopBackgroundRunning(context: Context): Promise<void> 向系统申请取消长时任务，使用promise形式返回结果。 +**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask -- **参数**： +**参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | context | Context | 是 | 应用运行的上下文 | + | context | [Context](js-apis-Context.md) | 是 | 应用运行的上下文 | -- **返回值** +**返回值** | 类型 | 说明 | | -------------- | ------------------------- | | Promise\ | 使用Promise形式返回结果。 | -- **示例**： +**示例**： ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; @@ -294,7 +285,19 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() ``` -## BackgroundMode 8+ +## DelaySuspendInfo + +延迟挂起信息。 + +**系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| requestId | number | 是 | 延迟挂起的请求ID。 | +| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。
一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | + + +## BackgroundMode8+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask -- GitLab