后台地理位置服务 Capacitor 插件

使用 @capgo/background-geolocation

为 iOS 和 Android 上的 Capacitor 应用提供精准的后台定位和原生地理围栏。用它持续推送精确的位置更新、监控圆形区域，并将地理围栏进入/退出事件传递到 JavaScript 或你的后端。

安装

bun add @capgo/background-geolocation
bunx cap sync

插件暴露的内容

• start - 持续获取精准的前台或后台位置更新。
• stop - 停止当前的位置追踪。
• openSettings - 当用户需要修复位置权限时，打开原生设置。
• setPlannedRoute - 当用户偏离预设路线时，播放原生提示音。
• setupGeofencing - 配置原生地理围栏默认值及可选的 transition webhook 投递。
• addGeofence - 监控 iOS 或 Android 的圆形地理围栏区域。
• removeGeofence / removeAllGeofences - 停止监控单个或所有已注册的区域。
• getMonitoredGeofences - 列出已监控的区域标识符。
• geofenceTransition listener - 在 App 处于活跃状态时接收进入和退出事件。
• geofenceError listener - 将原生监控错误与 transition 事件分开处理。

用法示例

start

调用此方法以开始监听设备位置变化。该方法返回一个 Promise 以表示调用已完成。每当获取到新位置或调用出错时，都会触发回调。请勿依赖 Promise 的 rejection 来处理位置错误。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.start(
  {
    backgroundMessage: "App is using your location in the background",
    backgroundTitle: "Location Service",
    requestPermissions: true,
    stale: false,
    distanceFilter: 10
  },
  (location, error) => {
    if (error) {
      console.error('Location error:', error);
      return;
    }
    if (location) {
      console.log('New location:', location.latitude, location.longitude);
    }
  }
);

stop

停止位置更新。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.stop();

openSettings

打开设备的定位设置页面。适用于引导用户开启定位服务或调整权限。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

// Direct user to location settings
await BackgroundGeolocation.openSettings();

setPlannedRoute

当用户偏离预定路线时播放音频文件。应使用此功能来播放声音（在原生端支持后台播放）。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setPlannedRoute({
  soundFile: "notification.mp3",
  route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});

原生地理围栏

利用 iOS 和 Android 的原生地理围栏（geofences）来监控商店、工作现场、配送区域、校园或签到区域。添加 HTTP 或 HTTPS url 以便在 WebView 挂起时，让原生 code POST 传输 payload。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofences',
  notifyOnEntry: true,
  notifyOnExit: true,
  payload: { userId: '123' },
});

await BackgroundGeolocation.addGeofence({
  identifier: 'warehouse',
  latitude: 40.7128,
  longitude: -74.006,
  radius: 200,
});

const listener = await BackgroundGeolocation.addListener(
  'geofenceTransition',
  (event) => console.log(event.identifier, event.transition),
);

const errorListener = await BackgroundGeolocation.addListener(
  'geofenceError',
  (event) => console.error(event.identifier, event.message),
);

await BackgroundGeolocation.removeGeofence({ identifier: 'warehouse' });
await listener.remove();
await errorListener.remove();

在 Android 上，仅在需要后台地理围栏功能时，才需在 app manifest 中添加 ACCESS_BACKGROUND_LOCATION 到你的 app manifest 中：

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

完整参考

• GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
• 文档: /docs/plugins/background-geolocation/

继续阅读 使用 @capgo/background-geolocation

如果你正在使用 使用 @capgo/background-geolocation 要规划原生插件工作，请将其与 @capgo/background-geolocation 了解 @capgo/background-geolocation 的实现细节， 快速入门 有关“入门指南”中的实现细节， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 有关 Capgo 开发的 Capacitor 插件的实现细节，以及 添加或更新插件 有关添加或更新插件的实现细节。