Accueil

Installer

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA à l'aide de 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 renvoyé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

Commencez à écouter les 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 d'écouter les changements de direction de boussole. 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 boussole. Sur iOS, cela vérifie l'état des autorisations de localisation. Sur Android, cela renvoie 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

Demandez l'autorisation d'accéder aux données de boussole. Sur iOS, cela demande l'autorisation de localisation (requise pour les données de direction). 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

Commencez à surveiller l'exactitude de la boussole. Sur Android, cela surveille l'exactitude du magnétomètre et émet des événements de changement d'exactitude. 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 l'exactitude 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êter la surveillance de la précision du compas. Cela arrête la surveillance de la précision.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Obtenir le niveau actuel de précision du compas. Sur Android, retourne la précision actuelle du capteur magnétométrique. 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éférence de type

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 du compas.

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 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 la 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.tsRe-run la synchronisation lorsque les public API changent en amont.

Continuez de Getting Started

Si vous utilisez Démarrage pour planifier le tableau de bord et les opérations API, connectez-le à Utilisation de @capgo/capacitor-compass for the native capability in Using @capgo/capacitor-compass, pour les détails d'implémentation dans Vue d'ensemble de API, for the implementation detail in API Overview, pour les détails d'implémentation dans Introduction, __CAPGO_KEEP_0__ Clés pour les détails d'implémentation dans API Clés, et for the implementation detail in API Keys, and Getting Started pour les détails d'implémentation dans les appareils.