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 0000000000000000000000000000000000000000..0c776e6816bad41ef6979e87df3cf64ddfe1b84a --- /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 0000000000000000000000000000000000000000..f3cec92c4187b4a63b4ca35f787b37e37c0a71d5 --- /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 Binary files /dev/null and b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-caution.gif differ 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 Binary files /dev/null and b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-danger.gif differ 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 Binary files /dev/null and b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-note.gif differ 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 Binary files /dev/null and b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-notice.gif differ diff --git a/zh-cn/application-dev/background-task-management/public_sys-resources/icon-tip.gif b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-tip.gif new file mode 100644 index 0000000000000000000000000000000000000000..93aa72053b510e456b149f36a0972703ea9999b7 Binary files /dev/null and b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-tip.gif differ diff --git a/zh-cn/application-dev/background-task-management/public_sys-resources/icon-warning.gif b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-warning.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/zh-cn/application-dev/background-task-management/public_sys-resources/icon-warning.gif differ 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 0000000000000000000000000000000000000000..bdab942d855725655b9333057609ef423639c588 --- /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。 | +