# @capgo/capacitor-uwb 中文文档

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

版本：8\.0\.9
npm 元数据更新时间：2026-10-15T05:44:03.917Z
中文译文更新时间：2026-11-09T04:14:28.923Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：125 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-01T21:59:12.521Z
- 最新版本发布：2026-10-15T05:44:03.628Z
- 近 30 天下载量：39569（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

IOS和Android上的超宽波段(UWB)的电容插件.

## 安装

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

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

## README

# @ capgo/ 电容- uwb

测量附近设备之间的距离和方向,在你的Capacitor app中标出Ultra-Wideband,用于精确的发现,解锁和相近体验.

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

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

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

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

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

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

## 主要特点

-   **可用性**数字 : `isAvailable()` 检查设备上的 UWB 支持 .
-   **iOS 对等会议**数字 : `getDiscoveryToken()` 财务报告和审定财务报表 `startPeerSession()` 与近接互动.
-   **Android 会话**数字 : `startControllerSession()` 财务报告和审定财务报表 `startControleeSession()` 与Jetpack UWB。 与Jetpack UWB.
-   **搜索事件**数字 : `rangingUpdate` 报告距离和方向, `sessionStateChanged` 跟踪会话.
-   **停下来**数字 : `stopSession()` 结束范围.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 需要 UWB 硬件 。 在网上不可用.

## 为什么这个插件

此插件将本地的 UWB 范围 API 包裹在 iOS 和 Android 上, 因此 Capacitor app 可以 :

-   检查当前设备是否支持 UWB 范围 .
-   以苹果的"相近互动"框架运行iOS上的对等对等范围.
-   使用 Jetpack 在 Android 上运行控制器/控制器测距 `androidx.core.uwb`。 。 。 .
-   通过插件听众接收距离、方向和会话生命周期更新.

在 iOS 上, 同行交换 `NIDiscoveryToken` 值出带,然后调用 `startPeerSession()`。 。 。 . 在Android上,控制器在控制器开始会话前共享范围参数出带.

## 平台支持

| 平台 | 支助 |
| --- | --- |
| iOS系统 | 相距和方向的近距离互动对等点 |
| 机器人 | QQJetpack UWB 控制器/控制器会话(Android 12+,UWB硬件) |
| 网页 | 不详 |

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| v八._。 。 。 ._ | v八._。 。 。 ._ | ✅ |
| v._。 。 。 ._ | v._。 。 。 ._ | 应要求 |
| v6 (英语)._。 。 。 ._ | v6 (英语)._。 。 。 ._ | 应要求 |

> 插件主版本遵循Capacitor主版本.

## 安装

您可以使用我们的 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-uwb` plugin in my project.
```

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

```bash
bun add @capgo/capacitor-uwb
bunx cap sync
```

## 使用量

```typescript
import { CapacitorUwb } from '@capgo/capacitor-uwb';

const availability = await CapacitorUwb.isAvailable();
if (!availability.available) {
  return;
}

await CapacitorUwb.addListener('rangingUpdate', (update) => {
  console.log(update.distanceMeters, update.direction);
});

// iOS: exchange discovery tokens out-of-band, then start ranging
const { discoveryToken } = await CapacitorUwb.getDiscoveryToken();
await CapacitorUwb.startPeerSession({ peerDiscoveryToken: '<peer-token-base64>' });

// Android: controller shares ranging parameters out-of-band
const controller = await CapacitorUwb.startControllerSession();
await CapacitorUwb.startControleeSession({
  rangingParameters: {
    ...controller.rangingParameters,
    peerAddress: controller.localAddress,
  },
});

await CapacitorUwb.stopSession();
```

## 页:1

-   测试真实的UWB硬件. 模拟器和大多数桌面浏览器都不曝光UWB收音机.
-   **iOS: (英语)** 在 Xcode 中添加近接交互能力并设定 `NSNearbyInteractionUsageDescription` 内 `Info.plist`。 。 。 .
-   **机器人:** 插件声明 `android.permission.UWB_RANGING`。在开始会话之前,控制器和控制器之间交换频段参数.
-   **网络 :** `isAvailable()` 返回时 `supported: false`。 。 。 .

完整的设置指南 : [capgo.app/docs/插件/uwb](https://capgo.app/docs/plugins/uwb/)

## 示例应用程序

这个 `example-app/` 文件夹中包含一个小 Vite 演示,用于检查可用性、交换会话参数、聆听测距更新和停止会话.

## API 密码

-   [`isAvailable()`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-isavailable)
-   [`getDiscoveryToken()`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-getdiscoverytoken)
-   [`startPeerSession(...)`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-startpeersession)
-   [`startControllerSession(...)`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-startcontrollersession)
-   [`startControleeSession(...)`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-startcontroleesession)
-   [`stopSession()`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-stopsession)
-   [`addListener('rangingUpdate', ...)`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-addlistenerrangingupdate-)
-   [`addListener('sessionStateChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-addlistenersessionstatechanged-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-removealllisteners)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-type-aliases)

IOS和Android上的超宽波段(UWB)的电容插件.

iOS使用Apple's Nearby Interactive框架进行对等测距. Android使用喷气式包装 `androidx.core.uwb` 用于控制器/控制器会话.

两个平台都要求交换发现符或测距参数 出带(例如蓝牙LE或后端).

### 易读 ()

```typescript
isAvailable() => Promise<UwbAvailabilityResult>
```

请检查UWB是否支持, 设备上是否目前可用 .

**回返情况:** `Promise<[UwbAvailabilityResult](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-uwbavailabilityresult)>`

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

* * *

### 获取 Discovery Token ()

```typescript
getDiscoveryToken() => Promise<DiscoveryTokenResult>
```

在iOS上获取本地的"近相"发现符.

将返回的令牌与对等的带外键共享, 然后调用 `startPeerSession()` 与对等符号.

**回返情况:** `Promise<[DiscoveryTokenResult](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-discoverytokenresult)>`

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

* * *

### 启动PeerSession (...)

```typescript
startPeerSession(options: StartPeerSessionOptions) => Promise<void>
```

在 iOS 上启动一个近接互动对等会话 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartPeerSessionOptions](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-startpeersessionoptions)` |

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

* * *

### 启动控制会议(...)

```typescript
startControllerSession(options?: StartControllerSessionOptions | undefined) => Promise<AndroidControllerSessionResult>
```

启动Android UWB控制器会话并返回可共享参数.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartControllerSessionOptions](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-startcontrollersessionoptions)` |

**回返情况:** `Promise<[AndroidControllerSessionResult](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-androidcontrollersessionresult)>`

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

* * *

### 启动控制会议(...)

```typescript
startControleeSession(options: StartControleeSessionOptions) => Promise<void>
```

用控制器提供的参数启动一个Android UWB控制器会话.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartControleeSessionOptions](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-startcontroleesessionoptions)` |

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

* * *

### 停止会议( )

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

停止活动的 UWB 测距会话 .

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

* * *

### 添加倾听器( 范围更新date )..

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

正在运行的会话中可听到距离和方向的更新 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'rangingUpdate'` |
| **`listenerFunc`** | `(event: [RangingUpdateEvent](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-rangingupdateevent)) => void` |

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

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

* * *

### 添加收听器( “session state Changed' ,...)

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

听听会话周期变化.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'sessionStateChanged'` |
| **`listenerFunc`** | `(event: [SessionStateChangedEvent](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-sessionstatechangedevent)) => void` |

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

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

* * *

### 删除所有收听器( )

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

删除此插件的所有注册听众 .

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

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<PluginVersionResult>
```

获取当前本地插件版本 .

**回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-pluginversionresult)>`

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

* * *

### 接口

#### Uwb 可用性

返回结果 `isAvailable()`。 。 。 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`supported`** | `boolean` | 设备硬件是否支持 UWB 范围 . | 8.0.0 (单位:千美元) |
| **`available`** | `boolean` | UWB目前是否可用并准备进行测距会话. | 8.0.0 (单位:千美元) |
| **`platform`** | `'ios' | 'android' | 'web'` | 由本地或网络执行返回的平台标签 . | 8.0.0 (单位:千美元) |

#### 发现Token结果

返回结果 `getDiscoveryToken()` (原始内容存档于2018-03-31). On iOS.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`discoveryToken`** | `string` | 基础64编码 `NIDiscoveryToken` 与对等频段外共享. | 8.0.0 (单位:千美元) |

#### 开始会话选项

备选方案 `startPeerSession()` (原始内容存档于2018-03-31). On iOS.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`peerDiscoveryToken`** | `string` | Base64 编码端点 `NIDiscoveryToken`。 。 。 . | 8.0.0 (单位:千美元) |
| **`isCameraAssistanceEnabled`** | `boolean` | 支持时是否启用相机辅助(iOS 16+). | 8.0.0 (单位:千美元) |

#### 机器人控制器

在启动 Android 控制器会话时返回参数 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`rangingParameters`** | `[AndroidRangingParameters](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-androidrangingparameters)` | 运行参数可与控制对象共享出带. | 8.0.0 (单位:千美元) |
| **`localAddress`** | `string` | 本地的 UWB 地址作为 Base64- 编码字节数组. | 8.0.0 (单位:千美元) |

#### Android Ranging (英语). 参数

Android测距参数在控制器和控制器之间交换出波段.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`sessionId`** | `number` | 由两位同行共享会话标识符 . | 8.0.0 (单位:千美元) |
| **`sessionKeyInfo`** | `string` | 可选的 Base64 编码会话密钥信息 . | 8.0.0 (单位:千美元) |
| **`subSessionId`** | `number` | 提供STS的可选子会话标识符. | 8.0.0 (单位:千美元) |
| **`subSessionKeyInfo`** | `string` | 可选的碱基64-编码子会话密钥信息. | 8.0.0 (单位:千美元) |
| **`complexChannel`** | `[UwbComplexChannel](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-uwbcomplexchannel)` | 范围会话的频道配置 . | 8.0.0 (单位:千美元) |
| **`peerAddress`** | `string` | 端口 UWB 地址为 Base64- 编码字节数组 . | 8.0.0 (单位:千美元) |
| **`uwbConfigType`** | `number` | UWB 配置类型 。 默认在Android上独播DS-TWR. | 8.0.0 (单位:千美元) |
| **`slotDurationMillis`** | `number` | 持续时间以毫秒计. | 8.0.0 (单位:千美元) |
| **`updateRateType`** | `number` | 搜索更新速率类型 `RangingParameters` 安卓号. | 8.0.0 (单位:千美元) |

#### Uwb 复合频道

Android UWB 复杂频道与对等端交换出波段.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`channel`** | `number` | UWB频道号码. | 8.0.0 (单位:千美元) |
| **`preambleIndex`** | `number` | 测距会场使用的序言索引. | 8.0.0 (单位:千美元) |

#### 开始控制会议选项

备选方案 `startControllerSession()` 安卓号.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`sessionId`** | `number` | 与控制对象共享会话标识符 . | 8.0.0 (单位:千美元) |
| **`sessionKeyInfo`** | `string` | 可选的 Base64 编码会话密钥信息 . | 8.0.0 (单位:千美元) |
| **`subSessionId`** | `number` | 备选子会话标识符. | 8.0.0 (单位:千美元) |
| **`subSessionKeyInfo`** | `string` | 可选的碱基64-编码子会话密钥信息. | 8.0.0 (单位:千美元) |
| **`complexChannel`** | `[UwbComplexChannel](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-uwbcomplexchannel)` | UWB 频道配置 . | 8.0.0 (单位:千美元) |
| **`uwbConfigType`** | `number` | UWB 配置类型 。 默认为 unicast DS- TWR . | 8.0.0 (单位:千美元) |
| **`slotDurationMillis`** | `number` | 持续时间以毫秒计. | 8.0.0 (单位:千美元) |
| **`updateRateType`** | `number` | 搜索更新速率类型 `RangingParameters` 安卓号. | 8.0.0 (单位:千美元) |
| **`peerAddress`** | `string` | 可选控制器UWB地址. 提供范围时立即开始. | 8.0.0 (单位:千美元) |

#### 启动控制会议选项

备选方案 `startControleeSession()` 安卓号.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`rangingParameters`** | `[AndroidRangingParameters](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-androidrangingparameters)` | 从控制器出带得到的测距参数. | 8.0.0 (单位:千美元) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 搜索更新事件

有效载荷 `rangingUpdate` 听着.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`distanceMeters`** | `number` | 估计距离对等方以米计. | 8.0.0 (单位:千美元) |
| **`direction`** | `[UwbDirection](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-uwbdirection)` | 可用时方向矢量为对等点 . | 8.0.0 (单位:千美元) |
| **`azimuthRadians`** | `number` | 可用弧度时的半角. | 8.0.0 (单位:千美元) |
| **`elevationRadians`** | `number` | 可用弧度时的升角. | 8.0.0 (单位:千美元) |
| **`horizontalAngleRadians`** | `number` | 可用弧度时水平角度 . | 8.0.0 (单位:千美元) |
| **`timestamp`** | `number` | 收到更新时以毫秒为单位解去九时戳. | 8.0.0 (单位:千美元) |

#### 用户方向

UWB 测距报告3D方向矢量.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`x`** | `number` | 方向矢量的X组件. | 8.0.0 (单位:千美元) |
| **`y`** | `number` | 方向向量的 Y 组件 . | 8.0.0 (单位:千美元) |
| **`z`** | `number` | 方向矢量的 Z 组件 . | 8.0.0 (单位:千美元) |

#### 会话状态已改变

有效载荷 `sessionStateChanged` 听着.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`state`** | `[UwbSessionState](https://npmcn.com/package/%40capgo/capacitor-uwb/#readme-uwbsessionstate)` | 当前会议状态. | 8.0.0 (单位:千美元) |
| **`reason`** | `string` | 可选的人类可读理由或错误描述. | 8.0.0 (单位:千美元) |

#### 插件变压器

请求插件版本时返回结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`version`** | `string` | 本地插件版本字符串 . | 8.0.0 (单位:千美元) |

### 类型异名

#### 开会国

插件报告的会话周期状态 .

`'initialized' | 'running' | 'suspended' | 'resumed' | 'invalidated' | 'stopped' | 'peerDisconnected'`

## 常见问题

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

IOS和Android上的超宽波段\(UWB\)的电容插件\.

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

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

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

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

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

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

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

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

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

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

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

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