# @capgo/capacitor-ibeacon 中文文档

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

版本：8\.1\.48
npm 元数据更新时间：2026-11-09T07:21:48.335Z
中文译文更新时间：2026-11-09T08:34:14.302Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：157 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-10-26T17:39:54.012Z
- 最新版本发布：2026-11-09T07:21:48.025Z
- 近 30 天下载量：3541（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 56 个）

## 中文简介

capacitor iBeacon 插件 - 近距离探测和信标区域监测

## 安装

```sh
npm install @capgo/capacitor-ibeacon
```

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

## README

# 电容器

从您的 Capacitor app 中检测到附近的iBeacons : 监视背景区域,距离范围信标,并在 iOS 上作为信标广告该设备. 为零售,场地和室内相近而建.

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

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

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

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

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

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

## 主要特点

-   **区域监测**数字 : `startMonitoringForRegion()` 与 `didEnterRegion`, (中文(简体) ), `didExitRegion` 财务报告和审定财务报表 `didDetermineStateForRegion` 事件.
-   **径行**数字 : `startRangingBeaconsInRegion()` 发射 `didRangeBeacons` 还有附近的信标.
-   **IOS上的广告**数字 : `startAdvertising()` 财务报告和审定财务报表 `stopAdvertising()` 将设备变成iBeacon.
-   **Android 的背景扫描**数字 : `enableBackgroundMode()`, (中文(简体) ), `setBackgroundScanPeriod()` 财务报告和审定财务报表 `enableARMAFilter()` 为更稳的距离.
-   **权限和状态**: 地点授权请求, `isBluetoothEnabled()` 财务报告和审定财务报表 `isRangingAvailable()`。 。 。 .
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. iOS使用Core Lace,Android使用AltBeacon库. 在网上不可用.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/ibeacon/ 页面存档备份,存于互联网档案馆](https://capgo.app/docs/plugins/ibeacon/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页: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/capacitor-ibeacon` plugin in my project.
```

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

```bash
npm install @capgo/capacitor-ibeacon
npx cap sync
```

## 配置

### iOS系统

#### 步骤1: 配置信息. plist

将以下密钥添加到您的 `ios/App/App/Info.plist` 文件 :

```xml
<!-- Required: Location permission for beacon detection -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to detect nearby beacons</string>

<!-- Required for background monitoring: Always authorization -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access to monitor beacons in the background</string>

<!-- Required: Bluetooth usage (iOS 13+) -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to detect nearby beacons</string>

<!-- Required for iOS 12 and earlier -->
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to detect and advertise as beacons</string>

<!-- Required for background beacon monitoring -->
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>bluetooth-central</string>
</array>
```

#### 步骤2: 在 Xcode 中启用能力

1.  在 Xcode 中打开您的工程 : `ios/App/App.xcworkspace`
2.  选择您的应用目标
3.  转到“ 签名能力” 标签
4.  点击"+能力"并添加"背景模式"
5.  检查以下选项:
    -   ✅ **地点更新** (用于背景信标监测)
    -   ✅ **使用蓝牙LE附件** (信标检测所需)

#### 需要权限

-   **使用时**: 前景信标测距和监测
-   **永远**: 用于背景信标监测(当应用程序不活动时检测信标)
-   **蓝牙**: 当信标使用 CoreLocation 时, 在 iOS 13+ 上自动授予

> **说明**:插件使用CoreLocation进行信标检测,它内部处理蓝牙扫描. 只有当您的应用程序也使用Core Bluetooth用于其他目的(例如广告作为信标)时,才需要直接蓝牙权限.

### 机器人

插件自动包含所有所需的权限和依赖性. 不需要手动配置 .

**权限包括:**

-   位置权限( 细、 粗、 背景)
-   蓝牙权限(对Android QQ11有适当的遗产支持,对Android 12+有现代权限)
-   背景信标扫描的前景服务权限
-   完成持续监测许可

**依赖性包括:**

-   AltBeacon Android灯塔图书馆(2.21.2)

**重要内容:** 您仍然需要使用插件的授权方法在运行时请求权限(见下文API部分).

## API 密码

所有方法都可通过 `CapacitorIbeacon` 对象 :

```typescript
import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
```

### 启动监测格式( 选项: 灯塔格式)

开始监视信标区域 进入/出行区域时触发事件.

```typescript
await CapacitorIbeacon.startMonitoringForRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  major: 1,
  minor: 2
});
```

### 停止监测监管( 选项: 灯塔监管)

停止监视信标区域.

```typescript
await CapacitorIbeacon.stopMonitoringForRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
```

### 启动 Ranging Beacons InRegion( 选项: 灯塔Region)

在一个区域开始测距信标。 提供连续距离更新.

```typescript
await CapacitorIbeacon.startRangingBeaconsInRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
```

### 停止 Ranging Beacons InRegion( 选项: 灯塔Region)

在一个区域停止测距信标.

```typescript
await CapacitorIbeacon.stopRangingBeaconsInRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
```

### 开始广告( 选项: 灯塔广告选项)

开始将该设备作为iBeacon(仅iOS)进行广告.

```typescript
await CapacitorIbeacon.startAdvertising({
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  major: 1,
  minor: 2,
  identifier: 'MyBeacon'
});
```

### 停止广告 ()

停止将该设备作为iBeacon(仅iOS)进行广告.

```typescript
await CapacitorIbeacon.stopAdvertising();
```

### 使用授权时请求 ()

请求"何时使用"定位授权.

```typescript
const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
console.log('Authorization status:', status);
```

### 总是认证 ()

请求"永远"定位授权(背景监测需要).

```typescript
const { status } = await CapacitorIbeacon.requestAlwaysAuthorization();
console.log('Authorization status:', status);
```

### 获取认证状态( C)

获取当前位置授权状态 .

```typescript
const { status } = await CapacitorIbeacon.getAuthorizationStatus();
// status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use'
```

### 是蓝牙可读( )

检查设备是否启用了蓝牙 .

```typescript
const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
if (!enabled) {
  console.log('Please enable Bluetooth');
}
```

### 朗金- 瓦依勒( )

检查设备是否有测距 .

```typescript
const { available } = await CapacitorIbeacon.isRangingAvailable();
```

### 启用ARMAFilter( 选项 : {已启用: 布尔} )

启用 ARMA 过滤以进行远程计算( 只有Android) .

```typescript
await CapacitorIbeacon.enableARMAFilter({ enabled: true });
```

### Android 背景扫描

Android 8+需要一个前景服务,以使蓝牙扫描在背景中保持活性. 您可以选择一次, 插件会自动 当应用程序在前景和背景之间移动时切换背景扫描.

```typescript
// Enable background scanning globally (Android only)
await CapacitorIbeacon.enableBackgroundMode({ enabled: true });

// Or opt in per call
await CapacitorIbeacon.startMonitoringForRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  enableBackgroundMode: true,
});
```

您也可以通过 Capacitor 配置来启用 :

```typescript
// capacitor.config.ts
plugins: {
  CapacitorIbeacon: {
    enableBackgroundMode: true,
  },
}
```

## 活动

使用 Capacitor 事件系统收听信标事件:

```typescript
import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
import { PluginListenerHandle } from '@capacitor/core';

// Listen for ranging events
const rangingListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didRangeBeacons',
  (data) => {
    console.log('Beacons detected:', data.beacons);
    data.beacons.forEach(beacon => {
      console.log(`Beacon: ${beacon.uuid}, Distance: ${beacon.accuracy}m, Proximity: ${beacon.proximity}`);
    });
  }
);

// Listen for region enter events
const enterListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didEnterRegion',
  (data) => {
    console.log('Entered region:', data.region.identifier);
  }
);

// Listen for region exit events
const exitListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didExitRegion',
  (data) => {
    console.log('Exited region:', data.region.identifier);
  }
);

// Listen for region state changes
const stateListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didDetermineStateForRegion',
  (data) => {
    console.log(`Region ${data.region.identifier}: ${data.state}`);
  }
);

// Clean up listeners when done
rangingListener.remove();
enterListener.remove();
exitListener.remove();
stateListener.remove();
```

## 完整示例

```typescript
import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';

// Define your beacon region
const beaconRegion = {
  identifier: 'MyStore',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  major: 1
};

async function setupBeaconMonitoring() {
  try {
    // Request permission
    const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
    
    if (status !== 'authorized_when_in_use' && status !== 'authorized_always') {
      console.error('Location permission denied');
      return;
    }

    // Check if Bluetooth is enabled
    const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
    if (!enabled) {
      console.error('Bluetooth is not enabled');
      return;
    }

    // Set up event listeners
    await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
      console.log('Welcome! You entered:', data.region.identifier);
      // Show welcome notification or trigger action
    });

    await CapacitorIbeacon.addListener('didExitRegion', (data) => {
      console.log('Goodbye! You left:', data.region.identifier);
    });

    await CapacitorIbeacon.addListener('didRangeBeacons', (data) => {
      data.beacons.forEach(beacon => {
        console.log(`Beacon ${beacon.minor}: ${beacon.proximity} (${beacon.accuracy.toFixed(2)}m)`);
      });
    });

    // Start monitoring
    await CapacitorIbeacon.startMonitoringForRegion(beaconRegion);
    console.log('Started monitoring for beacons');

    // Start ranging for distance updates
    await CapacitorIbeacon.startRangingBeaconsInRegion(beaconRegion);
    console.log('Started ranging beacons');

  } catch (error) {
    console.error('Error setting up beacon monitoring:', error);
  }
}

// Call the setup function
setupBeaconMonitoring();
```

## 类型脚本

### 灯塔注册

```typescript
interface BeaconRegion {
  identifier: string;
  uuid: string;
  major?: number;
  minor?: number;
  notifyEntryStateOnDisplay?: boolean;
}
```

### 灯塔

```typescript
interface Beacon {
  uuid: string;
  major: number;
  minor: number;
  rssi: number;
  proximity: 'immediate' | 'near' | 'far' | 'unknown';
  accuracy: number;
}
```

### 灯塔广告选项

```typescript
interface BeaconAdvertisingOptions {
  uuid: string;
  major: number;
  minor: number;
  identifier: string;
  measuredPower?: number;
}
```

## 近似值

-   **即时**:非常靠近信标(几厘米以内)
-   **相邻**: 相对靠近信标(几米之内)
-   **远**: 离信标更远(10+米)
-   **不详**: 距离无法确定

## 重要说明

1.  **iOS 背景监测**:要监视背景中的信标,需要:
    
    -   “总是”地点授权(`requestAlwaysAuthorization()`(中文(简体) )
    -   Xcode 中启用的背景模式能力
    -   `UIBackgroundModes` 两者 `location` 财务报告和审定财务报表 `bluetooth-central` 在Info.plist中输入
2.  **iOS Xcode 配置**: 仅添加Info.plist 密钥是不够的. 你个 **必须** 启用 Xcode 的背景模式能力(见上文配置部分)。 这是最常见的设置问题.
    
3.  **Android 图书馆**: 此插件包括了自动的 AltBeacon Android Beacon 库 (2.21.2).
    
4.  **电池使用量**:连续信标测距可以消耗大量的电池. 考虑使用监测(这更能节能),并只在需要时才开始测距.
    
5.  **UUID 格式**: UUID 必须是标准格式: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`
    
6.  **主要/次要价值**:这些是用于在UUID内识别特定信标的可选的16位无符号整数(0-65535).
    
7.  **权限**: 启动信标操作前总是请求和检查权限.
    

## 解决问题

### iOS问题

**“未检测到的 Beacons”或“无法工作”**

1.  **验证Info.plist 配置**数字 :
    
    -   确保所有所需的密钥都存在(见上文配置部分)
    -   检查权限描述是否有意义而非空
2.  **在 Xcode 中启用背景模式**数字 :
    
    -   这是一个常见的问题 - 您的 MUST 启用 Xcode 中的能力, 而不仅仅是添加 Info. plist 密钥
    -   打开 `ios/App/App.xcworkspace` xcode 编码
    -   选择目标 ~ “ 签名和能力 ”
    -   添加“ 背景模式” 能力
    -   请检查access-date=中的日期值 (帮助) "Location update"和"Uss Bluetooth LE 配件"
3.  **请求适当授权**数字 :
    
    ```typescript
    // For foreground detection only
    await CapacitorIbeacon.requestWhenInUseAuthorization();
    
    // For background monitoring (required for region enter/exit events when app is closed)
    await CapacitorIbeacon.requestAlwaysAuthorization();
    ```
    
4.  **选中蓝牙已启用**数字 :
    
    ```typescript
    const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
    if (!enabled) {
      // Prompt user to enable Bluetooth in Settings
    }
    ```
    
5.  **核查授权状况**数字 :
    
    ```typescript
    const { status } = await CapacitorIbeacon.getAuthorizationStatus();
    console.log('Auth status:', status);
    // Should be 'authorized_when_in_use' or 'authorized_always'
    ```
    
6.  **检查设备兼容性**数字 :
    
    -   iBeacon需要iOS 7.0+ (英语)
    -   一些功能需要特定的iOS版本(例如背景范围)
    -   使用 `isRangingAvailable()` 检查设备支持

**"没有事件开火"或"增加听力不起作用"**

-   确保设置听众 **在此之前** 开始监测/范围:
    
    ```typescript
    // Set up listeners first
    await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
      console.log('Entered:', data.region.identifier);
    });
    
    // Then start monitoring
    await CapacitorIbeacon.startMonitoringForRegion({
      identifier: 'MyRegion',
      uuid: 'YOUR-UUID-HERE'
    });
    ```
    

**背景监测不起作用**

-   需要“ 永远” 授权 : `requestAlwaysAuthorization()`
-   一定是这样 `UIBackgroundModes` 与 `location` 财务报告和审定财务报表 `bluetooth-central` 在Info.plist中输入
-   必须在 Xcode 中启用背景模式能力
-   iOS 可能会节流背景扫描以保存电池

### 安卓问题

见上文配置中的Android权限部分。 多数Android问题涉及:

-   不请求运行时间权限
-   在Android 8+上缺少前景服务
-   蓝牙未启用

详细的Android故障排除,请检查AltBeacon图书馆文档.

## 贷项

此插件的灵感来自 [索多瓦-插图-贝贝康](https://github.com/petermetz/cordova-plugin-ibeacon) 并改编为Capacitor.

## 许可证

麻省理工学院

## 捐款

见 [捐款额](https://npmcn.com/package/%40capgo/capacitor-ibeacon/CONTRIBUTING.md) 关于如何为此插件贡献的详细信息.

## 常见问题

### @capgo/capacitor-ibeacon 是什么？

capacitor iBeacon 插件 - 近距离探测和信标区域监测

### 如何安装 @capgo/capacitor-ibeacon？

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

### @capgo/capacitor-ibeacon 支持 TypeScript 吗？

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

### @capgo/capacitor-ibeacon 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-ibeacon 可以商用吗？

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

### @capgo/capacitor-ibeacon 的下载量有多少？

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

### @capgo/capacitor-ibeacon 还在维护吗？

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