From 8634359d4f72f5f553276989bc6334b352aba3bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BB=96=E5=BA=B7=E5=BA=B7?= Date: Fri, 7 Jan 2022 17:22:01 +0800 Subject: [PATCH] add Background task management MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 廖康康 --- .../background-task-dev-guide.md | 87 ++++++++++++ .../background-task-overview.md | 35 +++++ .../public_sys-resources/icon-caution.gif | Bin 0 -> 580 bytes .../public_sys-resources/icon-danger.gif | Bin 0 -> 580 bytes .../public_sys-resources/icon-note.gif | Bin 0 -> 394 bytes .../public_sys-resources/icon-notice.gif | Bin 0 -> 406 bytes .../public_sys-resources/icon-tip.gif | Bin 0 -> 253 bytes .../public_sys-resources/icon-warning.gif | Bin 0 -> 580 bytes .../apis/js-apis-background-task-mgmt.md | 128 ++++++++++++++++++ 9 files changed, 250 insertions(+) create mode 100644 zh-cn/application-dev/background-task-management/background-task-dev-guide.md create mode 100644 zh-cn/application-dev/background-task-management/background-task-overview.md create mode 100644 zh-cn/application-dev/background-task-management/public_sys-resources/icon-caution.gif create mode 100644 zh-cn/application-dev/background-task-management/public_sys-resources/icon-danger.gif create mode 100644 zh-cn/application-dev/background-task-management/public_sys-resources/icon-note.gif create mode 100644 zh-cn/application-dev/background-task-management/public_sys-resources/icon-notice.gif create mode 100644 zh-cn/application-dev/background-task-management/public_sys-resources/icon-tip.gif create mode 100644 zh-cn/application-dev/background-task-management/public_sys-resources/icon-warning.gif create mode 100644 zh-cn/application-dev/reference/apis/js-apis-background-task-mgmt.md diff --git a/zh-cn/application-dev/background-task-management/background-task-dev-guide.md b/zh-cn/application-dev/background-task-management/background-task-dev-guide.md new file mode 100644 index 0000000000..0c776e6816 --- /dev/null +++ b/zh-cn/application-dev/background-task-management/background-task-dev-guide.md @@ -0,0 +1,87 @@ +# 后台任务开发指导 + +## 场景介绍 + +应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。 + + +## 接口说明 + +``` +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +``` + +**表1** backgroundTaskManager主要接口 + +| 接口名 | 描述 | +| -------- | -------- | +| function requestSuspendDelay(reason: string, callback: Callback<void>): **DelaySuspendInfo**; | 后台应用申请延迟挂起。
延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | +| function getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void;
function getRemainingDelayTime(requestId: number): Promise<number>; | 获取应用程序进入挂起状态前的剩余时间。(requestId从requestSuspendDelay的返回值获取)
提供两种异步方法，使用Callback形式其任务执行结果以参数形式提供给回调函数，Promise形式则返回一个Promise对象。 | +| function cancelSuspendDelay(requestId: number): void; | 取消延迟挂起。(requestId从requestSuspendDelay的返回值获取) | + +**表2** DelaySuspendInfo包含参数 + +| 参数名 | 类型 | 是否必选 | 描述 | +| -------- | -------- | -------- | -------- | +| requestId | number | 是 | 延迟挂起的请求ID。 | +| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。 | + + +## 开发步骤 + +1. 申请延迟挂起 + ``` + import backgroundTaskManager from '@ohos.backgroundTaskManager'; + let myReason = 'test requestSuspendDelay'; + let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, (val) => { + if(val.code === 0) { + console.info("Operation time out: " + val.data); + } else { + console.info("Operation failed: " + val.data); + } + }); + var id = delayInfo.requestId;console.info("requestId is: " + id); + ``` + +2. 获取进入挂起前的剩余时间 + ``` + backgroundTaskManager.getRemainingDelayTime(id).then( res => { + console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + }).catch( err => { + console.log('promise => Operation failed. Cause: ' + err.data); + }); + ``` + +3. 取消延迟挂起 + ``` + backgroundTaskManager.cancelSuspendDelay(id); + ``` + + +## 开发实例 + +``` +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +let myReason = 'test requestSuspendDelay'; +// 申请延迟挂起 +let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, (val) => { + if(val.code === 0) { + console.info("Operation time out: " + val.data); + } else { + console.info("Operation failed: " + val.data); + } +}); +// 打印延迟挂起信息 +var id = delayInfo.requestId; +var time = delayInfo.actualDelayTime; +console.info("The requestId is: " + id); +console.info("The actualDelayTime is: " + time); +// 获取应用程序进入挂起状态前的剩余时间 +backgroundTaskManager.getRemainingDelayTime(id).then( res => { + console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); +}).catch( err => { + console.log('promise => Operation failed. Cause: ' + err.data); +}); +// 取消延迟挂起 +backgroundTaskManager.cancelSuspendDelay(id); +``` 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 new file mode 100644 index 0000000000..f3cec92c41 --- /dev/null +++ b/zh-cn/application-dev/background-task-management/background-task-overview.md @@ -0,0 +1,35 @@ +# 概述 + +对于有用户交互的OS来说，资源优先分配给与用户交互的业务进程，换句话说，在支撑OS运行的进程以外，用户能感知到的业务进程优先级最高，所以后台任务管理的范围是用户感知不到的业务进程。 + + +## 后台任务类型 + +本文描述的后台任务特指应用或业务模块处于后台（无可见界面）时，有需要继续执行或者后续执行的业务。对这些应用不可见但要继续或者将要执行的业务动作，为避免后台任务管理对业务执行的影响，OpenHarmony将后台任务分为三种类型： + +1. 无后台业务：退后台后，无任务需要处理。 + +2. 短时任务：退后台后，如果有紧急不可推迟且短时间能完成的任务，如应用退后台要进行数据压缩，不可中断，则使用短时任务申请延迟进入挂起（Suspend）状态。 + +3. 长时任务：如果是用户发起的可感知业务需要长时间后台运行的，如后台播放音乐、导航、上传下载、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 + + +## 短时任务 + +退到后台的应用有不可中断且短时间能完成的任务时，可以使用短时任务机制，该机制允许应用在后台短时间内完成任务，保障应用业务运行不受后台生命周期管理的影响。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 短时任务仅针对应用的临时任务提供资源使用生命周期保障，限制单次最大使用时长为3分钟，全天使用配额默认为10分钟（具体时长系统根据应用场景和系统状态智能调整）。 + + +### 短时任务使用约束 + +短时任务的使用需要遵从如下约束和规则： + +- **申请时机**：允许应用在前台时，或退后台在被挂起之前（应用退到后台默认有6~12秒的运行时长，具体时长由系统根据具体场景决定）申请延迟挂起，否则可能被挂起（Suspend），导致申请失败。 + +- **超时**：延迟挂起超时（Timeout），系统通过回调知会应用，应用需要取消对应的延迟挂起，或再次申请延迟挂起。超期不取消或不处理，该应用会被强制取消延迟挂起。 + +- **取消时机**：任务完成后申请方应用主动取消延时申请，不要等到超时后被系统取消，否则会影响该应用的后台允许运行时长配额。 + +- **配额机制**：为了防止应用滥用保活，或者申请后不取消，每个应用每天都会有一定配额（会根据用户的使用习惯动态调整），配额消耗完就不再允许申请短时任务，所以应用完成短时任务后立刻取消延时申请，避免消耗配额。（注，这个配额指的是申请的时长，系统默认应用在后台运行的时间不计算在内）。 diff --git a/zh-cn/application-dev/background-task-management/public_sys-resources/icon-caution.gif b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-caution.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 GIT binary patch literal 580 zcmV-K0=xZ3Nk%w1VIu$?0Hp~4{QBgqmQ+MG9K51r{QB&)np^||1PlfQ%(86!{`~yv zv{XhUWKt}AZaiE{EOcHp{O-j3`t;<+eEiycJT4p@77X;(jQsMfB$R?oG%6hQ z+MMLZbQBH@)Vg&1^3?qHb(5!%>3r0+`eq=&V&E}0Dypi0000000000 z00000A^8LW000R9EC2ui03!e$000L5z=Uu}ED8YtqjJd<+B}(9bIOb$3-31_h|V>=0A{ z1Hh0#H30>fNT})^fRU_83uewx9oRr{f{Sx1Ml`t)EQ zGkHZ67&~y{W5Jpq4H_WfuLxp*3<7O}GEl;1ESe36fLNs=B0&LQM1Buf(R)qg(BRd`t1OPjI1m_q4 literal 0 HcmV?d00001 diff --git a/zh-cn/application-dev/background-task-management/public_sys-resources/icon-danger.gif b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-danger.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 GIT binary patch literal 580 zcmV-K0=xZ3Nk%w1VIu$?0Hp~4{QBgqmQ+MG9K51r{QB&)np^||1PlfQ%(86!{`~yv zv{XhUWKt}AZaiE{EOcHp{O-j3`t;<+eEiycJT4p@77X;(jQsMfB$R?oG%6hQ z+MMLZbQBH@)Vg&1^3?qHb(5!%>3r0+`eq=&V&E}0Dypi0000000000 z00000A^8LW000R9EC2ui03!e$000L5z=Uu}ED8YtqjJd<+B}(9bIOb$3-31_h|V>=0A{ z1Hh0#H30>fNT})^fRU_83uewx9oRr{f{Sx1Ml`t)EQ zGkHZ67&~y{W5Jpq4H_WfuLxp*3<7O}GEl;1ESe36fLNs=B0&LQM1Buf(R)qg(BRd`t1OPjI1m_q4 literal 0 HcmV?d00001 diff --git a/zh-cn/application-dev/background-task-management/public_sys-resources/icon-note.gif b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda GIT binary patch literal 394 zcmZ?wbhEHblx7fPSjxcg=ii?@_wH=jwxy=7CMGH-B`L+l$wfv=#>UF#$gv|VY%C^b zCQFtrnKN(Bo_%|sJbO}7RAORe!otL&qo<>yq_Sq+8Xqqo5h0P3w3Lvb5E(g{p01vl zxR@)KuDH0l^z`+-dH3eaw=XqSH7aTIx{kzVBN;X&hha0dQSgWuiw0NWUvMRmkD|> literal 0 HcmV?d00001 diff --git a/zh-cn/application-dev/background-task-management/public_sys-resources/icon-notice.gif b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-notice.gif new file mode 100644 index 0000000000000000000000000000000000000000..86024f61b691400bea99e5b1f506d9d9aef36e27 GIT binary patch literal 406 zcmV;H0crk6Nk%w1VIu$@0J8u9|NsB@_xJDb@8;&_*4Ea}&d#;9wWXz{jEszHYim+c zQaU<1At50E0000000000A^8Le000gEEC2ui03!e%000R7038S%NU)&51O^i-Tu6`s z0)`MFE@;3YqD6xSC^kTNu_J>91{PH8XfZ(p1pp2-SU@u3#{mEUC}_}tg3+I#{z}{Ok@D_ZUDg- zt0stin4;pC8M{WLSlRH*1pzqEw1}3oOskyNN?j;7HD{BBZ*OEcv4HK!6Bk6beR+04 z&8}k>SkTusVTDmkyOz#5fCA$JTPGJVQvr3uZ?QzzPQFvD0rGf_PdrcF`pMs}p^BcF zKtKTd`0wipR%nKN&Wj+V}pX;WC3SdJV!a_8Qi zE7z`U*|Y^H0^}fB$R?oG%6hQ z+MMLZbQBH@)Vg&1^3?qHb(5!%>3r0+`eq=&V&E}0Dypi0000000000 z00000A^8LW000R9EC2ui03!e$000L5z=Uu}ED8YtqjJd<+B}(9bIOb$3-31_h|V>=0A{ z1Hh0#H30>fNT})^fRU_83uewx9oRr{f{Sx1Ml`t)EQ zGkHZ67&~y{W5Jpq4H_WfuLxp*3<7O}GEl;1ESe36fLNs=B0&LQM1Buf(R)qg(BRd`t1OPjI1m_q4 literal 0 HcmV?d00001 diff --git a/zh-cn/application-dev/reference/apis/js-apis-background-task-mgmt.md b/zh-cn/application-dev/reference/apis/js-apis-background-task-mgmt.md new file mode 100644 index 0000000000..bdab942d85 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-background-task-mgmt.md @@ -0,0 +1,128 @@ +# 后台任务管理 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +``` +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +``` + + +## 权限 + +无 + + +## backgroundTaskManager.requestSuspendDelay + +requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo + +后台应用申请延迟挂起。 + +延迟挂起时间一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 + +- **参数**： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | reason | string | 是 | 延迟挂起申请的原因。 | + | callback | Callback<void> | 是 | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 | + +- **返回值**： + | 类型 | 说明 | + | -------- | -------- | + | [DelaySuspendInfo](#delaysuspendinfo) | 返回延迟挂起信息。 | + +- **示例**： + ``` + let myReason = 'test requestSuspendDelay'; + let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, (val) => { + if(val.code === 0) { + console.info("Operation time out: " + val.data); + } else { + console.info("Operation failed: " + val.data); + } + }) + ``` + + +## backgroundTaskManager.getRemainingDelayTime + +getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void + +获取应用程序进入挂起状态前的剩余时间，使用callback形式返回。 + +- **参数**： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | requestId | number | 是 | 延迟挂起的请求ID。 | + | callback | AsyncCallback<number> | 是 | 指定的callback回调方法。用于返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | + +- **示例**： + ``` + let id = 1; + backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { + if(err) { + console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + } else { + console.log('promise => Operation failed. Cause: ' + err.data); + } + }) + ``` + + +## backgroundTaskManager.getRemainingDelayTime + +getRemainingDelayTime(requestId: number): Promise<number> + +获取应用程序进入挂起状态前的剩余时间，使用Promise形式返回。 + +- **参数**： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | requestId | number | 是 | 延迟挂起的请求ID。 | + +- **返回值**： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 指定的Promise回调方法。返回应用程序进入挂起状态之前的剩余时间，以毫秒为单位。 | + +- **示例**： + ``` + let id = 1; + backgroundTaskManager.getRemainingDelayTime(id).then( res => { + console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + }).catch( err => { + console.log('promise => Operation failed. Cause: ' + err.data); + }) + ``` + + +## backgroundTaskManager.cancelSuspendDelay + +cancelSuspendDelay(requestId: number): void + +取消延迟挂起。 + +- **参数**： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | requestId | number | 是 | 延迟挂起的请求ID。 | + +- **示例**： + ``` + backgroundTaskManager.cancelSuspendDelay(id); + ``` + + +#### DelaySuspendInfo + +延迟挂起信息。 + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| requestId | number | 是 | 延迟挂起的请求ID。 | +| actualDelayTime | number | 是 | 应用的实际挂起延迟时间，以毫秒为单位。
一般情况下默认值为180000，低电量（依据系统低电量广播）时默认值为60000。 | + -- GitLab