diff --git a/zh-cn/application-dev/task-management/background-task-dev-guide.md b/zh-cn/application-dev/task-management/background-task-dev-guide.md index b279133c7705c8940cddf4721847b00b50156daa..139043496961c6311577bcf561ec59a50010c14c 100644 --- a/zh-cn/application-dev/task-management/background-task-dev-guide.md +++ b/zh-cn/application-dev/task-management/background-task-dev-guide.md @@ -12,6 +12,8 @@ **表1** 短时任务主要接口 +> **说明：** 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。 + | 接口名 | 描述 | | ---------------------------------------- | ---------------------------------------- | | requestSuspendDelay(reason: string, callback: Callback<void>): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | 后台应用申请延迟挂起。
延迟挂起时间一般情况下默认值为180000，低电量时默认值为60000。 | @@ -25,46 +27,65 @@ 1. 申请延迟挂起 ```js - import backgroundTaskManager from '@ohos.backgroundTaskManager'; + 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; - console.info("requestId is: " + id); + 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}`); + } ``` 2. 获取进入挂起前的剩余时间 ```js - 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, (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}`); + } ``` 3. 取消延迟挂起 ```js - backgroundTaskManager.cancelSuspendDelay(id); + try { + backgroundTaskManager.cancelSuspendDelay(id); + } catch (error) { + console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`); + } ``` ### 开发实例 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; let myReason = 'test requestSuspendDelay'; - +var delayInfo; // 申请延迟挂起 -let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { - console.info("Request suspension delay will time out."); -}); +try { + delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { + console.info("Request suspension delay will time out."); + }) +} catch (error) { + console.error(`requestSuspendDelay failed. code is ${error.code} message is ${error.message}`); +} // 打印延迟挂起信息 var id = delayInfo.requestId; @@ -73,14 +94,24 @@ console.info("The requestId is: " + id); console.info("The actualDelayTime is: " + time); // 获取应用程序进入挂起状态前的剩余时间 -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, (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.cancelSuspendDelay(id); +try { + backgroundTaskManager.cancelSuspendDelay(id); +} catch (error) { + console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`); +} ``` ## 长时任务 @@ -93,6 +124,8 @@ ohos.permission.KEEP_BACKGROUND_RUNNING **表2** 长时任务主要接口 +> **说明：** 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。 + | 接口名 | 描述 | | ---------------------------------------- | ---------------------------- | | startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> | 服务启动后，向系统申请长时任务，使服务一直保持后台运行。 | @@ -145,7 +178,7 @@ ohos.permission.KEEP_BACKGROUND_RUNNING 2. 申请长时任务。 ```js - import backgroundTaskManager from '@ohos.backgroundTaskManager'; + import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; import wantAgent from '@ohos.wantAgent'; @@ -175,7 +208,7 @@ ohos.permission.KEEP_BACKGROUND_RUNNING 3. 停止长时任务。 ```js - import backgroundTaskManager from '@ohos.backgroundTaskManager'; + import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { @@ -211,7 +244,7 @@ ohos.permission.KEEP_BACKGROUND_RUNNING 2. 申请长时任务。 ```ts - import backgroundTaskManager from '@ohos.backgroundTaskManager'; + import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import wantAgent from '@ohos.wantAgent'; let wantAgentInfo = { @@ -228,25 +261,33 @@ ohos.permission.KEEP_BACKGROUND_RUNNING // 通过wantAgent模块的getWantAgent方法获取WantAgent对象 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(this.context, - 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}`); + } }); ``` 3. 停止长时任务。 ```ts - import backgroundTaskManager from '@ohos.backgroundTaskManager'; + import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; - backgroundTaskManager.stopBackgroundRunning(this.context).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}`); + } ``` @@ -262,7 +303,7 @@ ohos.permission.KEEP_BACKGROUND_RUNNING 当需要与后台执行的长时任务交互时（如播放音乐等）。可以采用connectAbility()方法启动并连接Service Ability。在获取到服务的代理对象后，与服务进行通信，控制长时任务的申请和取消。 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; import wantAgent from '@ohos.wantAgent'; import rpc from "@ohos.rpc"; @@ -371,7 +412,7 @@ Stage模型的相关信息参考[Stage模型综述](../ability/stage-brief.md) ```ts import Ability from '@ohos.application.Ability' -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import wantAgent from '@ohos.wantAgent'; let mContext = null; @@ -395,21 +436,29 @@ function startContinuousTask() { // 通过wantAgent模块的getWantAgent方法获取WantAgent对象 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { - backgroundTaskManager.startBackgroundRunning(mContext, - 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}`); + } }); } function stopContinuousTask() { - backgroundTaskManager.stopBackgroundRunning(mContext).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}`); + } } class MySequenceable { @@ -494,9 +543,11 @@ export default class BgTaskAbility extends Ability { **表1** 能效资源申请主要接口 +> **说明：** 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。 + | 接口名 | 描述 | | ---------------------------------------- | ---------------------------------------- | -| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | 申请能效资源。 | +| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): void | 申请能效资源。 | | resetAllEfficiencyResources():void | 释放申请的能效资源。 | @@ -506,7 +557,7 @@ export default class BgTaskAbility extends Ability { 1. 申请能效资源 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; let request = { resourceTypes: backgroundTaskManager.ResourceType.CPU, @@ -516,14 +567,18 @@ let request = { isPersist: true, isProcess: true, }; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); +try { + backgroundTaskManager.applyEfficiencyResources(request); + console.info("applyEfficiencyResources success. "); +} catch (error) { + console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); +} ``` 2. 释放申请的部分资源 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; let request = { resourceTypes: backgroundTaskManager.ResourceType.CPU, @@ -531,22 +586,30 @@ let request = { timeOut: 0, reason: "reset", }; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); +try { + backgroundTaskManager.applyEfficiencyResources(request); + console.info("applyEfficiencyResources success. "); +} catch (error) { + console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); +} ``` 3. 释放申请的所有资源 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; -backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +try { + backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +} catch (error) { + console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`); +} ``` ### 开发实例 ```js -import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; // 申请能效资源 let request = { @@ -558,8 +621,12 @@ let request = { isPersist: true, isProcess: true, }; -let res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request is: " + res); +try { + backgroundTaskManager.applyEfficiencyResources(request); + console.info("applyEfficiencyResources success. "); +} catch (error) { + console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); +} // 释放部分资源 request = { @@ -568,11 +635,19 @@ request = { timeOut: 0, reason: "reset", }; -res = backgroundTaskManager.applyEfficiencyResources(request); -console.info("the result of request 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.backgroundTaskManager.resetAllEfficiencyResources(); +try { + backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +} catch (error) { + console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`); +} ``` ## 相关实例 diff --git a/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md b/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md index 300086d76e88216b98d0e7f67b0a112ec95b7913..1e7ddc1d47d8e85fd759a358d09bfd45add69e5a 100644 --- a/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md +++ b/zh-cn/application-dev/task-management/work-scheduler-dev-guide.md @@ -4,11 +4,10 @@ 应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时间。延迟任务调度约束见[延迟任务调度概述](./work-scheduler-overview.md)。 - ## 接口说明 注册相关接口包导入： ```js -import workScheduler from '@ohos.workScheduler'; +import workScheduler from '@ohos.resourceschedule.workScheduler'; ``` 回调相关接口包导入： @@ -20,15 +19,17 @@ import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; **表1** workScheduler主要接口 +> **说明：** 延迟任务调度错误码见[workScheduler错误码](../../api/errorcodes/errorcode-workScheduler.md)。 + 接口名 | 接口描述 ---------------------------------------------------------|----------------------------------------- -startWork(work: WorkInfo): boolean; | 延迟调度任务申请 -stopWork(work: WorkInfo, needCancel?: boolean): boolean; | 延迟调度任务取消 +startWork(work: WorkInfo): void; | 延迟调度任务申请 +stopWork(work: WorkInfo, needCancel?: boolean): void; | 延迟调度任务取消 getWorkStatus(workId: number, callback: AsyncCallback\): void;| 获取延迟调度任务状态（Callback形式） getWorkStatus(workId: number): Promise\; | 获取延迟调度任务状态（Promise形式） obtainAllWorks(callback: AsyncCallback\): Array\;| 获取所有延迟调度任务（Callback形式） obtainAllWorks(): Promise>;| 获取所有延迟调度任务（Promise形式） -stopAndClearWorks(): boolean;| 停止并清除任务 +stopAndClearWorks(): void;| 停止并清除任务 isLastWorkTimeOut(workId: number, callback: AsyncCallback\): boolean;| 获取上次任务是否超时（针对RepeatWork，Callback形式） isLastWorkTimeOut(workId: number): Promise\;| 获取上次任务是否超时（针对RepeatWork，Promise形式） @@ -77,7 +78,7 @@ onWorkStop(work: WorkInfo): void | 延迟调度任务结束回调 **注册延迟任务** - import workScheduler from '@ohos.workScheduler'; + import workScheduler from '@ohos.resourceschedule.workScheduler'; let workInfo = { workId: 1, @@ -93,14 +94,18 @@ onWorkStop(work: WorkInfo): void | 延迟调度任务结束回调 mykey3: 1.5 } } - var res = workScheduler.startWork(workInfo); - console.info("workschedulerLog res:" + res); + try{ + workScheduler.startWork(workInfo); + console.info('workschedulerLog startWork success'); + } catch (error) { + console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`); + } **取消延迟任务** - import workScheduler from '@ohos.workScheduler'; + import workScheduler from '@ohos.resourceschedule.workScheduler'; let workInfo = { workId: 1, @@ -116,83 +121,114 @@ onWorkStop(work: WorkInfo): void | 延迟调度任务结束回调 mykey3: 1.5 } } - var res = workScheduler.stopWork(workInfo, false); - console.info("workschedulerLog res:" + res); + 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}`); + } **获取指定延迟任务** 1.Callback写法 - workScheduler.getWorkStatus(50, (err, res) => { - if (err) { - console.info('workschedulerLog getWorkStatus failed, because:' + err.code); - } else { - for (let item in res) { - console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]); + 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}`); + } 2.Promise写法 - workScheduler.getWorkStatus(50).then((res) => { - for (let item in res) { - console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); - } - }).catch((err) => { - console.info('workschedulerLog getWorkStatus failed, because:' + err.code); - }) + 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}`); + } **获取所有延迟任务** 1.Callback写法 - workScheduler.obtainAllWorks((err, res) =>{ - if (err) { - console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); - } else { - console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); - } - }); + 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}`); + } 2.Promise写法 - workScheduler.obtainAllWorks().then((res) => { - console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); - }).catch((err) => { - console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); - }) + 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}`); + } **停止并清除任务** - let res = workScheduler.stopAndClearWorks(); - console.info("workschedulerLog res:" + res); + try{ + workScheduler.stopAndClearWorks(); + console.info(`workschedulerLog stopAndClearWorks success`); + } catch (error) { + console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`); + } **判断上次执行是否超时** 1.Callback写法 - workScheduler.isLastWorkTimeOut(500, (err, res) =>{ - if (err) { - console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code); - } else { - console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); - } - }); + 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}`); + } 2.Promise写法 - workScheduler.isLastWorkTimeOut(500) - .then(res => { - console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); - }) - .catch(err => { - console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code); - }); - }) + 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}`); + } ## 相关实例