# @capacitor/background-runner 中文文档

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

版本：4\.0\.0
npm 元数据更新时间：2026-10-30T20:47:00.832Z
中文译文更新时间：2026-11-09T02:46:05.843Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capacitor/background-runner
原文对照：https://npmcn.com/package/%40capacitor/background-runner/?lang=original
源码仓库：https://github.com/ionic-team/capacitor-background-runner

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

- 包体积（解压后）：2.7 MB，68 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=9\.0\.0-alpha\.5
- 首次发布：2023-07-18T22:59:21.937Z
- 最新版本发布：2026-10-30T20:47:00.667Z
- 近 30 天下载量：77192（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 33 个）

## 中文简介

背景运行器

## 安装

```sh
npm install @capacitor/background-runner
```

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

## README

# @ capacor/ 背景运行器

背景 Runner 提供了一个基于事件的独立 JavaScript 环境,用于在网络视图外执行您的 Javascript 代码.

## 安装

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

背景跑者支持在使用前需要用户许可的各种设备API.

## iOS系统

在 iOS 上, 您必须启用背景模式能力 .

![Enable Background Mode Capability in Xcode](https://github.com/ionic-team/capacitor-background-runner/raw/main/docs/enable_background_mode_capability.png)

一旦加入,您必须启用 `Background fetch` 财务报告和审定财务报表 `Background processing` 模式,以便至少能够登记和安排背景任务.

如果您将使用地理定位或按下通知, 请启用 `Location updates` 或者说 `Remote notifications` 页:1.

![Configure Background Modes in Xcode](https://github.com/ionic-team/capacitor-background-runner/raw/main/docs/configure_background_modes.png)

您还需要在您的 `Info.plist` 文件 :

```
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.example.background.task</string>
</array>
```

阅读 [配置 `Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) 输入 [iOS 指南](https://capacitorjs.com/docs/ios) 在 Xcode 中设置 iOS 权限的更多信息.

确定您使用与您使用的相同的ID `BGTaskSchedulerPermittedIdentifiers` (例如"com.example.background.task")) 于"中国互联网档案馆的存檔,存档日期2011-12-21 `label` 字段在插件配置中.

在启用背景模式能力后, 在您的应用程序中添加以下内容 `AppDelegate.swift`数字 :

在档案的顶端,下 `import Capacitor` 添加:

```swift
import CapacitorBackgroundRunner
```

```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // ....
    BackgroundRunnerPlugin.registerBackgroundTask()
    BackgroundRunnerPlugin.handleApplicationDidFinishLaunching(launchOptions: launchOptions)
    // ....

    return true
}
```

为了允许背景运行器处理远程通知,请添加以下内容:

```swift
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        // ....
        BackgroundRunnerPlugin.dispatchEvent(event: "remoteNotification", eventArgs: userInfo) { result in
            switch result {
            case .success:
                completionHandler(.newData)
            case .failure:
                completionHandler(.failed)
            }
        }
    }
```

### 地理位置

苹果公司要求在其中指定隐私描述 `Info.plist` 地点信息:

-   `NSLocationAlwaysUsageDescription` (单位:千美元)`Privacy - Location Always Usage Description`(中文(简体) )
-   `NSLocationWhenInUseUsageDescription` (单位:千美元)`Privacy - Location When In Use Usage Description`(中文(简体) )

## 机器人

不需要额外设置.

如果您正在升级一个已有的Android项目,则早期版本的以下剩余部分将不再被使用并可以被删除:

-   内 `android/app/build.gradle`,则 `dirs '../../node_modules/@capacitor/background-runner/android/src/main/libs', 'libs'` 线条 `flatDir` 块
-   `android/src/main/libs/android-js-engine-release.aar`,如果从1.0.5或更早升级

### 地理位置

此 API 需要将以下权限添加到您 `AndroidManifest.xml`数字 :

```xml
<!-- Geolocation API -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location.gps" />
```

前两条权限都要求获得位置数据, 无论是精细还是粗糙, 最后一行是可选的, 但是如果您的应用需要的话 _需求_ GPS到功能状态 你可以不说,尽管要记住,这可能意味着你的应用安装在缺乏GPS硬件的设备上.

### 当地通知

Android 13需要经过许可检查才能发送通知. 您必须打电话 `checkPermissions()` 财务报告和审定财务报表 `requestPermissions()` 相应.

12岁及更年长的Android上,它不会显示一个快活的,而且会照常返回.

从Android 12开始 计划通知将是不准确的 除非这个许可被添加到您身上 `AndroidManifest.xml`数字 :

```xml
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
```

注意,即使权限存在,用户仍然可以禁用应用程序设置中准确的通知.

阅读 [设置权限](https://capacitorjs.com/docs/android/configuration#setting-permissions) 输入 [安卓指南](https://capacitorjs.com/docs/android) 用于获取关于设置Android权限的更多信息.

## 关于背景运行器

在构建复杂应用的过程中,它有时在应用不在前期时需要进行工作. 标准Capacitor应用程序的挑战是,当这些背景事件发生时,网页视图不可用,需要您写出本地代码来处理这些事件. 这是背景运行器插件进入的地方 .

背景 Runner 使 JavaScript 代码容易处理本地背景事件. 您只需要创建您的运行 JavaScript 文件 [定义您的配置](https://npmcn.com/package/%40capacitor/background-runner/#readme-configuring-background-runner),然后背景运行器插件将自动配置和安排本地背景任务,这些任务将根据您的配置和平台规则执行。 无需修改您的用户界面代码 .

## 使用背景运行器

背景运行器包含一个无头的 JavaScript 环境,在您指定的 Javascript 文件中调用事件处理器 `capacitor.config.ts` 文档。 如果运行者在您的运行文件中找到一个事件处理器, 它会执行事件处理器, 然后关闭一次 `resolve()` 或者说 `reject()` 被调用(或者如果OS部队杀死了您的进程).

#### 实例运行者 JS 文件

```js
addEventListener('myCustomEvent', (resolve, reject, args) => {
  console.log('do something to update the system here');
  resolve();
});

addEventListener('myCustomEventWithReturnData', (resolve, reject, args) => {
  try {
    console.log('accepted this data: ' + JSON.stringify(args.user));

    const updatedUser = args.user;
    updatedUser.firstName = updatedUser.firstName + ' HELLO';
    updatedUser.lastName = updatedUser.lastName + ' WORLD';

    resolve(updatedUser);
  } catch (err) {
    reject(err);
  }
});

addEventListener('remoteNotification', (resolve, reject, args) => {
  try {
    console.log('received silent push notification');

    CapacitorNotifications.schedule([
      {
        id: 100,
        title: 'Enterprise Background Runner',
        body: 'Received silent push notification',
      },
    ]);

    resolve();
  } catch (err) {
    reject();
  }
});
```

通话 `resolve()` \\ `reject()` 实值 **所需经费** 在每一个事件处理者 由跑者召唤。 不这样做可能导致您的跑者被操作系统所杀, 如果您的事件被调用而应用程序处于背景 。 如果应用程序位于前方,则Async呼叫 `dispatchEvent` 可能无法解决问题.

对于使用背景运行器的更真实的世界实例,请检查 [背景运行器测试 App](https://github.com/ionic-team/background-runner-testapp)。 。 。 .

## 配置背景运行器

装入时, 背景运行器会自动注册一个 一旦您的应用程序被安排并运行的背景任务 有背景介绍.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`label`** | `string` | 跑道名,用在木上. | 1.0.0 (单位:千美元) |
| **`src`** | `string` | 运行 JavaScript 文件的路径,相对于应用程序捆绑. | 1.0.0 (单位:千美元) |
| **`event`** | `string` | 当OS执行背景任务时将调用的事件名称 . | 1.0.0 (单位:千美元) |
| **`repeat`** | `boolean` | 如果背景任务应该根据所设定的间隔重复 `interval`。 。 。 . | 1.0.0 (单位:千美元) |
| **`interval`** | `number` | 应用被放入开始背景任务的背景后的分钟数 。 若为 `repeat` ,这也指定了每次执行之间的分钟数. | 1.0.0 (单位:千美元) |
| **`autoStart`** | `boolean` | 自动注册和安排应用程序加载的背景任务 . | 1.0.0 (单位:千美元) |

### 实例

单位 `capacitor.config.json`数字 :

```json
{
  "plugins": {
    "BackgroundRunner": {
      "label": "com.example.background.task",
      "src": "runners/background.js",
      "event": "myCustomEvent",
      "repeat": true,
      "interval": 15,
      "autoStart": true
    }
  }
}
```

单位 `capacitor.config.ts`数字 :

```ts
/// <reference types="@capacitor/background-runner" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    BackgroundRunner: {
      label: "com.example.background.task",
      src: "runners/background.js",
      event: "myCustomEvent",
      repeat: true,
      interval: 15,
      autoStart: true,
    },
  },
};

export default config;
```

## Java 脚本 API

背景 Runner 不在浏览器或网页视图中执行您的 Javascript 代码, 因此您可能使用的典型 Web API 可能无法使用 。 包括DOM API 或与您的应用程序的DOM交互能力.

以下是背景运行器提供的可用网络API列表:

-   [控制台](https://developer.mozilla.org/en-US/docs/Web/API/console)
    -   仅限 `info`, (中文(简体) ), `log`, (中文(简体) ), `warn`, (中文(简体) ), `error` ,以及 `debug` 备有
-   [文本解析器](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
    -   仅限 `decode` 可用
-   [文本编码器](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
    -   仅限 `encode` 可用
-   [添加事件倾听器](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
    -   事件倾听者选项和 `useCapture` 不支持
-   [设置时间](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)
-   [设置间距](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)
-   [清除超时](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout)
-   [清除间隔](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)
-   [密码](https://developer.mozilla.org/en-US/docs/Web/API/Crypto)
-   [获取](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
    -   尚未支持的请求对象
    -   仅 `method`, (中文(简体) ), `headers` 财务报告和审定财务报表 `body` 选项对象中支持

除了标准的Web API,背景运行器还支持一些 [自定义控制器 API](https://npmcn.com/package/%40capacitor/background-runner/#readme-capacitor-api) 显示相关移动设备功能的自定义 API

## 运行时间

目前,跑步者被设计为在您的应用处于后台时进行周期性连续工作,或者在您的应用处于前台时执行与您的UI分离的线程中的同步工作. 因此,跑步者寿命不长. 竞技场的赛事不设状态。 每次打给 `dispatchEvent()` 创建一个新上下文,用于您运行的代码被装入并执行,一次 `resolve()` 或者说 `reject()` 称为,上下文被破坏.

## Android 电池优化

一些Android小贩提供内置电池优化设置,这些设置超越了Android的库存. 其中一些优化必须被您的终端用户禁用,以便您的背景任务正常工作.

访问 [别杀我的应用程序!](https://dontkillmyapp.com/) 用于了解受影响的制造商和用户调整设置所需步骤的更多信息.

## 背景任务的限制

无法在移动操作系统中运行持续,总是运行背景服务. 由于iOS和Android为了减少电池和数据消耗而设计的限制,背景任务受到各种限制的限制,在设计和实施你的背景任务时必须记住这些限制.

### iOS系统

-   每次引用你的任务 大约有30秒的运行时间 `completed()` 或者你的任务被杀死.
-   尽管您可以设定一个间隔来定义您的任务在应用程序背景之后运行的时间, 或者它应该运行多少次, 但这并不能保证 。 iOS将决定您的任务最终运行的时间和频率,部分由您应用的频率决定.
-   模拟器中没有执行背景任务 .

### 机器人

-   您的任务执行时间最长为10分钟,但为了保持您的任务交叉平台相容,您应当将工作限制在最多为30秒.
-   重复的背景任务最小间隔至少为15分钟. 与iOS类似,任何你要求的间隔都可能不会被精确地击中——实际执行时间受OS电池优化和其他heuristics的限制.

## API 密码

-   [`checkPermissions()`](https://npmcn.com/package/%40capacitor/background-runner/#readme-checkpermissions)
-   [`requestPermissions(...)`](https://npmcn.com/package/%40capacitor/background-runner/#readme-requestpermissions)
-   [`dispatchEvent(...)`](https://npmcn.com/package/%40capacitor/background-runner/#readme-dispatchevent)
-   [`addListener('backgroundRunnerNotificationReceived', ...)`](https://npmcn.com/package/%40capacitor/background-runner/#readme-addlistenerbackgroundrunnernotificationreceived-)
-   [`removeNotificationListeners()`](https://npmcn.com/package/%40capacitor/background-runner/#readme-removenotificationlisteners)
-   [接口](https://npmcn.com/package/%40capacitor/background-runner/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capacitor/background-runner/#readme-type-aliases)

### 检查( )

```typescript
checkPermissions() => any
```

检查各种 Capacitor 设备 API 的权限 .

**回返情况:** `any`

**自:** 1.0.0 (单位:千美元)

* * *

### 请求(...)

```typescript
requestPermissions(options: RequestPermissionOptions) => any
```

请求显示本地通知的权限 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RequestPermissionOptions](https://npmcn.com/package/%40capacitor/background-runner/#readme-requestpermissionoptions)` |

**回返情况:** `any`

**自:** 1.0.0 (单位:千美元)

* * *

### 调度事件(...)

```typescript
dispatchEvent<T = void>(options: DispatchEventOptions) => any
```

向配置的跑者发送事件 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DispatchEventOptions](https://npmcn.com/package/%40capacitor/background-runner/#readme-dispatcheventoptions)` |

**回返情况:** `any`

**自:** 1.0.0 (单位:千美元)

* * *

### 添加 listener ("背景运行通知收到",...)

```typescript
addListener(eventName: 'backgroundRunnerNotificationReceived', listenerFunc: (event: NotificationActionEvent) => void) => any
```

为通知动作添加一个收听器 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'backgroundRunnerNotificationReceived'` |
| **`listenerFunc`** | `(event: [NotificationActionEvent](https://npmcn.com/package/%40capacitor/background-runner/#readme-notificationactionevent)) => void` |

**回返情况:** `any`

**自:** 2.1.1 国家

* * *

### 删除通知听众( )

```typescript
removeNotificationListeners() => any
```

删除此插件的通知动作听器 .

**回返情况:** `any`

**自:** 2.1.1 国家

* * *

### 接口

#### 权限状态

| Prop | 类型 |
| --- | --- |
| **`geolocation`** | `[PermissionState](https://npmcn.com/package/%40capacitor/background-runner/#readme-permissionstate)` |
| **`notifications`** | `[PermissionState](https://npmcn.com/package/%40capacitor/background-runner/#readme-permissionstate)` |

#### 请求允许选项

| Prop | 类型 |
| --- | --- |
| **`apis`** | `{}` |

#### 调度事件选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`label`** | `string` | 将事件发送到 | 1.0.0 (单位:千美元) |
| **`event`** | `string` | 已注册事件听众名称 . | 1.0.0 (单位:千美元) |
| **`details`** | `{ [key: string]: any; }` |  |  |

#### 通知行动活动

| Prop | 类型 |
| --- | --- |
| **`actionTypeId`** | `string` |
| **`notificationId`** | `number` |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => any` |

### 类型异名

#### 权限状态

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

#### API 密码

`'geolocation' | 'notifications'`

## API 电源

### 接口

#### 电容设备

获取设备信息,如网络连接和电池状态等.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`getBatteryStatus`** | `() => [BatteryStatus](https://npmcn.com/package/%40capacitor/background-runner/#readme-batterystatus)` | 获取设备的当前电池状态 . | 1.0.0 (单位:千美元) |
| **`getNetworkStatus`** | `() => [NetworkStatus](https://npmcn.com/package/%40capacitor/background-runner/#readme-networkstatus)` | 获取设备的当前网络状态 . | 1.0.0 (单位:千美元) |

#### 电池状况

| Prop | 类型 |
| --- | --- |
| **`batteryLevel`** | `number` |
| **`isCharging`** | `boolean` |

#### 网络状态

| Prop | 类型 |
| --- | --- |
| **`connected`** | `boolean` |
| **`connectionType`** | `string` |

#### 电源KV

一个简单的字符串密钥/由用户Defaults在iOS和共享首选项在Android上支持的值商店.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`set`** | `(key: string, value: string) => void` | 用给定的密钥设置字符串值 . | 1.0.0 (单位:千美元) |
| **`get`** | `(key: string) => { value: string; }` | 获取给定密钥的字符串值 . | 1.0.0 (单位:千美元) |
| **`remove`** | `(key: string) => void` | 删除给定键的值 . | 1.0.0 (单位:千美元) |

#### 电容

发送基本的本地通知 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`schedule`** | `(options: {}) => void` | 安排当地通知 | 1.0.0 (单位:千美元) |
| **`setBadge`** | `(options: [NotificationBadgeOptions](https://npmcn.com/package/%40capacitor/background-runner/#readme-notificationbadgeoptions)) => void` | 设置应用程序徽章计数 | 2.0.0 (韩语) |
| **`clearBadge`** | `() => void` | 清除应用程序徽章计数 | 2.0.0 (韩语) |

#### 通知列表选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `number` | 通知识别符。 在Android上,这是一英寸32分 因此,该值应该介于-2147483648和2147483647(含)之间. | 1.0.0 (单位:千美元) |
| **`title`** | `string` | 通知的标题. | 1.0.0 (单位:千美元) |
| **`body`** | `string` | 通知书正文如下:. | 1.0.0 (单位:千美元) |
| **`scheduleAt`** | `Date` | 发送通知的日期. | 1.0.0 (单位:千美元) |
| **`sound`** | `string` | 显示此通知时播放的音频文件名称 。 包含文件扩展名 。 在iOS上,文件应该在应用程序包中. 在Android上,文件应该放在res/raw文件夹中. 建议的格式是 `.wav` 因为得到了iOS和Android的支持. 仅可用于iOS和Android < 26. 对于Android 26+,使用由所期望的声音所配置的频道的频道Id. 如果找不到声音文件,则会使用默认系统通知声音(即空字符串或错误名称)。 如果不提供,它将在Android上产生默认声音,而不会在iOS上产生声音. | 1.0.0 (单位:千美元) |
| **`actionTypeId`** | `string` | 将行动类型与本通知联系起来. | 1.0.0 (单位:千美元) |
| **`threadIdentifier`** | `string` | 用于组合多个通知. 设定 `threadIdentifier` 编辑 [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent)。仅供iOS使用. | 1.0.0 (单位:千美元) |
| **`summaryArgument`** | `string` | 此通知的字符串会添加该类的汇总格式字符串 。 仅供iOS使用. **此选项没有效果 .** `summaryArgument` 打开 [`UNMutableNotificationContent`](https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent) 自iOS 15起被贬值,且该值被系统忽略,因此不再被设定在通知内容上. | 1.0.0 (单位:千美元) |
| **`group`** | `string` | 用于组合多个通知. 电话 `setGroup()` 打开 [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) 与所提供的价值。 仅供Android使用. | 1.0.0 (单位:千美元) |
| **`groupSummary`** | `string` | 如果情况属实,该通知将成为一组通知的概要。 电话 `setGroupSummary()` 打开 [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) 与所提供的价值。 仅供Android使用时使用 `group`。 。 。 . | 1.0.0 (单位:千美元) |
| **`extra`** | `any` | 在此通知中设置要存储的额外数据 . | 1.0.0 (单位:千美元) |
| **`ongoing`** | `boolean` | 如果是真的,通知不能被刷去. 电话 `setOngoing()` 打开 [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) 与所提供的价值。 仅供Android使用. | 1.0.0 (单位:千美元) |
| **`autoCancel`** | `boolean` | 如果真实, 当用户点击时, 通知会被取消 。 电话 `setAutoCancel()` 打开 [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) 与所提供的价值。 仅供Android使用. | 1.0.0 (单位:千美元) |
| **`largeBody`** | `string` | 设置多行文本块,以大文本通知样式显示. | 1.0.0 (单位:千美元) |
| **`summaryText`** | `string` | 用于将摘要文本细节设置在收件箱和大文本通知样式中. 仅供Android使用. | 1.0.0 (单位:千美元) |
| **`smallIcon`** | `string` | 设置自定义状态栏图标 。 如果设定,此选项将覆盖 `smallIcon` 选项。 图标应该放置在您的应用程序中 `res/drawable` 文件夹。 此选项的值应该是可绘制的资源ID, 即没有扩展名的文件名 。 仅供Android使用. | 1.0.0 (单位:千美元) |
| **`largeIcon`** | `string` | 设置通知的大图标 。 图标应该放置在您的应用程序中 `res/drawable` 文件夹。 此选项的值应该是可绘制的资源ID, 即没有扩展名的文件名 。 仅供Android使用. | 1.0.0 (单位:千美元) |
| **`channelId`** | `string` | 指定应发送通知的频道。 如果该名称的频道不存在,则通知不会开火。 如果不提供,它将使用默认通道。 电话 `setChannelId()` 打开 [`NotificationCompat.Builder`](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) 与所提供的价值。 仅供Android 26+使用. | 1.0.0 (单位:千美元) |

#### 通知选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`count`** | `number` | 申请徽章计数时的编号 . | 2.0.0 (韩语) |
| **`notificationTitle`** | `string` | 这个 **所需经费** 相关徽章计数通知的标题。 只为安卓. | 2.0.0 (韩语) |
| **`notificationSubtitle`** | `string` | 相关警徽计数通知的字幕. 只为安卓. | 2.0.0 (韩语) |

#### 电源定位

获取设备位置信息 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`getCurrentPosition`** | `() => [GetCurrentPositionResult](https://npmcn.com/package/%40capacitor/background-runner/#readme-getcurrentpositionresult)` | 获取设备的最后一个已知位置 | 1.0.0 (单位:千美元) |

#### 获取当前选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`latitude`** | `number` | 十进制纬度 | 1.0.0 (单位:千美元) |
| **`longitude`** | `number` | 十进制经度 | 1.0.0 (单位:千美元) |
| **`accuracy`** | `number` | 以米计的经纬度坐标的精确度 | 1.0.0 (单位:千美元) |
| **`altitude`** | `number | null` | 用户的高度( 如果有的话) | 1.0.0 (单位:千美元) |
| **`altitudeAccuracy`** | `number | null` | 如果有的话,高度坐标的精确度为米。 可在所有iOS版本和Android 8.0+上查阅. | 1.0.0 (单位:千美元) |
| **`speed`** | `number | null` | 用户正在旅行的速度( 如果可用) | 1.0.0 (单位:千美元) |
| **`heading`** | `number | null` | 用户所面临的标题( 如果有的话) | 1.0.0 (单位:千美元) |

#### 电容监视器

与该应用程序对齐的手表互动

发送Message, transfer UserInfo并更新应用 Context 是 WCSession 代表方法的原始路径,但目前没有效果 [电容监视器](https://npmcn.com/package/%40capacitor/background-runner/#readme-capacitorwatch) 观察应用. 如果开发本地手表应用作为Capacitor应用的配套应用,它们就可以被使用

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`sendMessage`** | `(options: []) => void` | 向手表发送信件, 并附上信件Message () WC会议代表方法 这对 [电容监视器](https://npmcn.com/package/%40capacitor/background-runner/#readme-capacitorwatch) 监视应用程序 |
| **`transferUserInfo`** | `(options: []) => void` | 使用用户信息( ) WCSession 代表方法向手表发送信息 这对 [电容监视器](https://npmcn.com/package/%40capacitor/background-runner/#readme-capacitorwatch) 监视应用程序 |
| **`updateApplicationContext`** | `(options: []) => void` | 用更新的应用程序更新手表上的应用程序上下文 WC会议代表方法 这对 [电容监视器](https://npmcn.com/package/%40capacitor/background-runner/#readme-capacitorwatch) 监视应用程序 |
| **`isReachable`** | `boolean` | 检查是否可到达配对表 |
| **`updateWatchUI`** | `(options: { watchUI: string; }) => void` | 将手表上当前的 UI 替换为这里指定的内容 . |
| **`updateWatchData`** | `(options: { data: { [key: string]: string; }; }) => void` | 更新手表用于显示文本和按钮字段中变量的数据 |

#### 电源App

| Prop | 类型 |
| --- | --- |
| **`getState`** | `() => [AppState](https://npmcn.com/package/%40capacitor/background-runner/#readme-appstate)` |
| **`getInfo`** | `() => [AppInfo](https://npmcn.com/package/%40capacitor/background-runner/#readme-appinfo)` |

#### 状态

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`isActive`** | `boolean` | 应用程序是否活动 . | 1.0.0 (单位:千美元) |

#### 应用信息

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`name`** | `string` | 应用名称. | 1.0.0 (单位:千美元) |
| **`id`** | `string` | 应用的标识符. 在iOS上是"包子识别器". 在Android上,这是应用程序ID | 1.0.0 (单位:千美元) |
| **`build`** | `string` | 建设版. 在iOS上,它是CFBundleVersion。 在Android上,这是Code的版本. | 1.0.0 (单位:千美元) |
| **`version`** | `string` | 应用版. 在iOS上,它是CFBundleShortVersion String. (中文(简体) ). 在Android上它是包的版本Name. | 1.0.0 (单位:千美元) |

## 常见问题

### @capacitor/background-runner 是什么？

背景运行器

### 如何安装 @capacitor/background-runner？

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

### @capacitor/background-runner 支持 TypeScript 吗？

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

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

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

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

@capacitor/background-runner 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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