版本：v6

@capacitor/background-runner

Background Runner 提供了一个基于事件的独立 JavaScript 环境，用于在 Web 视图之外执行您的 JavaScript 代码。

安装

npm install @capacitor/background-runner
npx cap sync

Background Runner 支持多种设备 API，这些 API 需要用户事先授权。

iOS

在 iOS 上，您必须启用 Background Modes 功能。

在 Xcode 中启用 Background Mode 功能

添加后，您必须至少启用 Background fetch 和 Background processing 模式，才能注册和调度后台任务。

如果您将使用 Geolocation 或 Push Notifications，请分别启用 Location updates 或 Remote notifications。

在 Xcode 中配置 Background Modes

启用 Background Modes 功能后，将以下内容添加到您的应用的 AppDelegate.swift 中：

在文件顶部，import Capacitor 下方添加：

import CapacitorBackgroundRunner

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

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

    return true
}

要允许 Background Runner 处理远程通知，请添加以下内容：

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)
            }
        }
    }

Geolocation（地理位置）

Apple 要求在 Info.plist 中为位置信息指定隐私描述：

NSLocationAlwaysUsageDescription（Privacy - Location Always Usage Description）
NSLocationWhenInUseUsageDescription（Privacy - Location When In Use Usage Description）

阅读 iOS 指南中关于配置 Info.plist 的内容，了解更多关于在 Xcode 中设置 iOS 权限的信息。

Android

在 android/app/build.gradle 中插入以下内容：

...

repositories {
    flatDir{
        dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
+		dirs '../../node_modules/@capacitor/background-runner/android/src/main/libs', 'libs'
    }
}
...

如果您从 1.0.5 升级且现有 Android 项目，请确保从 android/src/main/libs 中删除 android-js-engine-release.aar。

Geolocation（地理位置）

此 API 需要在您的 AndroidManifest.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 硬件的设备上。

Local Notifications（本地通知）

Android 13 需要权限检查才能发送通知。您需要相应地调用 checkPermissions() 和 requestPermissions()。

在 Android 12 及更早版本上，不会显示提示，直接返回已授权。

从 Android 12 开始，除非在 AndroidManifest.xml 中添加此权限，否则定时通知不会精确执行：

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

请注意，即使存在此权限，用户仍然可以从应用设置中禁用精确通知。

阅读 Android 指南中关于设置权限的内容，了解更多关于设置 Android 权限的信息。

关于 Background Runner

在构建复杂应用的过程中，有时需要在应用不在前台时执行工作。标准 Capacitor 应用的挑战在于，当这些后台事件发生时，WebView 不可用，这要求您编写原生代码来处理这些事件。Background Runner 插件就是为了解决这个问题而生的。

Background Runner 使得编写 JavaScript 代码来处理原生后台事件变得简单。您需要做的就是创建 runner JavaScript 文件并定义您的配置，然后 Background Runner 插件将自动配置和调度一个原生后台任务，该任务将根据您的配置和平台规则执行。无需修改您的 UI 代码。

使用 Background Runner

Background Runner 包含一个无头 JavaScript 环境，用于调用您在 capacitor.config.ts 文件中指定的 JavaScript 文件中的事件处理器。如果 runner 在您的 runner 文件中找到与传入事件对应的事件处理器，它将执行该事件处理器，然后在调用 resolve() 或 reject() 后关闭（或如果操作系统强制终止您的进程）。

Runner 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();
  }
});

在 runner 调用的每个事件处理器中必须调用 resolve() / reject()。如果未能做到这一点，当应用在后台时您的事件被调用，可能会导致您的 runner 被操作系统杀死。如果应用在前台，对 dispatchEvent 的异步调用可能无法 resolve。

更多使用 Background Runner 的实际示例，请查看 Background Runner Test App。

配置 Background Runner

加载时，Background Runner 将自动注册一个后台任务，该任务将在您的应用进入后台后被调度和执行。

属性	类型	描述	始于
`label`	`string`	runner 的名称，用于日志记录。	1.0.0
`src`	`string`	runner JavaScript 文件的路径，相对于应用包。	1.0.0
`event`	`string`	当操作系统执行后台任务时将调用的事件名称。	1.0.0
`repeat`	`boolean`	后台任务是否应根据 `interval` 中设置的时间间隔重复执行。	1.0.0
`interval`	`number`	应用进入后台后，后台任务开始执行的分钟数。如果 `repeat` 为 true，这也指定了每次执行之间的分钟数。	1.0.0
`autoStart`	`boolean`	是否在应用加载时自动注册和调度后台任务。	1.0.0

示例

在 capacitor.config.json 中：

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

在 capacitor.config.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;

JavaScript API

Background Runner 不在浏览器或 WebView 中执行您的 JavaScript 代码，因此您可能习惯的典型 Web API 可能不可用。这包括 DOM API 以及与应用程序 DOM 交互的能力。

以下是 Background Runner 中提供的 Web API 列表：

console
- 仅支持 info、log、warn、error 和 debug
TextDecoder
- 仅支持 decode
TextEncoder
- 仅支持 encode
addEventListener
- 不支持事件监听器选项和 useCapture
setTimeout
setInterval
clearTimeout
clearInterval
crypto
fetch
- 尚不支持 Request 对象
- options 对象中仅支持 method、headers 和 body

除了标准 Web API 之外，Background Runner 还支持许多自定义 Capacitor API，这些 API 暴露了相关的移动设备功能。

Runner 生命周期

目前，runner 设计用于在应用处于后台时执行周期性的突发工作，或在应用处于前台时在与 UI 分离的线程中执行异步工作。因此，runner 不会长期存在。runner 中的事件调用之间不会保持状态。每次调用 dispatchEvent() 都会创建一个新的上下文，在其中加载和执行您的 runner 代码，一旦调用 resolve() 或 reject()，该上下文就会被销毁。

Android 电池优化

一些 Android 厂商提供了超出原生 Android 的内置电池优化设置。其中一些优化必须由您的最终用户禁用，您的后台任务才能正常工作。

请访问 Don't kill my app! 了解受影响的制造商以及用户需要执行的步骤。

后台任务的限制

在移动操作系统上不可能运行持久性的、始终运行的后台服务。由于 iOS 和 Android 为减少电池和数据消耗而施加的限制，后台任务受到各种限制，您在设计和实现后台任务时必须牢记这些限制。

iOS

每次任务调用大约有最多 30 秒的运行时间，之后您必须调用 completed()，否则您的任务将被终止。
虽然您可以设置一个间隔来定义应用进入后台后任务的执行时间或执行频率，但这并不保证。iOS 将决定您的任务最终何时以及多久运行一次，这在一定程度上取决于您的应用被使用的频率。
后台任务不会在模拟器中执行。

Android

您的任务最多有 10 分钟来执行工作，但为了保持跨平台兼容性，您应将工作限制在最多 30 秒内。
重复执行的后台任务的最小间隔至少为 15 分钟。与 iOS 类似，您请求的任何间隔可能不会精确命中——实际执行时间受操作系统电池优化和其他启发式算法的制约。

checkPermissions()

checkPermissions() => any

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

返回： any

始于： 1.0.0

requestPermissions(...)

requestPermissions(options: RequestPermissionOptions) => any

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

参数	类型
`options`	`RequestPermissionOptions`

返回： any

始于： 1.0.0

dispatchEvent(...)

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

向配置的 runner 发送一个事件。

参数	类型
`options`	`DispatchEventOptions`

返回： any

始于： 1.0.0

接口

PermissionStatus

属性	类型
`geolocation`	`PermissionState`
`notifications`	`PermissionState`

RequestPermissionOptions

属性	类型
`apis`	`{}`

DispatchEventOptions

属性	类型	描述	始于
`label`	`string`	要发送事件的 runner 标签	1.0.0
`event`	`string`	已注册的事件监听器名称。	1.0.0
`details`	`{ [key: string]: any; }`

类型别名

PermissionState

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

API

'geolocation' | 'notifications'

Capacitor API

接口

CapacitorDevice

获取设备信息，例如网络连接状态和电池状态。

属性	类型	描述	始于
`getBatteryStatus`	`() => BatteryStatus`	获取设备的当前电池状态。	1.0.0
`getNetworkStatus`	`() => NetworkStatus`	获取设备的当前网络状态。	1.0.0

BatteryStatus

属性	类型
`batteryLevel`	`number`
`isCharging`	`boolean`

NetworkStatus

属性	类型
`connected`	`boolean`
`connectionType`	`string`

CapacitorKV

一个简单的字符串键值存储，在 iOS 上由 UserDefaults 支持，在 Android 上由 Shared Preferences 支持。

属性	类型	描述	始于
`set`	`(key: string, value: string) => void`	使用给定键设置字符串值。	1.0.0
`get`	`(key: string) => { value: string; }`	获取给定键的字符串值。	1.0.0
`remove`	`(key: string) => void`	删除给定键的值。	1.0.0

CapacitorNotifications

发送基本的本地通知。

属性	类型	描述	始于
`schedule`	`(options: {}) => void`	调度一个本地通知	1.0.0
`setBadge`	`(options: NotificationBadgeOptions) => void`	设置应用角标数量	2.0.0
`clearBadge`	`() => void`	清除应用角标数量	2.0.0

NotificationScheduleOptions

属性	类型	描述	始于
`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+，使用已配置所需声音的 channelId。如果未找到声音文件（即空字符串或错误名称），将使用系统默认通知声音。如果未提供，在 Android 上会产生默认声音，在 iOS 上则无声。	1.0.0
`actionTypeId`	`string`	为此通知关联一个操作类型。	1.0.0
`threadIdentifier`	`string`	用于对多个通知进行分组。在 `UNMutableNotificationContent` 上设置 `threadIdentifier`。仅适用于 iOS。	1.0.0
`summaryArgument`	`string`	此通知添加到类别摘要格式字符串的字符串。在 `UNMutableNotificationContent` 上设置 `summaryArgument`。仅适用于 iOS。	1.0.0
`group`	`string`	用于对多个通知进行分组。使用提供的值在 `NotificationCompat.Builder` 上调用 `setGroup()`。仅适用于 Android。	1.0.0
`groupSummary`	`string`	如果为 true，此通知将成为通知组的摘要。使用提供的值在 `NotificationCompat.Builder` 上调用 `setGroupSummary()`。仅在使用 `group` 时适用于 Android。	1.0.0
`extra`	`any`	设置要存储在此通知中的额外数据。	1.0.0
`ongoing`	`boolean`	如果为 true，通知不能被滑动清除。使用提供的值在 `NotificationCompat.Builder` 上调用 `setOngoing()`。仅适用于 Android。	1.0.0
`autoCancel`	`boolean`	如果为 true，用户点击通知时通知被取消。使用提供的值在 `NotificationCompat.Builder` 上调用 `setAutoCancel()`。仅适用于 Android。	1.0.0
`largeBody`	`string`	设置用于大文本通知样式的多行文本块。	1.0.0
`summaryText`	`string`	用于在收件箱和大文本通知样式中设置摘要文本详情。仅适用于 Android。	1.0.0
`smallIcon`	`string`	设置自定义状态栏图标。如果设置，将覆盖 Capacitor 配置中的 `smallIcon` 选项。图标应放在应用的 `res/drawable` 文件夹中。此选项的值应为 drawable 资源 ID，即不带扩展名的文件名。仅适用于 Android。	1.0.0
`largeIcon`	`string`	设置通知的大图标。图标应放在应用的 `res/drawable` 文件夹中。此选项的值应为 drawable 资源 ID，即不带扩展名的文件名。仅适用于 Android。	1.0.0
`channelId`	`string`	指定通知应发送到的频道。如果具有给定名称的频道不存在，则通知不会触发。如果未提供，将使用默认频道。使用提供的值在 `NotificationCompat.Builder` 上调用 `setChannelId()`。仅适用于 Android 26+。	1.0.0

NotificationBadgeOptions

属性	类型	描述	始于
`count`	`number`	要设置的应用角标数量。	2.0.0
`notificationTitle`	`string`	关联角标通知的必需标题。仅适用于 Android。	2.0.0
`notificationSubtitle`	`string`	关联角标通知的副标题。仅适用于 Android。	2.0.0

CapacitorGeolocation

获取设备位置信息。

属性	类型	描述	始于
`getCurrentPosition`	`() => GetCurrentPositionResult`	获取设备的最后已知位置	1.0.0

GetCurrentPositionResult

属性	类型	描述	始于
`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

CapacitorWatch

与配对此应用的手表交互。

sendMessage、transferUserInfo 和 updateApplicationContext 是 WCSession 委托方法的原始路由，但目前在使用 CapacitorWatch 的手表应用中没有效果。如果开发原生手表应用作为 Capacitor 应用的配套应用，可以使用它们。

属性	类型	描述
`sendMessage`	`(options: []) => void`	使用 sendMessage() WCSession 委托方法向手表发送消息。对 CapacitorWatch 手表应用没有效果。
`transferUserInfo`	`(options: []) => void`	使用 transferUserInfo() WCSession 委托方法向手表发送信息。对 CapacitorWatch 手表应用没有效果。
`updateApplicationContext`	`(options: []) => void`	使用 updateApplicationContext() WCSession 委托方法更新手表上的应用上下文。对 CapacitorWatch 手表应用没有效果。
`isReachable`	`boolean`	检查配套手表是否可到达。
`updateWatchUI`	`(options: { watchUI: string; }) => void`	用手表上指定的内容替换当前 UI。
`updateWatchData`	`(options: { data: { [key: string]: string; }; }) => void`	更新手表用于在文本和按钮字段中显示变量的数据。

CapacitorApp

属性	类型
`getState`	`() => AppState`
`getInfo`	`() => AppInfo`

AppState

属性	类型	描述	始于
`isActive`	`boolean`	应用是否处于活动状态。	1.0.0

AppInfo

属性	类型	描述	始于
`name`	`string`	应用的名称。	1.0.0
`id`	`string`	应用的标识符。在 iOS 上是 Bundle Identifier。在 Android 上是 Application ID。	1.0.0
`build`	`string`	构建版本。在 iOS 上是 CFBundleVersion。在 Android 上是 versionCode。	1.0.0
`version`	`string`	应用版本。在 iOS 上是 CFBundleShortVersionString。在 Android 上是包的 versionName。	1.0.0

安装​

iOS​

Geolocation（地理位置）​

Android​

Geolocation（地理位置）​

Local Notifications（本地通知）​

关于 Background Runner​

使用 Background Runner​

Runner JS 文件示例​

配置 Background Runner​

示例​

JavaScript API​

Runner 生命周期​

Android 电池优化​

后台任务的限制​

iOS​

Android​

API​

checkPermissions()​

requestPermissions(...)​

dispatchEvent(...)​

接口​

PermissionStatus​

RequestPermissionOptions​

DispatchEventOptions​

类型别名​

PermissionState​

API​

Capacitor API​

接口​

CapacitorDevice​

BatteryStatus​

NetworkStatus​

CapacitorKV​

CapacitorNotifications​

NotificationScheduleOptions​

NotificationBadgeOptions​

CapacitorGeolocation​

GetCurrentPositionResult​

CapacitorWatch​

CapacitorApp​

AppState​

AppInfo​

Contents

安装

iOS

Geolocation（地理位置）

Android

Geolocation（地理位置）

Local Notifications（本地通知）

关于 Background Runner

使用 Background Runner

Runner JS 文件示例

配置 Background Runner

示例

JavaScript API

Runner 生命周期

Android 电池优化

后台任务的限制

iOS

Android

API

checkPermissions()

requestPermissions(...)

dispatchEvent(...)

接口

PermissionStatus

RequestPermissionOptions

DispatchEventOptions

类型别名

PermissionState

API

Capacitor API

接口

CapacitorDevice

BatteryStatus

NetworkStatus

CapacitorKV

CapacitorNotifications

NotificationScheduleOptions

NotificationBadgeOptions

CapacitorGeolocation

GetCurrentPositionResult

CapacitorWatch

CapacitorApp

AppState

AppInfo