@expo-harmony/expo-background-fetch

GitHub 仓库 | 官方文档

为 HarmonyOS 上的 React Native 应用提供 Expo Background Fetch 的原生实现，与官方同版本的 expo-background-fetch 和 expo-task-manager 配套使用。

安装

npm install @expo-harmony/expo-background-fetch [email protected] expo-task-manager@~55.0.20

使用前必须在 app.json 的 plugins 中传入 @expo-harmony/expo-background-fetch，并将其放在 @expo-harmony/prebuild-config 之前：

{
  "expo": {
    "plugins": [
      "@expo-harmony/expo-background-fetch",
      "@expo-harmony/prebuild-config"
    ]
  }
}

HarmonyOS Work Scheduler 的周期任务最短间隔为 2 小时，实际执行时间还会受到系统电量、配额和应用活跃度影响。

本包最低支持 HarmonyOS 5.0.1（API 13），宿主应用的 compatibleSdkVersion 不能低于这个版本。模块和 config plugin 都不声明权限，任务需要访问网络等资源时，由应用按实际业务声明所需权限。

API 对照表

Methods

BackgroundFetch.getStatusAsync()

返回 Promise<BackgroundFetchStatus>。系统具备 Work Scheduler 能力、且应用能在无界面场景下启动时返回 Available，否则返回 Restricted。HarmonyOS 没有针对单个应用的后台刷新开关，Denied 没有取值来源。

BackgroundFetch.registerTaskAsync(taskName, options)

返回 Promise<void>。任务先用 TaskManager.defineTask 定义，注册后写入 Work Scheduler，应用初始化时自动恢复。同名任务重复注册会替换之前的注册，并复用原来的调度名额，已注册满 10 个任务时也能完成替换。

与上游一样，注册不要求联网，离线任务也会被系统调度。升级后恢复旧版本注册的任务时，会移除当时附带的联网条件。

taskName 需为非空字符串，options 默认 {}。应用在前台时暂停执行，切回后台后允许系统继续调度。单次回调最长运行 2 分钟，超时系统会终止承载任务的 Extension 进程。单个应用同一时刻最多注册 10 个延迟任务。

Work Scheduler 不可用、config plugin 未应用、任务名或选项不合法时拒绝。

BackgroundFetch.unregisterTaskAsync(taskName)

返回 Promise<void>，取消任务在 Work Scheduler 中的注册。任务不存在时拒绝。

未实现的内容

• setMinimumIntervalAsync(minimumInterval)：HarmonyOS 按任务设置间隔，没有全局间隔设置，调用不产生效果。

Types

BackgroundFetchOptions

| 属性 | 类型 | | ----------------- | --------- | | minimumInterval | number | | stopOnTerminate | boolean | | startOnBoot | boolean |

minimumInterval 以秒为单位，默认 600（10 分钟），必须是正有限数。Work Scheduler 能接受的间隔上限是 2147483.647 秒（约 24.86 天），更大的值在注册时拒绝。重复间隔会被抬到至少 2 小时，实际触发时间由系统调度决定，不保证精确。执行频率还按应用活跃分组分级限制：

• 活跃分组：最短 2 小时
• 经常使用分组：4 小时
• 常用分组：24 小时
• 极少使用分组：48 小时
• 受限使用分组、从未使用分组：不执行

stopOnTerminate 默认 true，最后一个 UIAbility 正常销毁后停止执行任务。后台无界面运行时释放和开发时重新加载不视为应用终止。

startOnBoot 默认 false。为 true 时任务持久化到系统，设备重启后恢复。两个选项独立配置：

| stopOnTerminate | startOnBoot | 正常终止后 | 设备重启后 | | ----------------- | ------------- | ---------- | ---------- | | true | false | 停止 | 不恢复 | | true | true | 停止 | 恢复 | | false | false | 继续调度 | 不恢复 | | false | true | 继续调度 | 恢复 |

开机恢复使用系统持久化任务；前台暂停和终止状态按系统启动次数记录，扩展回调在加载 JS 前检查。系统重启后旧状态失效。系统强杀若不发送销毁回调，无法保证执行 stopOnTerminate 清理；系统强行停止应用时还受系统后台限制约束。

stopOnTerminate 和 startOnBoot 官方标记为 Android 专属，在 HarmonyOS 上可用。传入未知字段时拒绝。

Enums

BackgroundFetchResult

| 成员 | 值 | 含义 | | --------- | --- | ------------------ | | NoData | 1 | 没有新数据 | | NewData | 2 | 成功获取到新数据 | | Failed | 3 | 尝试获取数据但失败 |

返回值在 HarmonyOS 上不影响后续调度。

BackgroundFetchStatus

| 成员 | 值 | 含义 | | ------------ | --- | -------------------------------- | | Denied | 1 | 用户关闭了后台行为 | | Restricted | 2 | 后台更新不可用，用户无法重新开启 | | Available | 3 | 后台更新可用 |

getStatusAsync() 在 HarmonyOS 上只会返回 Restricted 或 Available。

原生初始化

不需要写原生初始化代码。模块在应用启动时自动向 TaskManager 注册，进程由后台任务冷启动、尚未打开界面时也一样。CNG 工程的入口由 prebuild 自动生成。升级已有的 Bare 工程时，需要在 module.json5 中登记 module.srcEntry，见 接入说明。

Author

expo-harmony © Baoshuo, Released under the MIT License. Authored and maintained by Baoshuo with help from contributors.

Personal Website · Blog · GitHub @renbaoshuo · Twitter @renbaoshuo