Einstieg

Installieren

bun add @capgo/capacitor-compass
bunx cap sync

Importieren

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

API Übersicht

getCurrentHeading

Ermitteln Sie den aktuellen Kompasswinkel in Grad. Bei iOS wird der Winkel im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Bei Android wird der Winkel, wenn die Methode aufgerufen wird, mithilfe von Beschleunigungssensor und Magnetometer berechnet. Nicht implementiert auf Web.

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

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

startListening

Starten Sie das Abhören von Änderungen des Kompasswinkels über Ereignisse. Dies startet die Kompass-Sensoren und sendet Ereignisse ‘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

Beenden Sie das Abhören von Änderungen des Kompasswinkels. Dies stoppt die Kompass-Sensoren und stoppt die Ereignisausgabe.

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

await CapgoCompass.stopListening();

checkPermissions

Überprüfen Sie den aktuellen Berechtigungsstatus für den Zugriff auf Kompassdaten. Bei iOS wird die Standortberechtigung überprüft. Bei Android wird immer ‘granted’ zurückgegeben, da keine Berechtigungen erforderlich sind.

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

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

requestPermissions

Berechtigung zum Zugriff auf Kompassdaten anfordern. Auf iOS wird hier die Standortberechtigung angefordert (erforderlich für die Kopf-Höhen-Daten). Auf Android wird dies sofort erfüllt, da keine Berechtigungen erforderlich sind.

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

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

watchAccuracy

Kopf-Höhen-Accurazitätsüberwachung starten. Auf Android überwacht dies die Magnetometer-Accurazität und sendet Ereignisse für accuracyChange. Entwickler können auf diese Ereignisse hören und eigene UI für Kalibrierungshinweise implementieren. Auf iOS und Web tut sich nichts, da die Kopf-Höhen-Accurazitätsüberwachung nicht verfügbar ist.

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

Kopf-Höhen-Accurazitätsüberwachung beenden. Dies beendet die Accurazitätsüberwachung.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Aktuelle Kopf-Höhen-Accurazität abrufen. Auf Android wird die aktuelle Magnetometer-Sensor-Accurazität zurückgegeben. Auf iOS und Web wird immer CompassAccuracy.UNKNOWN zurückgegeben, da die Accurazitätsüberwachung nicht verfügbar ist.

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

const { accuracy } = await CapgoCompass.getAccuracy();
if (accuracy < CompassAccuracy.MEDIUM) {
  console.log('Compass needs calibration');
}

Typenreferenz

CompassHeading

Ergbnis mit dem Winkelwert des Kompasses.

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

ListeningOptions

Optionen zur Konfiguration des Hörverhaltens des Kompasses.

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

Ereignisdaten für Änderungen des Kompasswinkels.

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

AccuracyChangeEvent

Ereignisdaten für Änderungen der Genauigkeit.

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

PermissionStatus

Zugriffsstatus für Kompass-Plugin.

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

Konstanten für die Genauigkeit des Kompasses.

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

Zugriffsstatus für Kompass-Zugriff.

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

Quelle der Wahrheit

Diese Seite wurde aus dem Plugin generiert. src/definitions.tsRe-run the Sync, wenn die öffentliche API upstream geändert wird.