Démarrage

Installation

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. Pas implémenté sur Web.

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

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

startListening

Démarrez la lecture des changements de direction magnétique via des événements. Cela démarre les capteurs magnétiques 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 la lecture des changements de direction magnétique. Cela arrête les capteurs magnétiques 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 magnétique. Sur iOS, cela vérifie l'état de la permission de localisation. Sur Android, cela renvoie toujours ‘granted’ 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 direction magnétique. 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 l'exactitude du compas. Sur Android, cela surveille l'exactitude du capteur magnétique et émet des événements de changement d'exactitude. Les développeurs peuvent écouter ces événements et mettre en œuvre 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 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êtez de surveiller 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 d'exactitude du compas. Sur Android, retourne l'exactitude actuelle du capteur magnétique. Sur iOS et Web, retourne toujours CompassAccuracy.UNKNOWN car la surveillance de l'exactitude du compas 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 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 de l'événement de changement de direction.

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

AccuracyChangeEvent

Données de l'événement de changement 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 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 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 modifications publiques API se produisent en amont.

Continuez de l'Accueil

Si vous utilisez Accueil pour planifier le tableau de bord et les opérations API, connectez-le à Utilisation de @capgo/capacitor-compass pour la capacité native dans Utilisation de @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 les détails d'implémentation dans les API clés, et Appareils pour les détails d'implémentation dans Appareils.