Bussola Plugin Capacitor

Usare @capgo/capacitor-compass

Interfaccia del plugin Capacitor Compass per leggere l'orientamento della bussola del dispositivo.

Installa

bun add @capgo/capacitor-compass
bunx cap sync

bunx cap sync copia i code nativi del plugin nei tuoi progetti nativi. Eseguilo di nuovo dopo ogni aggiornamento del plugin.

Importa

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

API in breve

Metodo	Descrizione
getCurrentHeading	Ottieni l'orientamento attuale della bussola in gradi. Su iOS, l'orientamento viene aggiornato in background e viene restituito l'ultimo valore disponibile. Su Android, l'orientamento viene calcolato al momento della chiamata tramite i sensori accelerometro e magnetometro. Non implementato su Web.
startListening	Inizia a monitorare i cambiamenti di orientamento tramite eventi. Questo attiva i sensori della bussola ed emette eventi 'headingChange'.
stopListening	Smetti di monitorare i cambiamenti di orientamento. Questo disattiva i sensori della bussola e interrompe l'emissione di eventi.
checkPermissions	Controlla lo stato attuale dei permessi per accedere ai dati della bussola. Su iOS, verifica lo stato dei permessi di localizzazione. Su Android, restituisce sempre 'granted' poiché non sono richiesti permessi.
requestPermissions	Richiedi il permesso per accedere ai dati della bussola. Su iOS, richiede il permesso di localizzazione (necessario per i dati di orientamento). Su Android, la richiesta si risolve immediatamente poiché non sono richiesti permessi.
watchAccuracy	Inizia a monitorare la precisione della bussola. Su Android, monitora la precisione del magnetometro ed emette eventi accuracyChange. Gli sviluppatori possono ascoltare questi eventi e implementare la propria UI per i prompt di calibrazione. Su iOS e Web, questo metodo non ha effetto poiché il monitoraggio della precisione non è disponibile.
unwatchAccuracy	Smetti di monitorare la precisione della bussola. Interrompe il monitoraggio della precisione.
getAccuracy	Ottieni il livello di precisione attuale della bussola. Su Android, restituisce la precisione attuale del sensore magnetometro. Su iOS e Web, restituisce sempre CompassAccuracy.UNKNOWN poiché il monitoraggio della precisione non è disponibile.

Esempi

getCurrentHeading()

Ottieni l'orientamento attuale della bussola in gradi. Su iOS, l'orientamento viene aggiornato in background e viene restituito l'ultimo valore. Su Android, l'orientamento viene calcolato al momento della chiamata al metodo usando i sensori accelerometro e magnetometro. Non implementato su Web.

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

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

startListening()

Inizia ad ascoltare i cambiamenti di orientamento della bussola tramite eventi. Questo avvia i sensori della bussola ed emette eventi '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()

Smetti di ascoltare i cambiamenti di orientamento della bussola. Questo ferma i sensori della bussola e interrompe l'emissione di eventi.

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

await CapgoCompass.stopListening();

checkPermissions()

Controlla lo stato attuale dei permessi per accedere ai dati della bussola. Su iOS, verifica lo stato dei permessi di localizzazione. Su Android, restituisce sempre 'granted' dato che non servono permessi.

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

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

requestPermissions()

Richiedi il permesso per accedere ai dati della bussola. Su iOS, richiede il permesso di localizzazione (necessario per i dati di orientamento). Su Android, viene risolta subito dato che non servono permessi.

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

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

watchAccuracy()

Inizia a monitorare la precisione della bussola. Su Android, monitora la precisione del magnetometro ed emette eventi accuracyChange. Gli sviluppatori possono ascoltare questi eventi e implementare la propria UI per i prompt di calibrazione. Su iOS e Web, questo metodo non fa nulla poiché il monitoraggio della precisione della bussola non è disponibile.

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 tabella sopra elenca gli 8 metodi core. Gli helper per listener e versioni, e il contratto completo di ogni metodo, sono documentati nella repository GitHub.

Ascolta gli eventi

addListener restituisce un handle. Chiama handle.remove() quando la schermata viene smontata, o CapgoCompass.removeAllListeners() per rimuovere tutti i listener.

Riferimento completo

• repository GitHub
• Documentazione
• riferimento API

Continua da Utilizzo di @capgo/capacitor-compass

Se stai usando Usare @capgo/capacitor-compass per pianificare le operazioni della dashboard e di API, collegalo a @capgo/capacitor-compass per i dettagli di implementazione in @capgo/capacitor-compass, Per iniziare per i dettagli di implementazione nella guida introduttiva, Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli implementativi nell'Introduzione, e Chiavi API per i dettagli implementativi in API Keys.