Inizia

Installazione

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo competenze al tuo strumento di AI utilizzando il seguente comando:

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

Poi utilizza 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 i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

bun add @capgo/capacitor-compass
bunx cap sync

Importa

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

API Panoramica

getCurrentHeading

Ottieni l'attuale orientamento della bussola in gradi. Su iOS, l'orientamento viene aggiornato in background e il valore più recente viene restituito. Su Android, l'orientamento viene calcolato quando viene chiamato il metodo utilizzando 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 a rilevare i cambiamenti dell'orientamento della bussola tramite eventi. Ciò avvia i sensori della bussola e 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

Smettere di ascoltare le variazioni del capo magnetico. Questo ferma i sensori del capo magnetico e ferma l'emissione di eventi.

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

await CapgoCompass.stopListening();

checkPermissions

Controlla lo stato di autorizzazione corrente per l'accesso ai dati del capo magnetico. Su iOS, questo controlla lo stato di autorizzazione per la localizzazione. Su Android, questo restituisce sempre ‘concesso’ 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 capo magnetico. Su iOS, questo richiede l'autorizzazione per la localizzazione (richiesta per i dati di capo magnetico). Su Android, questo 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 l'accuratezza del capo magnetico. Su Android, questo monitora l'accuratezza del magnetometro e emette eventi di accuratezzaChange. 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 dell'accuratezza del capo magnetico 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

Smetti di monitorare l'accuratezza del compasso. Questo ferma la monitoraggio dell'accuratezza.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Ottieni il livello di accuratezza del compasso corrente. Su Android, restituisce l'attuale accuratezza del sensore magnetometro. Su iOS e Web, restituisce sempre CompassAccuracy.UNKNOWN poiché la monitoraggio dell'accuratezza 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 direzione del compasso.

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

ListeningOptions

Opzioni per la configurazione del comportamento di ascolto di 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 evento per gli eventi di modifica della direzione.

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 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 di livello di accuratezza 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’s src/definitions.tsRiavvia la sincronizzazione quando il pubblico API cambia in modo upstream.

Continua da qui: Inizia

If sei stai utilizzando Avvio rapido per pianificare il pannello di controllo e le operazioni API, collega il tuo account a Utilizza @capgo/capacitor-compass per la capacità nativa in Utilizza @capgo/capacitor-compass, Panoramica di API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi di API per i dettagli di implementazione in Chiavi di API, e Dispositivi per i dettagli di implementazione nei dispositivi.