Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

npm install @capgo/capacitor-compass
npx cap sync

Importa

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

Avvio rapido

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

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

Esempio: startListening

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

Esempio: stopListening

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

await CapgoCompass.stopListening();

Errori comuni

• Permessi: chiamata checkPermissions() poi requestPermissions() quando necessario.
• Listener: rimuovi gli handle quando gli schermi vengono smontati.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Panoramica API

getCurrentHeading

Ottieni la direzione attuale della bussola in gradi. Su iOS, la direzione viene aggiornata in background e viene restituito l'ultimo valore. Su Android, la direzione viene calcolata al momento della chiamata tramite 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 l'ascolto dei cambiamenti di direzione 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

Interrompi l'ascolto dei cambiamenti di orientamento della bussola. Questo ferma i sensori della bussola e interrompe l'emissione degli 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’ poiché non sono richiesti 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, si risolve immediatamente poiché non sono richiesti permessi.

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

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

watchAccuracy

Inizia a monitorare l'accuratezza della bussola. Su Android, monitora l'accuratezza 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 dell'accuratezza 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
  }
});

unwatchAccuracy

Smetti di monitorare la precisione della bussola. Interrompe il monitoraggio della precisione.

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

await CapgoCompass.unwatchAccuracy();

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 non è disponibile.

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

const { accuracy } = await CapgoCompass.getAccuracy();
if (accuracy < CompassAccuracy.MEDIUM) {
  console.log('Compass needs calibration');
}

Riferimento ai tipi

CompassHeading

Risultato contenente il valore dell'heading della bussola.

export interface CompassHeading {
  /** Compass heading in degrees (0-360) */
  value: number;
}

ListeningOptions

Opzioni per configurare il comportamento di ascolto del compass.

export interface ListeningOptions {
  /**
   * Minimum interval between heading change events in milliseconds.
   * Lower values = more frequent updates but higher CPU/battery usage.
   *
   * @default 100
   * @since 8.1.4
   */
  minInterval?: number;

  /**
   * Minimum heading change in degrees required to trigger an event.
   * Lower values = more sensitive but more events.
   * Handles wraparound (e.g., 359° to 1° = 2° change).
   *
   * @default 2.0
   * @since 8.1.4
   */
  minHeadingChange?: number;
}

HeadingChangeEvent

Dati dell'evento per i cambiamenti di heading.

export interface HeadingChangeEvent {
  /** Compass heading in degrees (0-360) */
  value: number;
}

AccuracyChangeEvent

Dati dell'evento per i cambiamenti di accuratezza.

export interface AccuracyChangeEvent {
  /** Current accuracy level of the compass */
  accuracy: CompassAccuracy;
}

PermissionStatus

Stato dei permessi per il plugin compass.

export interface PermissionStatus {
  /**
   * Permission state for accessing compass/location data.
   * On iOS, this requires location permission to access heading.
   * On Android, no special permissions are required for compass sensors.
   *
   * @since 7.0.0
   */
  compass: PermissionState;
}

CompassAccuracy

Costanti del livello di precisione della bussola.

export enum CompassAccuracy {
  /** High accuracy - approximates to less than 5 degrees of error */
  HIGH = 3,
  /** Medium accuracy - approximates to less than 10 degrees of error */
  MEDIUM = 2,
  /** Low accuracy - approximates to less than 15 degrees of error */
  LOW = 1,
  /** Unreliable accuracy - approximates to more than 15 degrees of error */
  UNRELIABLE = 0,
  /** Unknown accuracy value */
  UNKNOWN = -1,
}

PermissionState

Stato dei permessi per l'accesso alla bussola.

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

Fonte di verità

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Continua da Getting Started

Se stai usando Per iniziare per pianificare le operazioni della dashboard e di API, collegalo a Usare @capgo/capacitor-compass per la funzionalità nativa in @capgo/capacitor-compass, Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione in Chiavi API, e Dispositivi per i dettagli di implementazione in Dispositivi.