Brújula plugin Capacitor

Usando @capgo/capacitor-compass

Plugin de Capacitor Compass para leer la orientación de la brújula del dispositivo.

Instalar

bun add @capgo/capacitor-compass
bunx cap sync

bunx cap sync copia el code nativo del plugin en tus proyectos nativos. Ejecútalo de nuevo tras cada actualización del plugin.

Importar

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

API de un vistazo

Método	Descripción
getCurrentHeading	Obtén el rumbo actual de la brújula en grados. En iOS, el rumbo se actualiza en segundo plano y se devuelve el último valor. En Android, el rumbo se calcula al llamar al método usando los sensores de acelerómetro y magnetómetro. No implementado en Web.
startListening	Empieza a escuchar los cambios de orientación del compás mediante eventos. Esto activa los sensores del compás y emite eventos 'headingChange'.
stopListening	Deja de escuchar los cambios de orientación de la brújula. Esto detiene los sensores y deja de emitir eventos.
checkPermissions	Comprueba el estado actual de los permisos para acceder a los datos de la brújula. En iOS, esto comprueba el estado del permiso de ubicación. En Android, siempre devuelve 'granted', ya que no se requieren permisos.
requestPermissions	Solicita permiso para acceder a los datos de la brújula. En iOS, esto solicita el permiso de ubicación (necesario para los datos de rumbo). En Android, se resuelve de inmediato, ya que no se requieren permisos.
watchAccuracy	Empieza a monitorear la precisión de la brújula. En Android, monitorea la precisión del magnetómetro y emite eventos accuracyChange. Los desarrolladores pueden escuchar estos eventos e implementar su propia UI para los prompts de calibración. En iOS y Web, este método no hace nada, ya que el monitoreo de la precisión de la brújula no está disponible.
unwatchAccuracy	Deja de monitorear la precisión de la brújula. Esto detiene el monitoreo de precisión.
getAccuracy	Obtiene el nivel de precisión actual de la brújula. En Android, devuelve la precisión actual del sensor magnetómetro. En iOS y Web, siempre devuelve CompassAccuracy.UNKNOWN ya que el monitoreo de precisión no está disponible.

Ejemplos

getCurrentHeading()

Obtén el rumbo actual de la brújula en grados. En iOS, el rumbo se actualiza en segundo plano y se devuelve el último valor. En Android, el rumbo se calcula al llamar al método usando los sensores de acelerómetro y magnetómetro. No implementado en Web.

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

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

startListening()

Empieza a escuchar los cambios de orientación del compás mediante eventos. Esto activa los sensores del compás y emite eventos '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()

Deja de escuchar los cambios de orientación de la brújula. Esto detiene los sensores y deja de emitir eventos.

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

await CapgoCompass.stopListening();

checkPermissions()

Comprueba el estado actual de los permisos para acceder a los datos de la brújula. En iOS, esto comprueba el estado del permiso de ubicación. En Android, siempre devuelve 'granted', ya que no se requieren permisos.

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

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

requestPermissions()

Solicita permiso para acceder a los datos de la brújula. En iOS, esto solicita el permiso de ubicación (necesario para los datos de rumbo). En Android, se resuelve de inmediato, ya que no se requieren permisos.

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

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

watchAccuracy()

Empieza a monitorear la precisión de la brújula. En Android, monitorea la precisión del magnetómetro y emite eventos accuracyChange. Los desarrolladores pueden escuchar estos eventos e implementar su propia UI para los prompts de calibración. En iOS y Web, este método no hace nada, ya que el monitoreo de la precisión de la brújula no está disponible.

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
  }
});

La tabla anterior lista los 8 métodos principales. Los helpers de listener y de versión, y el contrato completo de cada método, están documentados en la repositorio GitHub.

Escuchar eventos

addListener devuelve un handle. Llama handle.remove() cuando la pantalla se desmonte, o CapgoCompass.removeAllListeners() para limpiar todos los listeners.

Referencia completa

• repositorio GitHub
• Documentación
• Referencia de API

Continúa desde Uso de @capgo/capacitor-compass

Si estás usando Uso de @capgo/capacitor-compass para planificar las operaciones del dashboard y de API, conéctalo con @capgo/capacitor-compass para los detalles de implementación en @capgo/capacitor-compass, Primeros pasos para los detalles de implementación en Primeros pasos, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en Introducción, y Claves de API para los detalles de implementación en API Keys.