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-Sensor 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 Kompasswinkeländerungen über Ereignisse. Dies startet die Kompass-Sensoren und sendet ‘headingChange’-Ereignisse aus.

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 Kompasswinkeländerungen. 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 überprüft dies den Standortberechtigungsstatus. Bei Android wird immer ‘erteilt’ 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. Bei iOS wird die Standortberechtigung angefordert (erforderlich für die Kopfdaten). Bei Android wird diese 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

Kompassgenauigkeit überwachen. Bei Android überwacht dies die Magnetometergenauigkeit und sendet Genauigkeitsänderungsereignisse. Entwickler können auf diese Ereignisse hören und eigene UI-Ansagen für Kalibrierungsprompt implementieren. Bei iOS und Web tut sich diese Methode nichts, da die Überwachung der Kompassgenauigkeit 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

Kompassgenauigkeitsüberwachung beenden. Dies beendet die Genauigkeitsüberwachung.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Ermitteln Sie den aktuellen Kompassgenauigkeitsgrad. Bei Android-Geräten wird der aktuelle Magnetometer-Sensoren-Accurazität zurückgegeben. Bei iOS- und Web-Geräten wird immer CompassAccuracy.UNKNOWN zurückgegeben, da die Genauigkeitsü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');
}

Typenverweis

CompassHeading

Erfolgsmeldung, die den Kompasswinkelinhalt enthält.

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

ListeningOptions

Optionen zur Konfiguration der Kompass-Hörverhaltensweise.

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

Daten für Ereignisse bei Änderungen des Kopfzeilen-Textes.

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

AccuracyChangeEvent

Daten für Ereignisse bei Änderungen der Genauigkeit.

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

PermissionStatus

Zustand der Kompass-Plugin-Berechtigung.

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 Genauigkeitsstufen 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 Kompasszugriff.

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

Quelle der Wahrheit

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

Weitermachen von Getting Started

Wenn Sie " Getting Started um das Dashboard und die API-Operationen zu planen, verbinden Sie es mit Verwenden Sie @capgo/capacitor-compass für die native Fähigkeit in Using @capgo/capacitor-compass, API Übersicht für die Implementierungsdetails in API Übersicht, Einführung für die Implementierungsdetails in Einführung, API Schlüssel für die Implementierungsdetails in API Schlüssel, und Geräte für die Implementierungsdetails in Geräte.