Compass Capacitor Plugin

Verwendung von @capgo/capacitor-compass

Capacitor Compass-Plugin-Schnittstelle zum Auslesen des Kompasskurses des Geräts.

Installieren

bun add @capgo/capacitor-compass
bunx cap sync

bunx cap sync kopiert den nativen code des Plugins in deine nativen Projekte. Nach jedem Plugin-Upgrade erneut ausführen.

Importieren

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

API auf einen Blick

Methode	Beschreibung
getCurrentHeading	Ruft den aktuellen Kompasskurs in Grad ab. Unter iOS wird der Kurs im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Unter Android wird der Kurs beim Methodenaufruf mittels Beschleunigungs- und Magnetometersensoren berechnet. Für Web nicht implementiert.
startListening	Beginne damit, über Events auf Änderungen des Kompasskurses zu hören. Dadurch werden die Kompasssensoren aktiviert und 'headingChange' Events ausgegeben.
stopListening	Stoppt das Abhören von Kompasskursänderungen. Dies deaktiviert die Kompasssensoren und stoppt das Emittieren von Events.
checkPermissions	Prüft den aktuellen Berechtigungsstatus für den Zugriff auf Kompassdaten. Unter iOS wird der Standort-Berechtigungsstatus geprüft. Unter Android wird immer 'granted' zurückgegeben, da keine Berechtigungen erforderlich sind.
requestPermissions	Fordert die Berechtigung für den Zugriff auf Kompassdaten an. Unter iOS wird die Standort-Berechtigung angefordert (erforderlich für Kursdaten). Unter Android wird dies sofort aufgelöst, da keine Berechtigungen erforderlich sind.
watchAccuracy	Startet die Überwachung der Kompassgenauigkeit. Unter Android wird die Magnetometersensorgenauigkeit überwacht und 'accuracyChange'-Events emittiert. Entwickler können auf diese Events hören und eigene UIs für Calibration Prompts implementieren. Unter iOS und Web bewirkt diese Methode nichts, da die Überwachung der Kompassgenauigkeit nicht verfügbar ist.
unwatchAccuracy	Überwachung der Kompassgenauigkeit stoppen. Dies beendet das Monitoring der Genauigkeit.
getAccuracy	Aktuelles Genauigkeitsniveau des Kompass abrufen. Auf Android wird die aktuelle Genauigkeit des Magnetometer-Sensors zurückgegeben. Auf iOS und Web wird immer CompassAccuracy.UNKNOWN zurückgegeben, da kein Genauigkeits-Monitoring verfügbar ist.

Beispiele

getCurrentHeading()

Ruft den aktuellen Kompasskurs in Grad ab. Auf iOS wird der Kurs im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Auf Android wird der Kurs beim Methodenaufruf mittels Beschleunigungs- und Magnetometersensoren berechnet. Für Web nicht implementiert.

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

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

startListening()

Aktiviert das Abhören von Kompasskursänderungen via Events. Dies startet die Kompasssensoren und emittiert 'headingChange' Events.

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

Stoppt das Abhören von Kompasskursänderungen. Dies deaktiviert die Kompasssensoren und stoppt das Emittieren von Events.

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

await CapgoCompass.stopListening();

checkPermissions()

Prüft den aktuellen Berechtigungsstatus für den Zugriff auf Kompassdaten. Auf iOS wird der Standort-Berechtigungsstatus geprüft. Auf 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()

Fordert die Berechtigung für den Zugriff auf Kompassdaten an. Auf iOS wird die Standort-Berechtigung angefordert (erforderlich für Kursdaten). Auf Android wird dies sofort aufgelöst, 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()

Startet die Überwachung der Kompassgenauigkeit. Auf Android wird die Magnetometersensorgenauigkeit überwacht und accuracyChange Events emittiert. Entwickler können auf diese Events hören und eigene UIs für Calibration Prompts implementieren. Auf iOS und Web bewirkt diese Methode nichts, da die Überwachung der Kompassgenauigkeit nicht verfügbar ist.

import { CapgoCompass, CompassAccuracy } 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
  }
});

Die obige Tabelle listet die 8 Kernmethoden auf. Listener- und Version-Helper sowie der vollständige Contract jeder Methode sind in der GitHub Repository.

Events abonnieren

addListener gibt ein Handle zurück. Rufe handle.remove() auf, wenn der Screen unmountet, oder CapgoCompass.removeAllListeners() auf, um alle Listener zu entfernen.

Vollständige Referenz

• GitHub Repository
• Dokumentation
• API-Referenz

Weiterlesen unter Verwendung von @capgo/capacitor-compass

Wenn du es nutzt Verwendung von @capgo/capacitor-compass um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-compass für die Implementierungsdetails in @capgo/capacitor-compass, Erste Schritte für die Implementierungsdetails in Erste Schritte, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung und API Schlüssel für die Implementierungsdetails in den API Keys.