快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-uwb` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-uwb
bunx cap sync

导入

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

快速入门

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

const result = await CapacitorUwb.isAvailable();
console.log(result);

示例：getDiscoveryToken

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

const result = await CapacitorUwb.getDiscoveryToken();
// The result holds sensitive values: use it without logging it.

示例：startPeerSession

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

await CapacitorUwb.startPeerSession({ peerDiscoveryToken: 'peer-discovery-token-123' });

常见坑点

• 监听器: 在页面卸载时移除句柄。
• 原生同步：运行 bunx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

检查可用性

const availability = await CapacitorUwb.isAvailable();

if (!availability.supported) {
  console.log('This device does not support UWB.');
}

iOS 对等会话

1. 调用 getDiscoveryToken() 在两台设备上。
2. 通过带外通道 (out-of-band) 交换返回的 base64 token。
3. 使用对端 token 开始测距。

const { discoveryToken } = await CapacitorUwb.getDiscoveryToken();

await CapacitorUwb.startPeerSession({
  peerDiscoveryToken: '<peer-token-base64>',
});

查看 iOS 配置 以了解功能和权限要求。

Android 控制端 / 被控端会话

1. 控制端调用 startControllerSession() 并共享返回的 rangingParameters 以及 localAddress.
2. 被控端构建自己的 rangingParameters，使用控制端的 localAddress 命名为 peerAddress.
3. 被控端调用 startControleeSession({ rangingParameters }).
4. 可选传入 peerAddress 在获知被控端地址后传给控制器。

const controller = await CapacitorUwb.startControllerSession();

await CapacitorUwb.startControleeSession({
  rangingParameters: {
    ...controller.rangingParameters,
    peerAddress: controller.localAddress,
  },
});

查看 Android 配置 硬件和权限要求。

监听更新

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

await CapacitorUwb.addListener('sessionStateChanged', (event) => {
  console.log(event.state, event.reason);
});

停止会话

await CapacitorUwb.stopSession();

单一事实来源

本页面由插件的 src/definitions.ts. 更新 TypeScript 定义并运行 bun run docgen 在插件仓库中执行，以刷新生成的 API 文档。