跳转到正文

@capgo/capacitor-background-task

iOS 和 Android 上的周期性后台 fetch 任务。

定义模块作用域任务、设置调度间隔,并返回 OS 可识别的结果,用于同步和缓存预热。

平台支持备注
iOS是Info.plist 中的 BGTaskScheduler 标识符
Android是WorkManager 风格的任务
Web 端否使用 Service Worker
  • defineTask - 为具名任务注册 JavaScript 回调。
  • registerTaskAsync - 持久化并调度周期性任务。
  • unregisterTaskAsync - 取消某个任务的后续执行。
  • isTaskRegisteredAsync - 检查任务是否已注册。
  • getRegisteredTasksAsync - 列出当前已注册的任务名称。
  • getPendingTaskRunsAsync - 查看 JavaScript 就绪前记录的原生任务事件。
  • getStatusAsync - 检查原生后台任务的可用性。
  • triggerTaskWorkerForTestingAsync - 在开发期间立即运行已注册的任务。
  • addExpirationListener - 处理 iOS 过期回调。
  • define, schedule, cancel, statusAsync,以及 finish - 兼容性辅助工具,用于 react-native-background-task.

后台任务并非精确计时器。Android 和 iOS 会根据电池、网络、应用使用情况和系统策略来决定何时运行计划任务。

平台原生调度器重要行为说明
AndroidWorkManager周期性任务的最小间隔为 15 分钟。
iOSBGTaskSchedulerminimumInterval 是最早开始日期,而非保证的执行频率。
Web 端仅用于测试的回退方案没有可用的真实后台调度器。
方法描述
defineTask为命名任务定义 JavaScript 回调。
registerTaskAsync注册一个命名的周期性后台任务。
unregisterTaskAsync取消未来的任务运行。
isTaskRegisteredAsync返回任务是否已注册。
getRegisteredTasksAsync列出已注册的任务名称。
getPendingTaskRunsAsync列出等待完成的 native 任务事件。
getStatusAsync返回 native 后台调度是否可用。
triggerTaskWorkerForTestingAsync触发已注册的任务,用于开发和 QA。
addExpirationListener监听 iOS 过期事件。

此参考文档同步自 src/definitions.ts 中的 capacitor-background-task.

如果你正在使用 @capgo/capacitor-background-task 要规划原生插件工作,请将其与 使用 @capgo/capacitor-background-task 用于“使用 @capgo/capacitor-background-task”中的原生能力, Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 关于“添加或更新插件”中的实现细节,以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。