# @capgo/background-geolocation 中文文档

规范地址：https://npmcn.com/package/%40capgo/background-geolocation/

版本：8\.5\.2
npm 元数据更新时间：2026-11-02T13:28:49.278Z
中文译文更新时间：2026-11-09T02:16:02.189Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/background-geolocation
原文对照：https://npmcn.com/package/%40capgo/background-geolocation/?lang=original
项目主页：https://capgo.app/docs/plugins/background-geolocation/
源码仓库：https://github.com/Cap-go/capacitor-background-geolocation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：560 kB，47 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-07-28T20:33:10.792Z
- 最新版本发布：2026-11-02T13:28:48.965Z
- 近 30 天下载量：170899（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 69 个）

## 中文简介

IOS和Android上的 Capacitor apps 精确背景地理学和本土地理学.

## 安装

```sh
npm install @capgo/background-geolocation
```

也可以使用：`pnpm add @capgo/background-geolocation`、`yarn add @capgo/background-geolocation`、`bun add @capgo/background-geolocation`

## README

# 背景位置

跟踪背景中的精确位置,并监控iOS和Android上的本土地缘. 用于快递,健身和外地服务应用,持续跟踪屏幕关闭后.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-background-geolocation)](https://capgo.app/?ref=plugin_background_geolocation)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_background_geolocation)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_background_geolocation) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/background-geolocation` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/ 背地- 地理定位到我的 Capacitor app 并把它连接起来。"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_background_geolocation) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_background_geolocation)

![@capgo/background-geolocation for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-background-geolocation/main/assets/github-social-preview.png)

## 主要特点

-   **背景跟踪**数字 : `start()` 包含选项的流位置更新, 如 `distanceFilter` 和一个背景通知信息, `stop()` 结束他们.
-   **原生上传**: 向您发送位置 `url` 从本地代码,并更改苍蝇上的标题 `updateHeaders()`。 。 。 .
-   **地平线**数字 : `addGeofence()`, (中文(简体) ), `removeGeofence()`, (中文(简体) ), `removeAllGeofences()` 财务报告和审定财务报表 `getMonitoredGeofences()`,与 `geofenceTransition` 财务报告和审定财务报表 `geofenceError` 事件.
-   **路线指导**数字 : `setPlannedRoute()` 当用户离开计划路线时播放声音.
-   **权限**数字 : `checkPermissions()`, (中文(简体) ), `requestPermissions()` 财务报告和审定财务报表 `openSettings()`。 。 。 .
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. iOS使用Core Location,Android使用Google Play服务定位并具有前瞻服务.

IOS和Android上用于精确背景位置跟踪和本土地取地取地的Capacitor插件. 用它来流出精确位置更新,监视循环地缘区域,在JavaScript中反应出出出入出事件,而POST地缘过渡在WebView被暂停时在本土进行.

## 特征

-   没有付费许可证的准确前景和背景地理定位.
-   在iOS和Android上进行原生地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地.
-   进入和退出事件通过 `geofenceTransition` 当应用程序还活着.
-   当WebView被暂停时, 本地的 Webhook 交付用于地缘过渡 .
-   用于开发和基于浏览器的测试的网络回落.

## 此插件的历史

有趣的是,这个插件有很多历史. 最初的解决办法来自: [晶体管软](https://github.com/transistorsoft) 是一个伟大的软件,我([哈雷尔姆](https://github.com/HarelM)如果符合您的需要,鼓励使用.  
我尝试了它,并理解它优先 电池寿命比精度, 这不适合我的徒步应用.  
有一个非常好的叉子 **毛龙85** 我很高兴能帮你维持它.  
但在某些时候, **毛龙85** 停止对GitHub上的消息作出回应,没有人可以继续维护.  
我希望Mauron85安全无事.

于是我创建了叉子并开始维持它 [这里](https://github.com/HaylLtd/cordova-background-geolocation-plugin)。 。 。 .  
半个多世纪以来,它对我很有用 但我觉得由于它的历史 特征 和虫子修复 很难维持.  
我也觉得由于它的复杂性,在引入新的特征方面存在着障碍.

于是我开始探索 减少这种复杂程度需要什么 同时,我羡慕到 [`@capacitor-community/background-geolocation`](https://github.com/capacitor-community/background-geolocation) 没错.  
我选择了两个世界中最好的:尝试减少原Cordova插件中的代码库,并在Capacitor插件上加入一些强力.

所以我才留着这个.  
我希望你会喜欢的!

## 插件比较

Capacitor apps中常用的三个主要背景-地心插件的简短比较.

| 插件 | 准确性 | 背景情况 | 地平线 | 本地过渡 POST | 定价 |
| --- | --- | --- | --- | --- | --- |
| `@capacitor-community/background-geolocation` (社区) | 不准确 | 对 | 没有 | 没有 | 免费 |
| `@capgo/background-geolocation` (此插件) | 准确 | 对 | iOS和Android 软件 | 是,用于地缘过渡 | 免费 |
| 晶体管软件(原作) | 准确 | 对 | 对 | 是, 内置的 HTTP 上传器 | 已支付 |

注释:

-   社区插件是轻量级的并持续在后台工作,但已知其准确性低于下方的选项.
-   这个 Cap-go 插件旨在提供准确的定位修正,可靠的背景操作,以及本土的地峡出入口处理,而不需要付费许可证.
-   当iOS或Android为区域过渡唤醒了本地代码,但Capacitor WebView没有运行时,原生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生.
-   Transistorsoft的插件是一个成熟而准确的解决方案,其中也包括了更宽的HTTP上传器. 这是一种商业产品,需要领取全额使用许可证.

## 使用量

```javascript
import { BackgroundGeolocation } from "@capgo/background-geolocation";

BackgroundGeolocation.start(
    {
        backgroundMessage: "Cancel to prevent battery drain.",
        backgroundTitle: "Tracking You.",
        requestPermissions: true,
        stale: false,
        distanceFilter: 50
    },
    (location, error) => {
        if (error) {
            if (error.code === "NOT_AUTHORIZED") {
                if (window.confirm(
                    "This app needs your location, " +
                    "but does not have permission.\n\n" +
                    "Open settings now?"
                )) {
                    // It can be useful to direct the user to their device's
                    // settings when location permissions have been denied. The
                    // plugin provides the 'openSettings' method to do exactly
                    // this.
                    BackgroundGeolocation.openSettings();
                }
            }
            return console.error(error);
        }
        return console.log(location);
    }
).then(() => {
    // When location updates are no longer needed, the plugin should be stopped by calling
    BackgroundGeolocation.stop();
});

// Set a planned route to get a notification sound when a new location arrives and it's not on the route:
        
BackgroundGeolocation.setPlannedRoute({soundFile: "assets/myFile.mp3", route: [[1,2], [3,4]], distance: 30 });
```

## 原生地缘

需要商店,工作站点,送货区,校园或报到区等轻量级位置界限时,使用本地地圈. 该插件在应用程序活动时,对地理栅栏进行本土监测并释放出JavaScript事件. Android背景投递是可选的,只有在你选择加入时才会请求.

```javascript
import { BackgroundGeolocation } from "@capgo/background-geolocation";

// Geofencing can notify JavaScript while the app is alive.
await BackgroundGeolocation.setupGeofencing({
    notifyOnEntry: true,
    notifyOnExit: true,
    payload: { userId: "123" }
});

await BackgroundGeolocation.addGeofence({
    identifier: "office",
    latitude: 37.33182,
    longitude: -122.03118,
    radius: 150
});

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

await BackgroundGeolocation.removeGeofence({ identifier: "office" });
handle.remove();
```

### Android背景地圈权限

插件不添加 `ACCESS_BACKGROUND_LOCATION` 除非您明确选择加入,否则不请求。 只有使用前景定位的应用程序可以省略此权限.

仅在应用程序处于背景时需要Android地缘变换时才选择:

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

```javascript
await BackgroundGeolocation.setupGeofencing({
    url: "https://api.example.com/geofences",
    backgroundLocation: true
});
```

```javascript
// If you just want the current location, try something like this. The longer
// the timeout, the more accurate the guess will be. I wouldn't go below about 100ms.
function guessLocation(callback, timeout) {
    let last_location;
    BackgroundGeolocation.start(
        {
            requestPermissions: false,
            stale: true
        },
        (location) => {
            last_location = location || undefined;
        }
    ).then(() => {
        setTimeout(() => {
            callback(last_location);
            BackgroundGeolocation.stop();
        }, timeout);
    });
}
```

## 位置日志

召回只运行在 WebView 运行时, 和一个 POST 地址 `url` 请求失败时放弃。 与 `locationLog` 上,每个位置也被添加到设备上的文件。 由原生代码所写出,因此它记录的时间与跟踪运行的时间一样长,它能活下来的应用重启并重新出道.

```javascript
await BackgroundGeolocation.start(
    {
        backgroundMessage: "Sharing your location.",
        locationLog: true
    },
    (location, error) => console.log(location, error)
);

// Later, when the app returns to the foreground or the network is back
const { entries } = await BackgroundGeolocation.getLocationLog();
if (entries.length > 0) {
    // Use the entries, for example upload them, then remove the ones that were read
    await BackgroundGeolocation.clearLocationLog({ upToId: entries[entries.length - 1].id });
}
```

每个条目都是 `Location` 带有 `id`ID只向上,所以与 `upToId` 从不删除读取后到达的位置。 日志可维持 `locationLogMaxEntries` 地点,以及 `limit` 财务报告和审定财务报表 `afterId` 以页读取. 它从设备备份中被放出,所以在一个被恢复的设备上,它开始是空的,而ID又从1开始.

### 可选 SQLite 位置日志

默认构建将日志存储在滚动文件中,而不编译SQLite代码. 要选择 SQLite 后端( 每个条目的 POST 状态, 和 原 PR # 92 的 型号相同), 请设置为 `capacitor.config` 运行 `npx cap sync`数字 :

```typescript
plugins: {
  BackgroundGeolocation: {
    locationLogSqlite: true
  }
}
```

那就通过 `locationLogSqlite: true` 内 `start()` 合并 `locationLog: true`。如果您请求 `locationLogSqlite` 不让它进入 `capacitor.config`, (中文(简体) ), `start()` 以明显的错误拒绝.

在iOS上, `npx cap sync` 切换可选选项 `ios/SqliteLocationLog` 并添加这些源加 `sqlite3` 目标 `Package.swift` (默认退出不编译或链接 SQLite). 在Android上,同步集 `backgroundGeolocation.locationLogSqlite.include` 内 `android/gradle.properties`。 。 。 .

要确认默认依赖性图不包括 SQLite : `cd android && ./gradlew :dependencies --configuration releaseCompileClasspath` (无) `sqliteEnabled` 来源)和在 `Package.swift` 编号 : `CapgoBackgroundGeolocation.podspec` sQLite 线条在同步启用前会保留注释 .

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/背地-地心定位/](https://capgo.app/docs/plugins/background-geolocation/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/background-geolocation` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

此插件支持 Capacitor v8 :

| 电容 | 插件 |
| --- | --- |
| 页:1 | 页:1 |

```sh
bun add @capgo/background-geolocation
bunx cap update
```

### iOS系统

添加以下密钥到 `Info.plist.`数字 :

```xml
<dict>
  ...
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>We need to track your location</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>We need to track your location while your device is locked.</string>
  <key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>
  ...
</dict>
```

### 机器人

设置 `android.useLegacyBridge` 选项到 `true` 在您的电容配置中。 这样可以防止位置更新在背景5分钟后停止. 见 [https://capcorjs.com/docs/config (中文(简体) )](https://capacitorjs.com/docs/config) 财务报告和审定财务报表 [https://github.com/concessor-community/background-geolocation/issues/89 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/capacitor-community/background-geolocation/issues/89)。 。 。 .

在Android 13+上,应用程序需要 `POST_NOTIFICATIONS` 运行时允许显示持续通知,告知用户其位置正在背景中使用。 此运行时间许可是在位置许可获得后请求的.

对于Android 10+上的背景地平面,应用程序也需要 `ACCESS_BACKGROUND_LOCATION` 财务报告和审定财务报表 `backgroundLocation: true` 内 `setupGeofencing()`。Android可能要求用户在授予前景位置后从系统设置中批准;使用 `openSettings()` 如果拒绝批准。 离开 `backgroundLocation` 未设置或 `false` 如果您的应用程序没有获得Android背景位置的 Google Play 批准 .

如果您的应用程序实时向服务器转发位置更新, 请注意在背景 Android 5分钟后, 从 WebView 启动的 HTTP 请求将会被节制 。 解决方案是使用本地的 HTTP 插件, 如 [电容Http](https://capacitorjs.com/docs/apis/http)。见 [https://github.com/concessor-community/后地地-地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地](https://github.com/capacitor-community/background-geolocation/issues/14)。 。 。 .

Android 的特定配置可以在 `strings.xml`数字 :

```xml
<resources>
    <!--
        The channel name for the background notification. This will be visible
        when the user presses & holds the notification. It defaults to
        "Background Tracking".
    -->
    <string name="capacitor_background_geolocation_notification_channel_name">
        Background Tracking
    </string>

    <!--
        The icon to use for the background notification. Note the absence of a
        leading "@". It defaults to "mipmap/ic_launcher", the app's launch icon.

        If a raster image is used to generate the icon (as opposed to a vector
        image), it must have a transparent background. To make sure your image
        is compatible, select "Notification Icons" as the Icon Type when
        creating the image asset in Android Studio.

        An incompatible image asset will cause the notification to misbehave in
        a few telling ways, even if the icon appears correctly:

          - The notification may be dismissable by the user when it should not
            be.
          - Tapping the notification may open the settings, not the app.
          - The notification text may be incorrect.
    -->
    <string name="capacitor_background_geolocation_notification_icon">
        drawable/ic_tracking
    </string>

    <!--
        The color of the notification as a string parseable by
        android.graphics.Color.parseColor. Optional.
    -->
    <string name="capacitor_background_geolocation_notification_color">
        yellow
    </string>
</resources>

```

## API 密码

-   [`start(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-start)
-   [`stop()`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-stop)
-   [`updateHeaders(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-updateheaders)
-   [`openSettings()`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-opensettings)
-   [`setPlannedRoute(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-setplannedroute)
-   [`setupGeofencing(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-setupgeofencing)
-   [`addGeofence(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-addgeofence)
-   [`removeGeofence(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-removegeofence)
-   [`removeAllGeofences()`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-removeallgeofences)
-   [`getMonitoredGeofences()`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-getmonitoredgeofences)
-   [`getLocationLog(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-getlocationlog)
-   [`clearLocationLog(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-clearlocationlog)
-   [`addListener('geofenceTransition', ...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-addlistenergeofencetransition-)
-   [`addListener('geofenceError', ...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-addlistenergeofenceerror-)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-checkpermissions)
-   [`requestPermissions(...)`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-requestpermissions)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/background-geolocation/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/background-geolocation/#readme-type-aliases)

背景地理定位功能的主要插件接口. 提供管理位置更新和访问设备设置的方法.

### 启动(...)

```typescript
start(options: StartOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<void>
```

要开始监听设备位置的变化,请使用这种方法. 一个承诺被退回 表示它完成了电话。 每次新地点都会呼叫回调 ,或如果调用此方法时出错。 不要依赖承诺拒绝这一点.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[StartOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions)` | 配置选项 |
| **`callback`** | `(position?: [Location](https://npmcn.com/package/%40capgo/background-geolocation/#readme-location), error?: [CallbackError](https://npmcn.com/package/%40capgo/background-geolocation/#readme-callbackerror)) => void` | 当新位置可用或发生错误时引用的回调函数 |

**自:** 7.0.9 联合国

* * *

### 停止( )

```typescript
stop() => Promise<void>
```

停止位置更新 .

**自:** 7.0.9 联合国

* * *

### 更新页眉(...)

```typescript
updateHeaders(options: UpdateHeadersOptions) => Promise<void>
```

替换本地 POST 使用的 HTTP 头头而不重新启动跟踪 .

当访问符过期时使用此选项 `url` 正在发送. 信头适用于运行中的位置监视器和在 这些特性已配置 `url`。 。 。 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[UpdateHeadersOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-updateheadersoptions)` | 替换信头 |

**自:** 8.3.3 国家

* * *

### 打开设置( C)

```typescript
openSettings() => Promise<void>
```

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

**自:** 7.0.0 (单位:千美元)

* * *

### 设置 PlannedRoute (...)

```typescript
setPlannedRoute(options: SetPlannedRouteOptions) => Promise<void>
```

当用户偏离计划路线时播放声音文件. 这应该用来演奏一个声音(在背景中也是,只用于本土).

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SetPlannedRouteOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-setplannedrouteoptions)` | 设置计划路线和声音文件的选项 |

**自:** 7.0.11 联合国

* * *

### 设置Geofencing(...)

```typescript
setupGeofencing(options: GeofenceSetupOptions) => Promise<void>
```

配置本土地缘过渡处理.

当您需要默认的出/出设置时, 请在添加地理栅栏前先调用此选项 或本地背景 POST 。 安卓背景 POST 需要 `backgroundLocation: true`。 。 。 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[GeofenceSetupOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-geofencesetupoptions)` | 地栅配置选项 |

**自:** 8.0.30 联合国

* * *

### 添加Geofence(...) 语句

```typescript
addGeofence(options: AddGeofenceOptions) => Promise<void>
```

开始监测圆形本土地缘.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[AddGeofenceOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-addgeofenceoptions)` | 地理围栏区域选项 |

**自:** 8.0.30 联合国

* * *

### 删除 Geofence (...)

```typescript
removeGeofence(options: RemoveGeofenceOptions) => Promise<void>
```

停止监视一个地峡.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[RemoveGeofenceOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-removegeofenceoptions)` | 地缘特征 |

**自:** 8.0.30 联合国

* * *

### 删除全部邮件( )

```typescript
removeAllGeofences() => Promise<void>
```

停止监视此插件注册的每一个地缘 .

**自:** 8.0.30 联合国

* * *

### 获得监测

```typescript
getMonitoredGeofences() => Promise<MonitoredGeofencesResult>
```

列出此插件目前监控的地缘识别符 .

**回返情况:** `Promise<[MonitoredGeofencesResult](https://npmcn.com/package/%40capgo/background-geolocation/#readme-monitoredgeofencesresult)>`

**自:** 8.0.30 联合国

* * *

### 获取LocationLog(...)

```typescript
getLocationLog(options?: GetLocationLogOptions | undefined) => Promise<LocationLogResult>
```

读取由 QQlink 保存的位置 [启动选项. locationLog](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions),无论或 没有跟踪正在运行 。 网络上没有任何东西 所以结果是 那边是空的.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[GetLocationLogOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-getlocationlogoptions)` | 期望条目返回 |

**回返情况:** `Promise<[LocationLogResult](https://npmcn.com/package/%40capgo/background-geolocation/#readme-locationlogresult)>`

**自:** 8.5.0 (中文(简体) )

* * *

### 清除LocationLog(...)

```typescript
clearLocationLog(options?: ClearLocationLogOptions | undefined) => Promise<void>
```

从位置日志中删除条目, 例如当它们已经存在时 读取或上传.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ClearLocationLogOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-clearlocationlogoptions)` | 要删除的条目 |

**自:** 8.5.0 (中文(简体) )

* * *

### 添加倾听器( “ geofence Transition ” ,...)

```typescript
addListener(eventName: 'geofenceTransition', listenerFunc: (event: GeofenceTransitionEvent) => void) => Promise<PluginListenerHandle>
```

在WebView活着时聆听地峡的入出过渡.

土著 `url` 通过配置 `setupGeofencing` 用于 提供背景安全服务.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'geofenceTransition'` |
| **`listenerFunc`** | `(event: [GeofenceTransitionEvent](https://npmcn.com/package/%40capgo/background-geolocation/#readme-geofencetransitionevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/background-geolocation/#readme-pluginlistenerhandle)>`

**自:** 8.0.30 联合国

* * *

### 添加倾听器( 'geofence Error', ...)

```typescript
addListener(eventName: 'geofenceError', listenerFunc: (event: GeofenceErrorEvent) => void) => Promise<PluginListenerHandle>
```

在WebView活着时监听原生地缘栅监测出错.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'geofenceError'` |
| **`listenerFunc`** | `(event: [GeofenceErrorEvent](https://npmcn.com/package/%40capgo/background-geolocation/#readme-geofenceerrorevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/background-geolocation/#readme-pluginlistenerhandle)>`

**自:** 8.0.30 联合国

* * *

### 检查( )

```typescript
checkPermissions() => Promise<BackgroundGeolocationPermissionStatus>
```

在不提示或副作用的情况下读取当前位置授权 .

IOS 地图 `CLAuthorizationStatus` 这样你就可以永远区分 在使用App. On Android时,报告前景位置, `ACCESS_BACKGROUND_LOCATION`,以及相关情况下的通知许可.

**回返情况:** `Promise<[BackgroundGeolocationPermissionStatus](https://npmcn.com/package/%40capgo/background-geolocation/#readme-backgroundgeolocationpermissionstatus)>`

**自:** 8.0.43 (中文(简体) )

* * *

### 请求(...)

```typescript
requestPermissions(options?: RequestBackgroundGeolocationPermissionsOptions | undefined) => Promise<BackgroundGeolocationPermissionStatus>
```

向用户请求与位置相关的权限.

Ưμ㼯A 设置屏幕中的状态。 只有在用户选择加入时才调用 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[RequestBackgroundGeolocationPermissionsOptions](https://npmcn.com/package/%40capgo/background-geolocation/#readme-requestbackgroundgeolocationpermissionsoptions)` | 请求权限的可选子集 |

**回返情况:** `Promise<[BackgroundGeolocationPermissionStatus](https://npmcn.com/package/%40capgo/background-geolocation/#readme-backgroundgeolocationpermissionstatus)>`

**自:** 8.0.43 (中文(简体) )

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本

**回返情况:** `Promise<{ version: string; }>`

* * *

### 接口

#### 开始选项

位置更新配置的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`backgroundMessage`** | `string` | 如果定义了"背景信息"选项,插件将提供位置更新,无论该应用程序位于背景还是前景. 如果它没有定义,则只在前地中保证位置更新. 这两个平台都是这样。 关于Android,必须显示通知,以继续接收背景位置更新. 这一备选案文具体规定了该通知的案文. |  | 7.0.9 联合国 |
| **`backgroundTitle`** | `string` | 上述通知的标题. | `"Using your location"` | 7.0.9 联合国 |
| **`requestPermissions`** | `boolean` | 如果用户尚未获得许可, 是否应当自动向用户请求权限 . | `true` | 7.0.9 联合国 |
| **`stale`** | `boolean` | 如果"真",在设备获得GPS固定装置的同时,可以发送被扭曲的位置. 你负责检查"时间"财产. 如果"虚假",地点保证更新. | `false` | 7.0.9 联合国 |
| **`distanceFilter`** | `number` | 设备在启动新位置更新前必须移动的米数距离 。 用于过滤出小移动并减少更新数量. 一个非零值在设备固定时压制更新(例如停放的车辆). 使用QQ链接 [启动选项.minIntervalms](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions)} 当你需要更低的更新率时, 但仍然需要周期点而不移动 . | `0` | 7.0.9 联合国 |
| **`url`** | `string` | 设定后,每个位置更新都会通过POSTing作为JSON直接从本地代码发送到这个URL,与JavaScript回调并行. 请求体匹配 [`Location`](https://npmcn.com/package/%40capgo/background-geolocation/#readme-location) 对象,加额外 `"source": "native"` 字段,这样服务器除了JavaScript层转发的更新之外,还可以告诉本地 POSTs. 本地发送不依赖于WebView. 在Android上,前景服务被系统活下来并重新启动(Android)`START_STICKY`)),所以位置 POST 即使在用户将应用程序从最近列表中刷去并杀死其进程之后,仍然继续. 在iOS上,只要系统保持了应用程序运行,位置就被本地化地POST;iOS本身在用户终止应用程序时停止了位置更新(一个OS限制——iOS没有相当于Android可重启的前地服务). 交付是最佳的:没有磁盘上排队,也没有自动重试. 失败的 POST 已登录并丢弃 。 片状网络可以延迟飞行请求,但点数并不贯穿整个过程死亡。 设置QQlink [启动选项. locationLog](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions)保持设备的每一个位置. |  | 8.2.0 (中文(简体) ) |
| **`headers`** | `[Record](https://npmcn.com/package/%40capgo/background-geolocation/#readme-record)<string, string>` | 由 QQlink 描述的本地 POST 的额外 HTTP 头 [启动选项.url](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions)} 忽略了何时 `url` 未设置。 在Android上,这些信头被坚持 `url` 因此粘性服务重启可以继续认证. 给此路径选择一个狭义的、长寿的符号, 或者在证书旋转时调用 QQlink 背景Geographic Plugin.updateheaders 。 在iOS定位头留在内存中用于跟踪会话. |  | 8.3.3 国家 |
| **`minIntervalMs`** | `number` | 本地位置 POST 之间的最小间隔, 以毫秒计 . `0` 或未设置保留当前行为(每个提供者更新). 作为Android应用 `requestLocationUpdates` 间隔(咨询)以及作为紧接两个平台上每个本地POST之前的硬门. 比上次寄出的要长的一分仍然通过(更新较晚,不是更快). 注:非零链接 [开始选项。 距离筛选](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions)} 在设备处于静止状态时压制更新, 因此它不能代替一个时间间隔, 当您仍然需要定期停放的车辆心跳时 . | `0` | 8.3.3 国家 |
| **`networkFallback`** | `boolean` | 只有Android - 对iOS没有影响. 是否还原到 `NETWORK_PROVIDER` (基于单元格/Wi-Fi的位置) `GPS_PROVIDER` 最近还没有解决 GPS可以在应用背景,屏幕被锁定,或者设备有弱的天空能见度(室内,密集的城市地区)时长时间地保持安静;网络倒置会用收缩器来填补这些缺口,但更可靠地交付,固定. GPS总是优先使用:只有在GPS沉默了20多秒之后,才使用网络固定,如果报告的准确度低于300米或未报告,则放弃。 默认为 `false`,因此,除非您选择加入,否则现有的仅限GPS精度特性不变. | `false` | 8.5.0 (中文(简体) ) |
| **`locationLog`** | `boolean` | 是否将每个位置都添加到设备上的日志文件中 。 文件来自本地代码,所以在WebView被暂停时继续录制,并生存下来 `stop()`,应用程序重新启动并重播。 它没有设备备份。 使用 QQlink 背景Geographic Plugin.getLocationLog 读取. 跟踪, 和它的日志, 当应用程序关闭时结束, 除了在Android上与QQlink [启动选项.url](https://npmcn.com/package/%40capgo/background-geolocation/#readme-startoptions)准备. | `false` | 8.5.0 (中文(简体) ) |
| **`locationLogMaxEntries`** | `number` | 位置日志上有多少位置。 满后取出最老的第十个. 一个位置大约需要200字节. | `100000` | 8.5.0 (中文(简体) ) |
| **`locationLogSqlite`** | `boolean` | 使用可选 SQLite 位置日志后端而非默认文件日志 。 要求数 `plugins.BackgroundGeolocation.locationLogSqlite: true` 内 `capacitor.config` 财务报告和审定财务报表 `npx cap sync` 故包含本地SQLite代码. | `false` | 8.5.0 (中文(简体) ) |

#### 地点

代表具有各种属性的地理位置. 包含GPS/网络提供者返回的所有标准位置属性.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`latitude`** | `number` | 纬度在度. 范围: -90.0至+90.0 | 7.0.0 (单位:千美元) |
| **`longitude`** | `number` | 以度为经. 范围: -180.0至+180.0 | 7.0.0 (单位:千美元) |
| **`accuracy`** | `number` | 水平不确定性的半径以米为单位,置信度为68%. 数值较低表明位置更准确. | 7.0.0 (单位:千美元) |
| **`altitude`** | `number | null` | 高于海平面的地表(如无则为无效). | 7.0.0 (单位:千美元) |
| **`altitudeAccuracy`** | `number | null` | 垂直不确定性以米为单位,有68%的置信度(或者如果无法获得则无效). | 7.0.0 (单位:千美元) |
| **`simulated`** | `boolean` | `true` 如果位置被软件模拟,而不是GPS。 用于检测正在开发或测试的模拟地点. | 7.0.0 (单位:千美元) |
| **`bearing`** | `number | null` | 从正北偏移以度为单位(或者如果不具备则无效). 范围: 0.0至 360.0 | 7.0.0 (单位:千美元) |
| **`speed`** | `number | null` | 速度以米/ 秒为单位( 如无) . | 7.0.0 (单位:千美元) |
| **`time`** | `number | null` | 时间 地点被生产, 以毫秒计 自unix epoc. 使用此选项检查一个位置在使用 stale 时是否为 stale: true. | 7.0.0 (单位:千美元) |

#### 回拨错误

可能传递到位置开始召回的错误对象 . 以可选错误代码扩展标准出错.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`code`** | `string` | 用于更具体错误处理的可选错误代码 . | 7.0.0 (单位:千美元) |

#### 更新标题选项

QQlink 背景Geogination Plugin.updateheaders 的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`headers`** | `[Record](https://npmcn.com/package/%40capgo/background-geolocation/#readme-record)<string, string>` | 通过配置本地 POST 替换 HTTP 头 `url`适用于活动位置监视器和地理栅栏设置,当这些特征具有 `url`。通过一个空对象来清除自定义标题. | 8.3.3 国家 |

#### 设定已规划的路由选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`soundFile`** | `string` | 要播放的音效文件名称 。 必须是应用的公用文件夹中有效的声音相对路径, 用于网络和本地平台 。 不需要在路径中包含公共文件夹. |  | 7.0.10 国家 |
| **`route`** | `[number, number][]` | 计划中的路线作为经纬和纬相对的阵列. 每对代表路线上的一个点. 这用于定义用户可以遵循的路由. 路由在用户偏离时用于播放声音. |  | 7.0.11 联合国 |
| **`distance`** | `number` | 用户必须偏离计划路线以触发声音的米长. 用于确定用户在播放声音之前距离路由有多远. 如果没有指定,则使用50米的默认值. | `50` | 7.0.11 联合国 |

#### 地栅设置选项

配置本土地缘花序过渡处理选项.

何时 `url` 提供,本地代码可以发送 JSON `POST` 任何时候 被监测区域进入或退出。 Android背景 POST 传送 需求 `backgroundLocation: true`。 。 。 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`url`** | `string` | 接收地缘过渡有效载荷的终点. 在Android上,本地背景的 POST 交付需要 `backgroundLocation: true`。交付是最佳的:没有盘上队列,也没有自动重试。 失败的 POST 已登录并丢弃 . |  | 8.0.30 联合国 |
| **`headers`** | `[Record](https://npmcn.com/package/%40capgo/background-geolocation/#readme-record)<string, string>` | 由 QQlink 描述的本地 POST 的额外 HTTP 头 [GeofenceSetup 选项.url](https://npmcn.com/package/%40capgo/background-geolocation/#readme-geofencesetupoptions)} 忽略了何时 `url` 未设置。 信头坚持使用地栅设置,这样过渡,在进程重启后起火仍然可以认证. 在证书旋转时, 优先使用狭义的缩放符号, 或是调用 QQlink 背景Geographic Plugin.update Headerers . |  | 8.3.3 国家 |
| **`notifyOnEntry`** | `boolean` | 是否应当监测入境过渡. | `true` | 8.0.30 联合国 |
| **`notifyOnExit`** | `boolean` | 是否应当监测退出过渡. | `true` | 8.0.30 联合国 |
| **`payload`** | `[Record](https://npmcn.com/package/%40capgo/background-geolocation/#readme-record)<string, unknown>` | Base JSON有效载荷合并为每次本土过渡POST和收听器活动. |  | 8.0.30 联合国 |
| **`requestPermissions`** | `boolean` | 插件是否应请求地理环境所需的本地位置权限 。 iOS地平线需要总是位置授权. Android地平圈请求默认前景定位. 只有在 `backgroundLocation` 已启用. | `true` | 8.0.30 联合国 |
| **`backgroundLocation`** | `boolean` | Android地圈是否应该选择背景位置权限. 插件不添加 `ACCESS_BACKGROUND_LOCATION` 你的应用清单。 如果您的应用程序没有获得Android背景位置的 Google Play 批准, 请将此禁用 。 仅在添加后启用 `ACCESS_BACKGROUND_LOCATION` 以显示您的应用, 当您需要Android地缘的转换时, 当应用在背景中。 这个选项只影响Android. 低于10的Android版本不要求额外的背景位置运行时间权限,但该选项仍然会开启原生Android背景地缘快递. | `false` | 8.0.34 国家 |

#### 添加

圆形地缘区域.

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`latitude`** | `number` | 区域中心纬度. |  | 8.0.30 联合国 |
| **`longitude`** | `number` | 区域中心经度. |  | 8.0.30 联合国 |
| **`radius`** | `number` | 区域半径为米. | `50` | 8.0.30 联合国 |
| **`identifier`** | `string` | 地峡稳定标识符. |  | 8.0.30 联合国 |
| **`notifyOnEntry`** | `boolean` | 覆盖此区域的设置级别条目设置 . |  | 8.0.30 联合国 |
| **`notifyOnExit`** | `boolean` | 覆盖此区域的设置级别退出设置. |  | 8.0.30 联合国 |
| **`payload`** | `[Record](https://npmcn.com/package/%40capgo/background-geolocation/#readme-record)<string, unknown>` | 特定区域的有效载荷与设置的有效载荷合并. |  | 8.0.30 联合国 |

#### 删除选择

清除受监测地缘的备选办法.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`identifier`** | `string` | 识别器传递到 `addGeofence`。 。 。 . | 8.0.30 联合国 |

#### 监测到的地理成果

列入监测到的地峡时返回结果.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`regions`** | `string[]` | 该插件目前监控的所有地栅的标识符 . | 8.0.30 联合国 |

#### 地点日志

由 QQlink 背景Geographic Plugin. getLocationLog 返回结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`entries`** | `LocationLogEntry[]` | 条目,最古老的第一. | 8.5.0 (中文(简体) ) |

#### 位置日志条目

位置日志中保存的地址 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `number` | 入道证相. 识别器随每个位置而增加,并且永远不会被再利用,所以最后一个读作是QQlink的光标 [GetLocationLog Options.afterId (英语)](https://npmcn.com/package/%40capgo/background-geolocation/#readme-getlocationlogoptions){\\fn方正粗倩简体\\fs12\\an8\\1chffff00\\b0}还有.. [清除LocationLog 选项.uptoId](https://npmcn.com/package/%40capgo/background-geolocation/#readme-clearlocationlogoptions)曰. 师曰. | 8.5.0 (中文(简体) ) |
| **`status`** | `'pending' | 'sent' | 'failed'` | 使用 SQLite 位置日志后端时的发送状态 . | 8.5.0 (中文(简体) ) |
| **`httpStatus`** | `number | null` | 本地 POST 的 HTTP 状态 `status` 实值 `sent` 或者说 `failed`。 。 。 . | 8.5.0 (中文(简体) ) |
| **`error`** | `string | null` | 错误消息当 `status` 实值 `failed`。 。 。 . | 8.5.0 (中文(简体) ) |

#### 访问日志选项

链接背景GeoginPlugin.getLocationLog 的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`afterId`** | `number` | 只返回带有 `id` 比这个大. |  | 8.5.0 (中文(简体) ) |
| **`limit`** | `number` | 要返回的条目最多可达一万个。 再打电话 `afterId` 设置到最后一个 `id` 收到以读取下一页. | `1000` | 8.5.0 (中文(简体) ) |

#### 清除日志选项

QQlink 背景定位 Plugin. ClearLocationLog 的选项 .

| Prop Prop 型 | 说明

## 常见问题

### @capgo/background-geolocation 是什么？

IOS和Android上的 Capacitor apps 精确背景地理学和本土地理学\.

### 如何安装 @capgo/background-geolocation？

在项目目录运行 npm install @capgo/background-geolocation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/background-geolocation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/background-geolocation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/background-geolocation 可以商用吗？

@capgo/background-geolocation 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/background-geolocation 的下载量有多少？

根据 npm 官方下载统计，@capgo/background-geolocation 在 2026/10/09 – 2026/11/07 这 30 天内被下载 170,899 次，日均约 5,697 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/background-geolocation 还在维护吗？

最新版本 8\.5\.2 发布于 2026/11/02（6 天前）；至今共发布 89 个版本，其中过去 12 个月发布了 69 个；首次发布于 2025/07/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。