Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

npm install @capgo/capacitor-compass
npx cap sync

Importer

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

Démarrage rapide

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

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

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

Exemple : stopListening

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

await CapgoCompass.stopListening();

Erreurs courantes

• Autorisations: appelez checkPermissions() puis requestPermissions() si nécessaire.
• Écouteurs: supprimez les handles lors du démontage des écrans.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Aperçu de API

getCurrentHeading

Récupère l'orientation actuelle de la boussole en degrés. Sur iOS, l'orientation est mise à jour en arrière-plan et la dernière valeur est renvoyée. Sur Android, l'orientation est calculée lors de l'appel de la méthode à l'aide des capteurs accéléromètre et magnétomètre. Non implémenté sur le Web.

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

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

startListening

Écoutez les changements d’orientation de la boussole via des événements. Cela active les capteurs de la boussole et émet des événements « 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

Arrête l'écoute des changements de cap du compas. Cela désactive les capteurs du compas et arrête l'émission d'événements.

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

await CapgoCompass.stopListening();

checkPermissions

Vérifie l'état actuel des permissions pour accéder aux données du compas. Sur iOS, cela vérifie l'état des permissions de localisation. Sur Android, cela retourne toujours « granted » car aucune permission n'est requise.

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

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

requestPermissions

Demande la permission d'accéder aux données du compas. Sur iOS, cela demande la permission de localisation (requise pour les données de cap). Sur Android, cela se résout immédiatement car aucune permission n'est requise.

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

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

watchAccuracy

Commence à surveiller la précision du compas. Sur Android, cela surveille la précision du magnétomètre et émet des événements accuracyChange. Les développeurs peuvent écouter ces événements et implémenter leur propre UI pour les prompts de calibration. Sur iOS et Web, cette méthode ne fait rien car la surveillance de la précision du compas n'est pas disponible.

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

Arrêter la surveillance de la précision de la boussole. Cela arrête la surveillance de la précision.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Obtenir le niveau de précision actuel de la boussole. Sur Android, retourne la précision actuelle du capteur magnétomètre. Sur iOS et Web, retourne toujours CompassAccuracy.UNKNOWN car la surveillance de la précision n'est pas disponible.

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

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

Référence de type

CompassHeading

Résultat contenant la valeur du cap de la boussole.

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

ListeningOptions

Options pour configurer le comportement d’écoute de la boussole.

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

Données d’événement pour les changements de cap.

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

AccuracyChangeEvent

Données d’événement pour les changements de précision.

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

PermissionStatus

Statut de l’autorisation pour le plugin boussole.

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

Constantes de niveau de précision de Compass.

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

État de l'autorisation d'accès à la boussole.

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

Source de vérité

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les opérations du dashboard et de API, connectez-l’avec Utiliser @capgo/capacitor-compass pour la capacité native dans « Utiliser @capgo/capacitor-compass », Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.