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

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 au 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'orientation actuelle du compas en degrés. Sur iOS, l'orientation est mise à jour en arrière-plan, et la valeur la plus récente 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

Démarrer la lecture des changements d'orientation du compas via des événements. Cela démarre les capteurs du compas 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 magnétique. Cela arrête les capteurs de direction 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 direction. Sur iOS, cela vérifie l'état de la permission de localisation. Sur Android, cela retourne toujours « autorisé » 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 la permission d'accéder aux données de direction. 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

Démarrer la surveillance de l'exactitude de la direction. 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 direction 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

Niveaux 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 des autorisations 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-générez la synchronisation lorsque le public API change en amont.

Continuez de Getting Started

Si vous utilisez Prise en main pour planifier votre tableau de bord et les opérations API, connectez-l’à Utilisation de @capgo/capacitor-compass pour la capacité native dans Utilisation de @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 sur les appareils.