使用 @capgo/capacitor-compass
Capacitor Compass 插件接口，用于读取设备指南针航向。
安装
bun add @capgo/capacitor-compass
bunx cap sync
bunx cap sync 将插件的原生 code 复制到你的原生项目中。每次升级插件后都要重新运行。
导入
import { CapgoCompass } from '@capgo/capacitor-compass';
API 概览
| 方法 | 描述 |
|---|---|
getCurrentHeading |
获取当前指南针航向（单位：度）。在 iOS 上，航向会在后台更新并返回最新值。在 Android 上，调用该方法时会通过加速度计和磁力计传感器计算航向。Web 端未实现。 |
startListening |
开始通过事件监听指南针航向的变化。此操作会启动指南针传感器并触发 'headingChange' 事件。 |
stopListening |
停止监听指南针航向变化。这会停止指南针传感器并停止触发事件。 |
checkPermissions |
检查访问指南针数据的当前权限状态。在 iOS 上，这会检查位置权限状态；在 Android 上，由于无需权限，将始终返回 'granted'。 |
requestPermissions |
请求访问指南针数据的权限。在 iOS 上，这会请求位置权限（获取航向数据所必需）。在 Android 上，由于不需要权限，此请求会立即完成。 |
watchAccuracy |
开始监测指南针精度。在 Android 上，这会监测磁力计精度并触发 accuracyChange 事件。开发者可以监听这些事件，并自行实现校准提示 UI。在 iOS 和 Web 上，由于无法监测指南针精度，此方法不会执行任何操作。 |
unwatchAccuracy |
停止监测指南针精度。此操作会停止精度监测。 |
getAccuracy |
获取当前指南针精度等级。在 Android 上，返回当前磁力计传感器的精度。在 iOS 和 Web 上，由于无法进行精度监测，始终返回 CompassAccuracy.UNKNOWN。 |
示例
getCurrentHeading()
获取当前指南针航向（单位：度）。在 iOS 上，航向会在后台更新并返回最新值。在 Android 上，调用该方法时会通过加速度计和磁力计传感器计算航向。Web 端未实现。
import { CapgoCompass } from '@capgo/capacitor-compass';
const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');
startListening()
通过事件开始监听指南针航向变化。此操作会启动指南针传感器并触发 'headingChange' 事件。
import { CapgoCompass } from '@capgo/capacitor-compass';
// With default throttling (100ms interval, 2° minimum change)
await CapgoCompass.startListening();
// With custom throttling for high-frequency updates
await CapgoCompass.startListening({
minInterval: 50, // 50ms between events
minHeadingChange: 1.0 // 1° minimum change
});
CapgoCompass.addListener('headingChange', (event) => {
console.log('Heading:', event.value);
});
stopListening()
停止监听指南针航向变化。这会停止指南针传感器并停止触发事件。
import { CapgoCompass } from '@capgo/capacitor-compass';
await CapgoCompass.stopListening();
checkPermissions()
检查访问指南针数据的当前权限状态。在 iOS 上，这会检查位置权限状态。在 Android 上，由于无需权限，此操作始终返回 'granted'。
import { CapgoCompass } from '@capgo/capacitor-compass';
const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);
requestPermissions()
请求访问指南针数据的权限。在 iOS 上，这会请求位置权限（获取航向数据所必需）。在 Android 上，由于不需要权限，此请求会立即完成。
import { CapgoCompass } from '@capgo/capacitor-compass';
const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
// Can now use compass
}
watchAccuracy()
开始监测指南针精度。在 Android 上，这会监测磁力计精度并触发 accuracyChange 事件。开发者可以监听这些事件，并自行实现校准提示 UI。在 iOS 和 Web 上，由于无法监测指南针精度，此方法不会执行任何操作。
import { CapgoCompass, CompassAccuracy } from '@capgo/capacitor-compass';
// Start monitoring accuracy
await CapgoCompass.watchAccuracy();
// Listen for accuracy changes and implement custom UI
CapgoCompass.addListener('accuracyChange', (event) => {
console.log('Accuracy changed to:', event.accuracy);
if (event.accuracy < CompassAccuracy.MEDIUM) {
// Show your custom calibration UI
}
});
上表列出了 8 个核心方法。有关监听器、版本辅助函数以及每个方法的完整契约，请参阅 GitHub 仓库.
监听事件
addListener 会返回一个句柄。调用 handle.remove() 在屏幕卸载时，或者调用 CapgoCompass.removeAllListeners() 以清除所有监听器。
完整参考文档
继续阅读“使用 @capgo/capacitor-compass”
如果你正在使用 使用 @capgo/capacitor-compass 要规划 dashboard 和 API 操作，请将其连接到 @capgo/capacitor-compass 有关 @capgo/capacitor-compass 中的实现细节， 快速入门 有关“入门指南”中的实现细节， API 概览 关于 API Overview 中的实现细节， 简介 关于简介中的实现细节，以及 API 密钥 关于 API Keys 中的实现细节。