版本：v8

@capacitor/background-runner

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

安装

npm install @capacitor/background-runner
npx cap sync

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

iOS

在 iOS 上，你必须启用 Background Modes（后台模式）功能。

在 Xcode 中启用后台模式功能

添加完成后，你至少需要启用 Background fetch 和 Background processing 模式，才能注册和调度你的后台任务。

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

在 Xcode 中配置后台模式

你还需要在 Info.plist 文件中添加以下条目：

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

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

确保你在插件配置的 label 字段中使用与 BGTaskSchedulerPermittedIdentifiers 相同的标识符（例如 "com.example.background.task"）。

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

地理定位

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

NSLocationAlwaysUsageDescription（隐私 - 始终使用位置描述）
NSLocationWhenInUseUsageDescription（隐私 - 使用时位置描述）

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。

地理定位

此 API 需要在你的 AndroidManifest.xml 中添加以下权限：

<!-- 地理定位 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()。

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

从 Android 12 开始，计划的（定时）通知将不会精确执行，除非在 AndroidManifest.xml 中添加此权限：

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

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

阅读关于在 Android 指南中设置权限的更多信息，以了解在 Android 上设置权限的详情。

关于 Background Runner

在构建复杂应用的过程中，有时需要在应用不在前台时执行工作。标准 Capacitor 应用的挑战在于，当这些后台事件发生时，Web 视图不可用，因此你需要编写原生代码来处理这些事件。这就是 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 测试应用。

配置 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 不在浏览器或 Web 视图中执行你的 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。

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 类似，你请求的任何间隔可能不会精确命中——实际执行时间受操作系统电池优化和其他启发式算法的影响。

API

checkPermissions()
requestPermissions(...)
dispatchEvent(...)
addListener('backgroundRunnerNotificationReceived', ...)
removeNotificationListeners()
Interfaces
Type Aliases

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

addListener('backgroundRunnerNotificationReceived', ...)

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

添加一个通知动作的监听器。

参数	类型
`eventName`	`'backgroundRunnerNotificationReceived'`
`listenerFunc`	`(event: NotificationActionEvent) => void`

返回值： any

自： 2.1.1

removeNotificationListeners()

removeNotificationListeners() => any

移除此插件的通知动作监听器。

返回值： any

自： 2.1.1

接口

PermissionStatus

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

RequestPermissionOptions

属性	类型
`apis`	`{}`

DispatchEventOptions

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

NotificationActionEvent

属性	类型
`actionTypeId`	`string`
`notificationId`	`number`

PluginListenerHandle

属性	类型
`remove`	`() => 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` 文件夹中。此选项的值应为可绘制资源的 ID，即不带扩展名的文件名。仅适用于 Android。	1.0.0
`largeIcon`	`string`	设置通知的大图标。图标应放置在应用的 `res/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 上为 package 的 versionName。	1.0.0

安装​

iOS​

地理定位​

Android​

地理定位​

本地通知​

关于 Background Runner​

使用 Background Runner​

示例 Runner JS 文件​

配置 Background Runner​

示例​

JavaScript API​

Runner 生命周期​

Android 电池优化​

后台任务的限制​

iOS​

Android​

API​

checkPermissions()​

requestPermissions(...)​

dispatchEvent(...)​

addListener('backgroundRunnerNotificationReceived', ...)​

removeNotificationListeners()​

接口​

PermissionStatus​

RequestPermissionOptions​

DispatchEventOptions​

NotificationActionEvent​

PluginListenerHandle​

类型别名​

PermissionState​

API​

Capacitor API​

接口​

CapacitorDevice​

BatteryStatus​

NetworkStatus​

CapacitorKV​

CapacitorNotifications​

NotificationScheduleOptions​

NotificationBadgeOptions​

CapacitorGeolocation​

GetCurrentPositionResult​

CapacitorWatch​

CapacitorApp​

AppState​

AppInfo​

Contents

安装

iOS

地理定位

Android

地理定位

本地通知

关于 Background Runner

使用 Background Runner

示例 Runner JS 文件

配置 Background Runner

示例

JavaScript API

Runner 生命周期

Android 电池优化

后台任务的限制

iOS

Android

API

checkPermissions()

requestPermissions(...)

dispatchEvent(...)

addListener('backgroundRunnerNotificationReceived', ...)

removeNotificationListeners()

接口

PermissionStatus

RequestPermissionOptions

DispatchEventOptions

NotificationActionEvent

PluginListenerHandle

类型别名

PermissionState

API

Capacitor API

接口

CapacitorDevice

BatteryStatus

NetworkStatus

CapacitorKV

CapacitorNotifications

NotificationScheduleOptions

NotificationBadgeOptions

CapacitorGeolocation

GetCurrentPositionResult

CapacitorWatch

CapacitorApp

AppState

AppInfo