Getting Started

Installer

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant la commande suivante :

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

Utilisez ensuite la prompt suivante :

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 la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques au plateforme ci-dessous :

bun add @capgo/capacitor-compass
bunx cap sync

Importer

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

API Vue d'ensemble

getCurrentHeading

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

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

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

startListening

Démarrer l'écoute des changements d'orientation via des événements. Cela démarre les capteurs d'orientation 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êtez de suivre les changements de cap. Cela arrête les capteurs de boussole et arrête l'émission d'événements.

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

await CapgoCompass.stopListening();

checkPermissions

Vérifiez l'état actuel des autorisations pour accéder aux données de la boussole. Sur iOS, cela vérifie l'état de l'autorisation de localisation. Sur Android, cela retourne toujours ‘accordé’ car aucune autorisation n'est requise.

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

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

requestPermissions

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

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

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

watchAccuracy

Démarrer la surveillance de la précision de la boussole. Sur Android, cela surveille la précision du magnétomètre et émet des événements de changement de précision. Les développeurs peuvent écouter ces événements et mettre en place leur propre interface utilisateur pour les invitations de calibration. Sur iOS et Web, cette méthode ne fait rien car la surveillance de la précision de la boussole n'est pas disponible.

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

Arrêtez la surveillance de l'exactitude du compas. Cela arrête la surveillance de l'exactitude.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Obtenez le niveau actuel de précision du compas. 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 } 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 de direction du compas.

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

ListeningOptions

Options pour configurer le comportement d'écoute du compas.

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 d'en-tête.

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

AccuracyChangeEvent

Données d'événement pour les changements d'exactitude.

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

PermissionStatus

État de permission pour le plugin de 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 d'exactitude de la boussole.

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 permission pour l'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 du plugin’s src/definitions.ts. Re-run la synchronisation lorsque le public API change en amont.

Continuez de Getting Started

Si vous utilisez Getting Started planer le tableau de bord et les opérations API, connectez-le à En utilisant @capgo/capacitor-compass pour la capacité native dans En utilisant @capgo/capacitor-compass, API Vue d'ensemble pour le détail d'implémentation dans API Vue d'ensemble, Introduction pour le détail d'implémentation dans Introduction, API Clés pour le détail d'implémentation dans API Clés, et Appareils pour le détail d'implémentation dans Appareils.