# @capgo/capacitor-background-task 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-background-task/

版本：8\.1\.12
npm 元数据更新时间：2026-10-15T06:15:32.956Z
中文译文更新时间：2026-11-09T04:03:23.169Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-background-task
原文对照：https://npmcn.com/package/%40capgo/capacitor-background-task/?lang=original
项目主页：https://capgo.app/docs/plugins/background-task/
源码仓库：https://github.com/Cap-go/capacitor-background-task

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：156 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-05-12T09:38:39.606Z
- 最新版本发布：2026-10-15T06:15:32.687Z
- 近 30 天下载量：40293（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

用于定期背景的 Capacitor 插件获取关于iOS和Android的任务.

## 安装

```sh
npm install @capgo/capacitor-background-task
```

也可以使用：`pnpm add @capgo/capacitor-background-task`、`yarn add @capgo/capacitor-background-task`、`bun add @capgo/capacitor-background-task`

## README

# @ capgo/ 电容器- 后地任务

在 iOS 和 Android 上运行您的 Capacitor app 中定期的背景任务, 并带有在 app 重新启动中幸存的命名任务 。 在应用程序未打开时同步数据或刷新内容 .

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-background-task)](https://capgo.app/?ref=plugin_background_task)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_background_task)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_background_task) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-background-task` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加入@capgo/capor-background-task 到我的Capacitor app,并把它连接起来。"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_background_task) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_background_task)

![@capgo/capacitor-background-task for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-background-task/main/assets/github-social-preview.png)

## 主要特点

-   **命名任务**数字 : `registerTaskAsync()` 财务报告和审定财务报表 `unregisterTaskAsync()` 选项 `minimumInterval` 财务报告和审定财务报表 `requiresNetwork`。 。 。 .
-   **状态**数字 : `isTaskRegisteredAsync()`, (中文(简体) ), `getRegisteredTasksAsync()` 财务报告和审定财务报表 `getStatusAsync()` 报告已安排和可用的情况.
-   **运行失败**数字 : `getPendingTaskRunsAsync()` 返回在 JavaScript 准备好之前在本地记录.
-   **测试**数字 : `triggerTaskWorkerForTestingAsync()` 在开发过程中立即运行所有已登记的任务.
-   **熟悉的 API**: 博览会背景 任务样式 API + React 原生背景任务兼容 `schedule()`, (中文(简体) ), `cancel()` 财务报告和审定财务报表 `finish()`。 。 。 .
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-22. iOS使用"背景任务",Android使用"WorkManager". Web是根茎.

## 它会做什么

-   与 WorkManager 定期安排关于Android的背景工作.
-   用 BGTaskScheduler 来排程 iOS 上的背景处理 .
-   支持多个命名任务 `minimumInterval` 几分钟后.
-   Emits 保留任务事件, 因此任务运行在 JavaScript 准备好之前可以被排出 .
-   提供小型 `react-native-background-task` 相容的 API : `define`, (中文(简体) ), `schedule`, (中文(简体) ), `cancel`, (中文(简体) ), `statusAsync`,以及 `finish`。 。 。 .

## 限制

-   背景任务不是精确的定时器 。 Android和iOS决定工作实际运行时间.
-   Android执行15分最小间隔.
-   iOS可能基于电池,网络和用户行为进行大量延迟运行.
-   iOS背景任务不运行于模拟器;使用物理设备.
-   此插件无法在背景中无限期运行应用程序 .

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | 应要求 |

政策:

-   新的插件从版本开始 `8.0.0` (8号电站基线).
-   对更古老的Capacitor主机的后向相容性按需支持.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-background-task` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-background-task
npx cap sync
```

## iOS 设置

添加背景处理模式和允许的任务标识符 `ios/App/App/Info.plist`数字 :

```xml
<key>UIBackgroundModes</key>
<array>
  <string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>app.capgo.backgroundtask.processing</string>
</array>
```

## 使用量

定义模块范围的任务,以便在操作系统启动应用程序后立即提供.

```typescript
import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

const SYNC_TASK = 'sync-offline-data';

BackgroundTask.defineTask(SYNC_TASK, async () => {
  try {
    await fetch('https://example.com/sync', { method: 'POST' });
    return BackgroundTaskResult.Success;
  } catch {
    return BackgroundTaskResult.Failed;
  }
});

await BackgroundTask.registerTaskAsync(SYNC_TASK, {
  minimumInterval: 30,
  requiresNetwork: true,
});
```

## 测试

```typescript
await BackgroundTask.triggerTaskWorkerForTestingAsync();
```

## 反应本地兼容性

```typescript
import { BackgroundTask } from '@capgo/capacitor-background-task';

BackgroundTask.define(async () => {
  await fetch('https://example.com/sync', { method: 'POST' });
});

await BackgroundTask.schedule({
  period: 1800,
});
```

## 示例应用

这个 `example-app/` 文件夹通过 `file:..` 用于验证开发期间的本地接线.

## API 密码

-   [`defineTask(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-definetask)
-   [`registerTaskAsync(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-registertaskasync)
-   [`unregisterTaskAsync(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-unregistertaskasync)
-   [`isTaskRegisteredAsync(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-istaskregisteredasync)
-   [`getRegisteredTasksAsync()`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-getregisteredtasksasync)
-   [`getPendingTaskRunsAsync()`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-getpendingtaskrunsasync)
-   [`getStatusAsync()`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-getstatusasync)
-   [`triggerTaskWorkerForTestingAsync()`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-triggertaskworkerfortestingasync)
-   [`addExpirationListener(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-addexpirationlistener)
-   [`define(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-define)
-   [`schedule(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-schedule)
-   [`cancel()`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-cancel)
-   [`statusAsync()`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-statusasync)
-   [`finish(...)`](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-finish)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-enums)

### 定义任务(...)

```typescript
defineTask(taskName: string, callback: BackgroundTaskCallback) => void
```

定义 JavaScript 回调任务 。 将此调用到模块/ 全球范围 .

| 参数 | 类型 |
| --- | --- |
| **`taskName`** | `string` |
| **`callback`** | `[BackgroundTaskCallback](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskcallback)` |

* * *

### 注册任务Async(...)

```typescript
registerTaskAsync(taskName: string, options?: BackgroundTaskOptions | undefined) => Promise<void>
```

注册一个命名的定期背景任务 .

| 参数 | 类型 |
| --- | --- |
| **`taskName`** | `string` |
| **`options`** | `[BackgroundTaskOptions](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskoptions)` |

* * *

### 未注册的任务Async (...)

```typescript
unregisterTaskAsync(taskName: string) => Promise<void>
```

取消一个命名的周期性背景任务 .

| 参数 | 类型 |
| --- | --- |
| **`taskName`** | `string` |

* * *

### 是任务注册的 Async (...)

```typescript
isTaskRegisteredAsync(taskName: string) => Promise<boolean>
```

检查是否注册了命名的任务 .

| 参数 | 类型 |
| --- | --- |
| **`taskName`** | `string` |

**回返情况:** `Promise<boolean>`

* * *

### 获得注册的任务Async ()

```typescript
getRegisteredTasksAsync() => Promise<string[]>
```

返回所有已注册的任务名称 .

**回返情况:** `Promise<string[]>`

* * *

### 获取“ 指定任务” Async ()

```typescript
getPendingTaskRunsAsync() => Promise<BackgroundTaskEvent[]>
```

返回未完成的任务运行在 JavaScript 准备好之前的本地记录 .

**回返情况:** `Promise<BackgroundTaskEvent[]>`

* * *

### 获取状态

```typescript
getStatusAsync() => Promise<BackgroundTaskStatus>
```

返回本地背景任务可用性 .

**回返情况:** `Promise<[BackgroundTaskStatus](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskstatus)>`

* * *

### 触发工作任务测试

```typescript
triggerTaskWorkerForTestingAsync() => Promise<boolean>
```

立即触发所有已登记的任务进行开发/测试.

**回返情况:** `Promise<boolean>`

* * *

### 添加扩展倾听器(...)

```typescript
addExpirationListener(listener: (event: BackgroundTaskEvent) => void) => Promise<PluginListenerHandle>
```

听iOS过期回调.

| 参数 | 类型 |
| --- | --- |
| **`listener`** | `(event: [BackgroundTaskEvent](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-pluginlistenerhandle)>`

* * *

### 定义(...)

```typescript
define(callback: BackgroundTaskCallback) => void
```

React 原生背景任务相容的单任务定义助手.

| 参数 | 类型 |
| --- | --- |
| **`callback`** | `[BackgroundTaskCallback](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskcallback)` |

* * *

### 调度(...)

```typescript
schedule(options?: ReactNativeBackgroundTaskOptions | undefined) => Promise<void>
```

反应本地背景任务相容的单任务调度器 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ReactNativeBackgroundTaskOptions](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-reactnativebackgroundtaskoptions)` |

* * *

### 取消( )

```typescript
cancel() => Promise<void>
```

React 原生背景任务相容的单任务取消帮助器.

* * *

### 状态 Async ()

```typescript
statusAsync() => Promise<ReactNativeBackgroundTaskStatus>
```

反应本地背景任务相容状态助手 .

**回返情况:** `Promise<[ReactNativeBackgroundTaskStatus](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-reactnativebackgroundtaskstatus)>`

* * *

### 结束(...)

```typescript
finish(result?: BackgroundTaskResult | undefined) => Promise<void>
```

反应本地背景任务相容的完成帮助器 。 普通博览会风格 调用自动完成 .

| 参数 | 类型 |
| --- | --- |
| **`result`** | `[BackgroundTaskResult](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskresult)` |

* * *

### 接口

#### 背景任务活动

当本地调度要求 JavaScript 执行任务时, 有效载荷已释放 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`taskName`** | `string` | 名称传递给注册 TaskAsync . |
| **`taskId`** | `string` | 本地运行标识符 。 JavaScript 包装器在定义的回调解析后自动完成. |
| **`timestamp`** | `number` | 运行时的原生时间戳. |
| **`test`** | `boolean` | 触发任务测试时为真 . |

#### 背景任务选项

定期登记背景任务的选项.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`minimumInterval`** | `number` | 任务运行之间的分钟间隔不准确 。 默认为720分. Android执行最少15分钟. iOS视此为最早的起步日期,可能运行较晚. |
| **`requiresNetwork`** | `boolean` | 运行本地调度器前需要活动网络 。 默认为真. |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 反活动背景任务选项

反应本地背景任务兼容调度选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`period`** | `number` | 每次行刑时的欲望秒 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}至少一分钟. |
| **`timeout`** | `number` | Android-仅限超时提示保留了API兼容性. |

#### ReactNativeBackground 任务状态

反应原生背景任务相容状态有效载荷.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`available`** | `boolean` | 应用程序是否有背景任务可用 . |
| **`unavailableReason`** | `string` | 理由当没有. |

### 类型异名

#### 背景任务调用

为背景任务执行的函数 .

`(event: [BackgroundTaskEvent](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskevent)): void | [BackgroundTaskResult](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskresult) | Promise<void | [BackgroundTaskResult](https://npmcn.com/package/%40capgo/capacitor-background-task/#readme-backgroundtaskresult)>`

### 数字

#### 背景任务结果

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`Success`** | `1` | 任务成功完成 . |
| **`Failed`** | `2` | 任务失败 . |

#### 背景任务状态

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`Restricted`** | `1` | 背景任务时间安排没有或受到限制. |
| **`Available`** | `2` | 背景任务时间安排. |

## 常见问题

### @capgo/capacitor-background-task 是什么？

用于定期背景的 Capacitor 插件获取关于iOS和Android的任务\.

### 如何安装 @capgo/capacitor-background-task？

在项目目录运行 npm install @capgo/capacitor-background-task，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-background-task 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-background-task 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-background-task 可以商用吗？

@capgo/capacitor-background-task 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-background-task 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-background-task 在 2026/10/09 – 2026/11/07 这 30 天内被下载 40,293 次，日均约 1,343 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-background-task 还在维护吗？

最新版本 8\.1\.12 发布于 2026/10/15（25 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/05/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。