跳到主要内容
版本：v8

@capacitor/background-runner

后台运行器提供了一个基于事件的独立 JavaScript 环境,用于在 Web 视图之外执行您的 JavaScript 代码。

安装​

npm install @capacitor/background-runner
npx cap sync

后台运行器支持各种需要用户预先授权的设备 API。

iOS​

在 iOS 上,您必须启用后台模式能力。

在 Xcode 中启用后台模式能力

添加后,您必须至少启用后台获取和后台处理模式,以启用注册和调度后台任务的能力。

如果您将使用地理位置或推送通知,请分别启用位置更新或远程通知。

在 Xcode 中配置后台模式

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

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

请在iOS 指南中阅读关于配置Info.plist,以获取有关在 Xcode 中设置 iOS 权限的更多信息。

请确保在插件配置的label字段中使用与BGTaskSchedulerPermittedIdentifiers相同的 ID(例如 "com.example.background.task")。

启用后台模式能力后,将以下内容添加到应用程序的AppDelegate.swift中:

在文件顶部,import Capacitor下添加:

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

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

    return true
}

要允许后台运行器处理远程通知,请添加以下内容:

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 (Privacy - Location Always Usage Description)
  • NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)

Android​

将以下行插入到android/app/build.gradle中:

...

repositories {
    flatDir{
        dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
+		dirs '/main/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 权限的更多信息。

关于后台运行器​

在构建复杂应用程序的过程中,有时需要在应用程序不在前台时执行工作。标准 Capacitor 应用程序的挑战在于,当这些后台事件发生时,webview 不可用,需要您编写原生代码来处理这些事件。这就是后台运行器插件发挥作用的地方。

后台运行器使编写 JavaScript 代码来处理原生后台事件变得容易。您只需要创建运行器 JavaScript 文件并定义您的配置,然后后台运行器插件将自动配置和调度原生后台任务,该任务将根据您的配置和平台规则执行。无需修改 UI 代码。

使用后台运行器​

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

运行器 JS 文件示例​

addEventListener('myCustomEvent', (resolve, reject, args) => {
  console.log('在此处执行某些操作以更新系统');
  resolve();
});

addEventListener('myCustomEventWithReturnData', (resolve, reject, args) => {
  try {
    console.log('接受此数据: ' + 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('收到静默推送通知');

    CapacitorNotifications.schedule([
      {
        id: 100,
        title: '企业后台运行器',
        body: '收到静默推送通知',
      },
    ]);

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

在运行器调用的每个事件处理程序中调用resolve() \ reject()是必需的。如果不这样做,可能会导致您的运行器在应用程序处于后台时调用事件时被操作系统终止。如果应用程序处于前台,对dispatchEvent的异步调用可能无法解析。

有关使用后台运行器的更多真实示例,请查看后台运行器测试应用程序。

配置后台运行器​

在加载时,后台运行器将自动注册一个后台任务,该任务将在应用程序进入后台时调度并运行。

属性类型描述自
labelstring运行器的名称,用于日志记录。1.0.0
srcstring运行器 JavaScript 文件的路径,相对于应用程序包。1.0.0
eventstring操作系统执行后台任务时将调用的事件的名称。1.0.0
repeatboolean后台任务是否应基于interval中设置的间隔重复。1.0.0
intervalnumber应用程序进入后台后开始后台任务的分钟数。如果repeat为 true,这也指定每次执行之间的分钟数。1.0.0
autoStartboolean在应用程序加载时自动注册和调度后台任务。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​

后台运行器不在浏览器或 Web 视图中执行您的 JavaScript 代码,因此您可能习惯的典型 Web API 可能不可用。这包括 DOM API 以及与应用程序 DOM 交互的能力。

以下是后台运行器中提供的可用 Web API 列表:

除了标准 Web API 之外,后台运行器还支持许多自定义 Capacitor API自定义 API,这些 API 公开相关的移动设备功能

运行器生命周期​

目前,运行器旨在在应用程序处于后台时执行周期性的工作突发,或在应用程序处于前台时在与 UI 分离的线程中执行异步工作。因此,运行器的生命周期不长。状态不会在运行器中的事件调用之间维护。每次调用dispatchEvent()都会创建一个新上下文,在该上下文中加载和执行运行器代码,一旦调用resolve()或reject(),上下文就会被销毁。

Android 电池优化​

某些 Android 供应商提供内置的电池优化设置,超出了 stock Android 的范围。其中一些优化必须由最终用户禁用,以便您的后台任务正常工作。

访问不要杀死我的应用程序!以获取有关受影响的制造商以及用户调整设置所需步骤的更多信息。

后台任务的限制​

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

iOS​

  • 每次调用任务时,您有大约 30 秒的运行时间,然后必须调用completed(),否则任务将被终止。
  • 虽然您可以设置一个间隔来定义任务在应用程序进入后台后运行的时间或运行频率,但这不能保证。iOS 将最终决定您任务运行的时间和频率,这部分取决于您使用应用程序的频率。
  • 后台任务不在模拟器中执行。

Android​

  • 您的任务最多有 10 分钟的时间来执行工作,但为了保持您的任务跨平台兼容,您应该将工作限制在最多 30 秒。
  • 重复的后台任务的最小间隔至少为 15 分钟。与 iOS 类似,您请求的任何间隔可能不会完全命中 - 实际执行时间取决于操作系统的电池优化和其他启发式方法。

API​

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

向配置的运行器分发事件。

参数类型
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

Interfaces​

PermissionStatus​

属性类型
geolocation
PermissionState
notifications
PermissionState

RequestPermissionOptions​

属性类型
apis{}

DispatchEventOptions​

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

NotificationActionEvent​

属性类型
actionTypeIdstring
notificationIdnumber

PluginListenerHandle​

属性类型
remove() => any

Type Aliases​

PermissionState​

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

API​

'geolocation' | 'notifications'

Capacitor API​

Interfaces​

CapacitorDevice​

获取有关设备的信息,例如网络连接和电池状态。

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

BatteryStatus​

属性类型
batteryLevelnumber
isChargingboolean

NetworkStatus​

属性类型
connectedboolean
connectionTypestring

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​

属性类型描述自
idnumber通知标识符。在 Android 上,它是一个 32 位整数。因此,该值应介于 -2147483648 和 2147483647 之间(含)。1.0.0
titlestring通知的标题。1.0.0
bodystring通知的正文,显示在标题下方。1.0.0
scheduleAtDate发送此通知的日期。1.0.0
soundstring显示此通知时要播放的音频文件名。在文件名中包含文件扩展名。在 iOS 上,文件应在应用程序包中。在 Android 上,文件应在 res/raw 文件夹中。推荐的格式是.wav,因为 iOS 和 Android 都支持。仅适用于 iOS 和 Android < 26。对于 Android 26+,使用配置了所需声音的频道的 channelId。如果找不到声音文件(即空字符串或错误的名称),将使用默认系统通知声音。如果未提供,它将在 Android 上产生默认声音,在 iOS 上不产生声音。1.0.0
actionTypeIdstring将操作类型与此通知关联。1.0.0
threadIdentifierstring用于对多个通知进行分组。在UNMutableNotificationContent上设置threadIdentifier。仅适用于 iOS。1.0.0
summaryArgumentstring此通知添加到类别的摘要格式字符串的字符串。在UNMutableNotificationContent上设置summaryArgument。仅适用于 iOS。1.0.0
groupstring用于对多个通知进行分组。使用提供的值在NotificationCompat.Builder上调用setGroup()。仅适用于 Android。1.0.0
groupSummarystring如果为 true,此通知将成为一组通知的摘要。使用提供的值在NotificationCompat.Builder上调用setGroupSummary()。仅适用于使用group的 Android。1.0.0
extraany设置要在此通知中存储的额外数据。1.0.0
ongoingboolean如果为 true,则无法滑动关闭通知。使用提供的值在NotificationCompat.Builder上调用setOngoing()。仅适用于 Android。1.0.0
autoCancelboolean如果为 true,则当用户单击通知时取消通知。使用提供的值在NotificationCompat.Builder上调用setAutoCancel()。仅适用于 Android。1.0.0
largeBodystring设置多行文本块以大文本通知样式显示。1.0.0
summaryTextstring用于在收件箱和大文本通知样式中设置摘要文本详细信息。仅适用于 Android。1.0.0
smallIconstring设置自定义状态栏图标。如果设置,这将覆盖 Capacitor 配置中的smallIcon选项。图标应放置在应用程序的res/drawable文件夹中。此选项的值应该是可绘制资源 ID,即不带扩展名的文件名。仅适用于 Android。1.0.0
largeIconstring为通知设置大图标。图标应放置在应用程序的res/drawable文件夹中。此选项的值应该是可绘制资源 ID,即不带扩展名的文件名。仅适用于 Android。1.0.0
channelIdstring指定应在哪个频道上传递通知。如果具有给定名称的频道不存在,则通知不会触发。如果未提供,它将使用默认频道。使用提供的值在NotificationCompat.Builder上调用setChannelId()。仅适用于 Android 26+。1.0.0

NotificationBadgeOptions​

属性类型描述自
countnumber要在应用程序徽章计数上设置的数字。2.0.0
notificationTitlestring关联徽章计数通知的必需标题。仅适用于 Android。2.0.0
notificationSubtitlestring关联徽章计数通知的副标题。仅适用于 Android。2.0.0

CapacitorGeolocation​

获取访问设备位置信息的权限。

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

GetCurrentPositionResult​

属性类型描述自
latitudenumber十进制度数1.0.0
longitudenumber十进制度数1.0.0
accuracynumber纬度和经度坐标的精度级别(米)1.0.0
altitudenumber | null用户所在的海拔(如果可用)1.0.0
altitudeAccuracynumber | null海拔坐标的精度级别(米,如果可用)。适用于所有 iOS 版本和 Android 8.0+。1.0.0
speednumber | null用户移动的速度(如果可用)1.0.0
headingnumber | null用户面向的方向(如果可用)1.0.0

CapacitorWatch​

与此应用程序配对的手表交互

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

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

CapacitorApp​

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

AppState​

属性类型描述自
isActiveboolean应用程序是否处于活动状态。1.0.0

AppInfo​

属性类型描述自
namestring应用程序的名称。1.0.0
idstring应用程序的标识符。在 iOS 上,它是 Bundle Identifier。在 Android 上,它是 Application ID1.0.0
buildstring构建版本。在 iOS 上,它是 CFBundleVersion。在 Android 上,它是 versionCode。1.0.0
versionstring应用程序版本。在 iOS 上,它是 CFBundleShortVersionString。在 Android 上,它是包的 versionName。1.0.0

Contents

编辑此页