Inizia

Installa

bun add @capgo/capacitor-compass
bunx cap sync

Importa

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

API Panoramica

getCurrentHeading

Ottieni l'attuale direzione del compasso in gradi. Su iOS, la direzione viene aggiornata in background e il valore più recente viene restituito. Su Android, la direzione viene calcolata quando il metodo viene chiamato utilizzando 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 della direzione magnetica tramite eventi. Ciò avvia i sensori del compasso e invia 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 della direzione magnetica. Ciò ferma i sensori del compasso e ferma l'invio di eventi.

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

await CapgoCompass.stopListening();

checkPermissions

Controlla lo stato di autorizzazione corrente per accedere ai dati del compasso. Su iOS, ciò controlla lo stato di autorizzazione per la posizione. Su Android, ciò restituisce sempre ‘granted’ poiché non sono richieste autorizzazioni.

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

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

requestPermissions

Richiedi l'autorizzazione per accedere ai dati del compasso. Su iOS, ciò richiede l'autorizzazione per la posizione (richiesta per i dati di direzione). Su Android, ciò risolve immediatamente poiché non sono richieste autorizzazioni.

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 del compasso. Su Android, questo monitora la precisione del magnetometro e emette eventi di cambio di precisione. I sviluppatori possono ascoltare questi eventi e implementare la propria UI per le richieste di calibrazione. Su iOS e Web, questo metodo non fa nulla poiché la monitorazione della precisione del compasso non è disponibile.

import { CapgoCompass } 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

Fermati di monitorare la precisione del compasso. Questo ferma la monitorazione della precisione.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Ottieni il livello di precisione attuale del compasso. Su Android, restituisce la precisione attuale del sensore magnetometro. Su iOS e Web, restituisce sempre CompassAccuracy.UNKNOWN poiché la monitorazione della precisione del compasso non è disponibile.

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

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

Riferimento di tipo

CompassHeading

Risultato contenente il valore di orientamento della bussola.

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

ListeningOptions

Opzioni per la configurazione del comportamento di ascolto della bussola.

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 evento per gli eventi di modifica dell'orientamento.

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

AccuracyChangeEvent

Dati evento per gli eventi di modifica dell'accuratezza.

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

PermissionStatus

Stato di autorizzazione per il plugin di compasso.

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 di livello di precisione del compasso.

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 di autorizzazione per l'accesso al compasso.

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

Fonte di verità

Questa pagina è generata dal plugin e viene sincronizzata con il repository di GitHub. src/definitions.tsRisciacqua nuovamente la sincronizzazione quando le modifiche pubbliche API vengono apportate in fase di sviluppo.

Continua da Iniziare

Se stai utilizzando Iniziare per pianificare il dashboard e le operazioni API, connettilo con Utilizza @capgo/capacitor-compass per la capacità nativa in Utilizza @capgo/capacitor-compass API Panoramica per i dettagli di implementazione in API Panoramica Introduzione per i dettagli di implementazione in Introduzione API Chiavi per i dettagli di implementazione in API Chiavi, e Dispositivi per i dettagli di implementazione in Dispositivi.