@capacitor/background-runner

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

安装

npm install @capacitor/background-runner
npx cap sync

Background Runner 支持 various device APIs，在使用之前必须获得用户授权。

iOS

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

添加该功能后，至少要启用 Background fetch 和 Background processing 模式，以启用注册和安排后台任务的能力。

如果将使用地理位置或推送通知，分别启用 Location updates 或 Remote notifications。

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

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（隐私 - 使用时使用位置描述）

有关在Xcode中设置iOS权限的更多信息，请参阅iOS指南中的配置Info.plist

Android

地理位置

该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" />

前两个权限请求获取精确定位和粗略定位的位置数据，最后一行是可选的，但如果有必要使App运行需要GPS，则必须添加。您可以省略这一行，但请注意，这可能意味着您的App安装在缺少GPS硬件的设备上。

本地通知

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

在Android 12及以下版本中，不会弹出提示，而是直接返回授权。

从Android 12开始，除非在您的AndroidManifest.xml中添加此权限，否则计划中的通知不会精确。

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

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

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

使用后台运行器

后台运行器是一个基于事件的 JavaScript 环境，它会向你在 capacitor.config.ts 文件中指定的 JavaScript 运行器文件中发出事件。如果运行器发现与进来事件对应的处理程序，它将执行事件处理程序，一旦调用（或如果操作系统强制终止你的进程）resolve() 或 reject()，它将关闭。

示例运行器 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() 是 必需的。如果不能这样做，如果事件在应用处于后台时被调用，操作系统可能会终止你的运行器。如果应用处于前台，异步调用 dispatchEvent 可能无法解析。

配置后台运行器

后台运行器在加载时会自动注册一个后台任务，一旦应用被放到后台，它就会被安排运行。此行为的设置定义在您的 capacitor.config.ts 文件中

const config: CapacitorConfig = {
  plugins: {
    BackgroundRunner: {
      label: 'com.example.background.task',
      src: 'background.js',
      event: 'myCustomEvent',
      repeat: true,
      interval: 2,
      autoStart: false,
    },
  },
};

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对象尚未支持
  • 仅在选项对象中支持 method、headers 和 body

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

Runner生命周期

目前，运行器是为了在您的应用处于后台时执行周期性工作而设计的，或者在应用处于前台时在独立的线程上执行异步工作。因此，运行器的生命周期并不长。运行器事件之间的状态不会被维持。每次调用 dispatchEvent() 都会在一个新的上下文中加载和执行您的运行器代码，一旦调用 resolve() 或 reject()，上下文就会被销毁。

Android电池优化

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

访问不要杀死我的应用！获取有关受影响制造商和用户调整设置的步骤的更多信息。

后台任务限制

在移动操作系统上无法运行持久的、始终运行的后台服务。由于iOS和Android为减少电池和数据处理所强加的限制，后台任务在设计实现时必须牢记其受到的各种限制。

iOS

• 您的任务调用每次运行大约30秒，在此之后您必须调用completed()或任务将被终止。
• 虽然您可以设置一个间隔定义任务在应用处于后台时运行的时间，或者运行频率，但这不是保证的。iOS将决定任务最终何时以及多久运行一次，部分取决于您应用的使用频率。

Android

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

API

• checkPermissions()
• requestPermissions(...)
• dispatchEvent(...)
• 接口
• 类型别名

checkPermissions()

checkPermissions() => any

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

返回值: 任意类型

自从 1.0.0

requestPermissions(...)

requestPermissions(options: RequestPermissionOptions) => any

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

返回值: 任意类型

自从 1.0.0

dispatchEvent(...)

dispatchEvent(options: DispatchEventOptions) => any

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

返回值: 任意类型

自从 1.0.0

接口

权限状态

请求权限选项

派发事件选项

类型别名

权限状态

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

API

'地理位置' | '通知'

Capacitor API

接口

CapacitorDevice

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

BatteryStatus

网络状态

CapacitorKV

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

CapacitorNotifications

发送基本的本地通知。

NotificationScheduleOptions

CapacitorGeolocation

获取设备地理位置信息。

GetCurrentPositionResult