Commencer

1. Installez le package

   npm

   npm i @capgo/capacitor-compass

   pnpm

   pnpm add @capgo/capacitor-compass

   yarn

   yarn add @capgo/capacitor-compass

   bun

   bun add @capgo/capacitor-compass

2. Synchronisation avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

iOS Configuration

Sur iOS, l’accès à la boussole nécessite une autorisation de localisation. Ajoutez ce qui suit à votre Info.plist :

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need location permission to access the compass</string>

Android Configuration

Aucune configuration supplémentaire requise. Le plugin utilise les capteurs magnétomètre et accéléromètre de l’appareil.

Utilisation

Importez le plugin et utilisez ses méthodes pour lire le cap de la boussole :

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

// Get current heading once
const getCurrentHeading = async () => {
  const { value } = await CapgoCompass.getCurrentHeading();
  console.log('Current heading:', value, 'degrees');
};

// Start continuous heading updates
const startCompass = async () => {
  // Start listening for updates
  await CapgoCompass.startListening();

  // Add listener for heading changes
  const handle = await CapgoCompass.addListener('headingChange', (event) => {
    console.log('Heading:', event.value, 'degrees');
  });

  // Later, to stop listening:
  // await CapgoCompass.stopListening();
  // await handle.remove();
};

// Check permissions
const checkPermission = async () => {
  const status = await CapgoCompass.checkPermissions();
  console.log('Permission status:', status.compass);
};

// Request permissions
const requestPermission = async () => {
  const status = await CapgoCompass.requestPermissions();
  if (status.compass === 'granted') {
    console.log('Compass access granted');
  }
};

API Référence

###getCurrentHeading()

Obtenez le cap actuel de la boussole en degrés.

const result = await CapgoCompass.getCurrentHeading();
// Returns: { value: number } - heading in degrees (0-360)

startListening()

Commencez à écouter les changements de cap de la boussole. Doit être appelé avant que les événements de cap ne soient émis.

await CapgoCompass.startListening();

stopListening()

Arrêtez d’écouter les changements de cap de la boussole.

await CapgoCompass.stopListening();

addListener(‘headingChange’, rappel)

Ajoutez un écouteur pour les événements de changement de titre.

const handle = await CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value);
});

// Remove listener when done
await handle.remove();

supprimerAllListeners()

Supprimez tous les auditeurs enregistrés.

await CapgoCompass.removeAllListeners();

checkPermissions()

Vérifiez l’état actuel des autorisations.

const status = await CapgoCompass.checkPermissions();
// Returns: { compass: 'prompt' | 'granted' | 'denied' }

requêtePermissions()

Demandez l’autorisation d’accéder aux données de la boussole.

const status = await CapgoCompass.requestPermissions();

###getPluginVersion()

Obtenez la version native du plugin.

const { version } = await CapgoCompass.getPluginVersion();

Exemple complet

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

export class CompassService {
  private listenerHandle: any = null;

  async init() {
    // Check and request permissions
    const status = await CapgoCompass.checkPermissions();
    if (status.compass !== 'granted') {
      const result = await CapgoCompass.requestPermissions();
      if (result.compass !== 'granted') {
        throw new Error('Compass permission denied');
      }
    }
  }

  async startTracking(onHeadingChange: (heading: number) => void) {
    // Start listening for updates
    await CapgoCompass.startListening();

    // Add event listener
    this.listenerHandle = await CapgoCompass.addListener(
      'headingChange',
      (event) => {
        onHeadingChange(event.value);
      }
    );
  }

  async stopTracking() {
    if (this.listenerHandle) {
      await this.listenerHandle.remove();
      this.listenerHandle = null;
    }
    await CapgoCompass.stopListening();
  }

  async getHeading(): Promise<number> {
    const { value } = await CapgoCompass.getCurrentHeading();
    return value;
  }

  getCardinalDirection(heading: number): string {
    const directions = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
    const index = Math.round(heading / 45) % 8;
    return directions[index];
  }
}

## Remarques sur la plate-forme

iOS

• Nécessite iOS 10.0+
• Utilise Core Location pour les données de cap
• Nécessite une autorisation de localisation (NSLocationWhenInUseUsageDescription)
• Les mises à jour des titres sont continues lorsque l’écoute est active

Android

• Nécessite Android 6.0 (API 23)+
• Utilise des capteurs accéléromètres et magnétomètres
• Aucune autorisation spéciale requise pour les capteurs de boussole
• Le cap est calculé à partir de la fusion des capteurs

###Web

• Non pris en charge sur la plateforme Web
• Les méthodes généreront des erreurs lorsqu’elles seront appelées