Démarrage

Installation

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

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

Ensuite, utilisez 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 à la plateforme ci-dessous :

bun add @capgo/capacitor-compass
bunx cap sync

Importer

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

API Vue d'ensemble

getCurrentHeading

Obtenir l'angle actuel de la boussole en degrés. Sur iOS, l'angle est mis à jour en arrière-plan, et la dernière valeur est renvoyée. Sur Android, l'angle est calculé 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 la lecture des changements de l'angle de la boussole via des événements. Cela démarre 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êtez d'écouter les changements de direction du compas. Cela arrête les capteurs du compas 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 du compas. Sur iOS, cela vérifie l'état de la permission 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 du compas. Sur iOS, cela demande la permission 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 la précision du compas. 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 du compas 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é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 de 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

Données d'événement pour les changements de titre.

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 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

Constantes de niveau de précision du compas.

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

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 le public API change en amont.

Continuez de Getting Started

Si vous utilisez Prise en main pour planifier l'interface de tableau de bord et les opérations API, connectez-l’avec En utilisant @capgo/capacitor-compass pour la capacité native dans En utilisant @capgo/capacitor-compass, API Vue d'ensemble pour les détails d'implémentation dans API Vue d'ensemble, Introduction pour les détails d'implémentation dans Introduction, API Clés pour les détails d'implémentation dans API Clés, et Appareils pour les détails d'implémentation dans les appareils.