From 5f913f20a42fd3c5689ebf6b89b67364cddd51d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=B1=E5=A4=A9=E6=80=A1?= Date: Mon, 17 Oct 2022 07:26:05 +0000 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 朱天怡 --- .../apis/js-apis-backgroundTaskManager.md | 576 +++++++++++++++--- .../reference/apis/js-apis-workScheduler.md | 2 +- 2 files changed, 495 insertions(+), 83 deletions(-) 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 1a2c040d1e..9aaaaf2f13 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -11,24 +11,16 @@ 对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。 > **说明：** -> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。从API version 9开始，导入模块由@ohos.backgroundTaskManager迁移至@ohos.resourceschedule.backgroundTaskManager +> - 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。 ## 导入模块 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; -``` -## backgroundTaskManager.requestSuspendDelay - - -## 导入模块 - -```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; ``` - -## backgroundTaskManager.requestSuspendDelay(deprecated) +## backgroundTaskManager.requestSuspendDelay9+ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo @@ -36,9 +28,7 @@ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspen 延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 -> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.requestSuspendDelay](#reminderagentmanagerpublishreminder9) -> -> 从 API version 7开始支持。 +> 从 API version 9开始支持。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask @@ -56,24 +46,31 @@ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspen **示例**： ```js + import backgroundTaskManager from '@ohos.resourceschedule.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); + 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 +## backgroundTaskManager.getRemainingDelayTime9+ getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 +> 从 API version 9开始支持。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**： @@ -85,23 +82,31 @@ getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): **示例**： ```js + import backgroundTaskManager from '@ohos.resourceschedule.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)); - } - }) + 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 +## backgroundTaskManager.getRemainingDelayTime9+ getRemainingDelayTime(requestId: number): Promise<number> 获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 +> 从 API version 9开始支持。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**： @@ -116,21 +121,29 @@ getRemainingDelayTime(requestId: number): Promise<number> **示例**： ```js + import backgroundTaskManager from '@ohos.resourceschedule.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); - }) + 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 +## backgroundTaskManager.cancelSuspendDelay9+ cancelSuspendDelay(requestId: number): void 取消延迟挂起。 +> 从 API version 9开始支持。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **参数**： @@ -140,17 +153,25 @@ cancelSuspendDelay(requestId: number): void **示例**： ```js + import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; + let id = 1; - backgroundTaskManager.cancelSuspendDelay(id); + try { + backgroundTaskManager.cancelSuspendDelay(id); + } catch (error) { + console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`); + } ``` -## backgroundTaskManager.startBackgroundRunning8+ +## backgroundTaskManager.startBackgroundRunning9+ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 向系统申请长时任务，使用callback形式返回结果。 +> 从 API version 9开始支持。 + **需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask @@ -165,13 +186,13 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want **示例**： ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.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); +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"); } @@ -190,18 +211,24 @@ let wantAgentInfo = { }; wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), - backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback) + 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.startBackgroundRunning8+ +## backgroundTaskManager.startBackgroundRunning9+ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 向系统申请长时任务，使用promise形式返回结果。 +> 从 API version 9开始支持。 + **需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask @@ -221,7 +248,7 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want **示例**： ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; import wantAgent from '@ohos.wantAgent'; @@ -238,22 +265,28 @@ let wantAgentInfo = { }; 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); - }); + 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.stopBackgroundRunning8+ +## backgroundTaskManager.stopBackgroundRunning9+ stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 向系统申请取消长时任务，使用callback形式返回结果。 +> 从 API version 9开始支持。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **参数**： @@ -264,27 +297,33 @@ stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): vo **示例**： ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; -function callback(err, data) { - if (err) { - console.error("Operation stopBackgroundRunning failed Cause: " + err); +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"); } } -backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback); +try { + backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback); +} catch (error) { + console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); +} ``` -## backgroundTaskManager.stopBackgroundRunning8+ +## backgroundTaskManager.stopBackgroundRunning9+ stopBackgroundRunning(context: Context): Promise<void> 向系统申请取消长时任务，使用promise形式返回结果。 +> 从 API version 9开始支持。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **参数**： @@ -299,24 +338,30 @@ stopBackgroundRunning(context: Context): Promise<void> **示例**： ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.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); -}); +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.applyEfficiencyResources9+ -applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): boolean +applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): void 向系统申请能效资源，使用boolean形式返回结果。 进程和它所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。 +> 从 API version 9开始支持。 + **系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统API**: 此接口为系统接口。 @@ -327,15 +372,10 @@ applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresour | ------- | ------- | ---- | ---------------------------------------- | | request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是 | 请求的必要信息。包括资源类型，超时时间等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 | -**返回值**： -| 类型 | 说明 | -| -------------- | ---------------- | -| boolean | true代表申请成功，false代表申请失败。 | - **示例**： ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; let request = { resourceTypes: backgroundTaskManager.ResourceType.CPU, @@ -345,8 +385,12 @@ let request = { isPersist: true, isProcess: false, }; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("result of applyEfficiencyResources is: " + res) +try { + backgroundTaskManager.applyEfficiencyResources(request); + console.info("applyEfficiencyResources success. "); +} catch (error) { + console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); +} ``` ## backgroundTaskManager.resetAllEfficiencyResources9+ @@ -355,6 +399,8 @@ resetAllEfficiencyResources(): void 释放所有已经申请的资源。 +> 从 API version 9开始支持。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply **系统API**: 此接口为系统接口。 @@ -362,13 +408,16 @@ resetAllEfficiencyResources(): void **示例**： ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; - -backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +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 +## DelaySuspendInfo9+ 延迟挂起信息。 @@ -380,7 +429,7 @@ backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); | actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。
一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | -## BackgroundMode8+ +## BackgroundMode9+ **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask @@ -429,4 +478,367 @@ backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); | WORK_SCHEDULER | 8 | 延迟任务，申请后有更长的执行时间。 | | BLUETOOTH | 16 | 蓝牙相关，申请后挂起状态下不被代理掉。 | | GPS | 32 | GPS相关，申请后挂起状态下不被代理掉。 | -| AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉。 | \ No newline at end of file +| AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉。 | + + + +## 导入模块 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +``` + + +## backgroundTaskManager.requestSuspendDelay(deprecated) + +requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo + +后台应用申请延迟挂起。 + +延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay9) +> +> 从 API version 7开始支持。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------------------ | +| reason | string | 是 | 延迟挂起申请的原因。 | +| callback | Callback<void> | 是 | 延迟即将超时的回调函数，一般在超时前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.getRemainingDelayTime7+(deprecated) + +getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void + +获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.getRemainingDelayTime](#backgroundtaskmanagergetremainingdelaytime9) +> +> 从 API version 7开始支持。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| --------- | --------------------------- | ---- | ---------------------------------------- | +| requestId | number | 是 | 延迟挂起的请求ID。 | +| callback | AsyncCallback<number> | 是 | 指定的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.getRemainingDelayTime7+(deprecated) + +getRemainingDelayTime(requestId: number): Promise<number> + +获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.getRemainingDelayTime](#backgroundtaskmanagergetremainingdelaytime9) +> +> 从 API version 7开始支持。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | ---------- | +| requestId | number | 是 | 延迟挂起的请求ID。 | + +**返回值**： +| 类型 | 说明 | +| --------------------- | ---------------------------------------- | +| Promise<number> | 指定的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.cancelSuspendDelay7+(deprecated) + +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.startBackgroundRunning8+(deprecated) + +startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void + +向系统申请长时任务，使用callback形式返回结果。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.startBackgroundRunning](#backgroundtaskmanagerstartbackgroundrunning9) +> +> 从 API version 7开始支持。 + +**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------- | ---- | ---------------------------------------- | +| context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | +| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | +| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击后跳转的界面。 | +| callback | AsyncCallback<void> | 是 | 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.startBackgroundRunning8+(deprecated) + +startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> + +向系统申请长时任务，使用promise形式返回结果。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.startBackgroundRunning](#backgroundtaskmanagerstartbackgroundrunning9) +> +> 从 API version 7开始支持。 + +**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ---------------------------------- | ---- | ---------------------------------------- | +| context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | +| bgMode | [BackgroundMode](#backgroundmode8) | 是 | 向系统申请的后台模式。 | +| wantAgent | [WantAgent](js-apis-wantAgent.md) | 是 | 通知参数，用于指定长时任务通知点击跳转的界面。 | + +**返回值**： +| 类型 | 说明 | +| -------------- | ---------------- | +| Promise\ | 使用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.stopBackgroundRunning8+(deprecated) + +stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void + +向系统申请取消长时任务，使用callback形式返回结果。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.stopBackgroundRunning](#backgroundtaskmanagerstopbackgroundrunning9) +> +> 从 API version 7开始支持。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------------------------------------- | +| context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | +| callback | AsyncCallback<void> | 是 | 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.stopBackgroundRunning8+(deprecated) + +stopBackgroundRunning(context: Context): Promise<void> + +向系统申请取消长时任务，使用promise形式返回结果。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.stopBackgroundRunning](#backgroundtaskmanagerstopbackgroundrunning9) +> +> 从 API version 7开始支持。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------- | ---- | ---------------------------------------- | +| context | Context | 是 | 应用运行的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | + +**返回值**： +| 类型 | 说明 | +| -------------- | ---------------- | +| Promise\ | 使用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); +}); + +``` + +## DelaySuspendInfo7+(deprecated) + +延迟挂起信息。 + +> **说明：** 从API version 9开始废弃，建议使用[backgroundTaskManager.DelaySuspendInfo](#backgroundtaskmanagerdelaysuspendinfo9) +> +> 从 API version 7开始支持。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask + +| 参数名 | 类型 | 必填 | 说明 | +| --------------- | ------ | ---- | ---------------------------------------- | +| requestId | number | 是 | 延迟挂起的请求ID。 | +| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。
一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | + + +## BackgroundMode8+(deprecated) + +> **说明：** 从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相关
此接口为系统接口。 | +| VOIP | 8 | 音视频通话
此接口为系统接口。 | +| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效）。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md b/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md index 186fd9383e..bb99c9e51f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md +++ b/zh-cn/application-dev/reference/apis/js-apis-workScheduler.md @@ -9,7 +9,7 @@ > - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > - 本模块接口仅可在Stage模型下使用。 > - 延迟任务调度约束见[延迟任务调度概述](../../task-management/work-scheduler-overview.md)。 -> - 延迟任务调度错误码见[延迟任务错误码](../errorcodes/errorcode-workScheduler.md)。 +> - 延迟任务调度错误码见[workScheduler错误码](../errorcodes/errorcode-workScheduler.md)。 ## 导入模块 -- GitLab