使用 @capgo/capacitor-background-task
在 Capacitor 应用中调度周期性后台 fetch 任务，支持命名任务、持久化注册、状态检查、注销和开发触发。该插件使用 Android WorkManager 和 iOS BGTaskScheduler。
安装
npm install @capgo/capacitor-background-task
npx cap sync
iOS 配置
为以下应用添加后台处理支持 ios/App/App/Info.plist:
<key>UIBackgroundModes</key>
<array>
<string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>app.capgo.backgroundtask.processing</string>
</array>
然后运行：
npx cap sync ios
插件暴露的内容
defineTask- 为指定任务定义 JavaScript 回调。registerTaskAsync- 持久化并调度周期性任务。unregisterTaskAsync- 取消单个任务。isTaskRegisteredAsync- 检查单个任务的注册状态。getRegisteredTasksAsync- 列出已注册的任务名称。getStatusAsync- 检查原生后台任务是否可用。triggerTaskWorkerForTestingAsync- 开发时立即触发已注册的任务。addExpirationListener- 在 iOS 任务过期时进行响应。
用法示例
在模块作用域内定义任务，以便在 OS 唤醒 App 时可用：
import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';
const SYNC_TASK = 'sync-offline-data';
BackgroundTask.defineTask(SYNC_TASK, async () => {
try {
await fetch('https://api.example.com/sync', { method: 'POST' });
return BackgroundTaskResult.Success;
} catch {
return BackgroundTaskResult.Failed;
}
});
await BackgroundTask.registerTaskAsync(SYNC_TASK, {
minimumInterval: 30,
requiresNetwork: true,
});
检查状态和已注册的任务名称：
const status = await BackgroundTask.getStatusAsync();
const tasks = await BackgroundTask.getRegisteredTasksAsync();
console.log({ status, tasks });
触发开发运行：
await BackgroundTask.triggerTaskWorkerForTestingAsync();
取消任务：
await BackgroundTask.unregisterTaskAsync(SYNC_TASK);
平台注意事项
- 后台任务调度具有随机性，并非精确计时器。
- Android 的周期性工作最小间隔为 15 分钟。
- iOS 将
minimumInterval视为最早开始时间，可能会延迟运行。 - 请在真机上测试 iOS 后台处理功能。
完整参考
- GitHub: https://github.com/Cap-go/capacitor-background-task/
- 文档：/docs/plugins/background-task/
从“使用 @capgo/capacitor-background-task”继续
如果你正在使用 使用 @capgo/capacitor-background-task 要规划原生插件工作，请将其与 @capgo/capacitor-background-task 有关 @capgo/capacitor-background-task 的实现细节， 快速入门 有关“入门指南”中的实现细节， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 有关 Capgo 开发的 Capacitor 插件的实现细节，以及 添加或更新插件 有关添加或更新插件的实现细节。