罗盘 Capacitor 插件

使用 @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()

获取当前compass方向（角度）。 在iOS上，方向会在后台更新，返回最新值。 在Android上，方向会在调用方法时使用加速度计和磁力计传感器计算。 未在Web上实现。

import { CapgoCompass } from '@capgo/capacitor-compass';

const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');

startListening()

开始监听compass方向变化事件。 这会启动compass传感器并发射'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()

停止监听compass方向变化事件。 这会停止compass传感器并停止发射事件。

import { CapgoCompass } from '@capgo/capacitor-compass';

await CapgoCompass.stopListening();

checkPermissions()

检查当前访问compass数据的权限状态。 在iOS上，检查位置权限状态。 在Android上，始终返回'granted'，因为无需权限。

import { CapgoCompass } from '@capgo/capacitor-compass';

const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);

requestPermissions()

请求访问compass数据的权限。 在iOS上，请求位置权限（用于获取方向数据）。 在Android上，立即返回，因为无需权限。

import { CapgoCompass } from '@capgo/capacitor-compass';

const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
  // Can now use compass
}

watchAccuracy()

开始监控compass精度。 在Android上，监控磁力计精度并发射accuracyChange事件。 开发者可以监听这些事件并实现自己的UI提示用户进行校准。 在iOS和Web上，这个方法什么也不做，因为compass精度监控不可用。

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() 清除所有监听器。

完整参考

• GitHub 仓库
• 文档
• API 参考

继续使用 @capgo/capacitor Compass

如果您正在使用 使用@capgo/capacitor-compass 规划API仪表板和操作，连接它 @capgo/capacitor-compass 了解@capgo/capacitor-compass的实现细节 开始使用 了解开始使用的实现细节 API概述 了解API概述的实现细节 介绍 了解介绍的实现细节 API密钥 了解API密钥的实现细节