Anleitung
So nutzt du Compass in Capacitor
Verwendung von @capgo/capacitor-compass
Capacitor Compass-Plugin-Schnittstelle zum Lesen der Kompassrichtung 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 die aktuelle Kompassrichtung in Grad ab. Auf iOS wird die Richtung im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Auf Android wird die Richtung beim Aufruf der Methode über Beschleunigungs- und Magnetometersensoren berechnet. Nicht für Web implementiert. |
startListening |
Höre auf Kompass-Richtungsänderungen über Events. Dies startet die Kompass-Sensoren und löst 'headingChange'-Events aus. |
stopListening |
Beendet das Lauschen auf Kompassänderungen. Dies stoppt die Kompasssensoren und das Auslösen von Events. |
checkPermissions |
Prüft den aktuellen Berechtigungsstatus für den Zugriff auf Kompassdaten. Auf iOS wird der Standortberechtigungsstatus geprüft. Auf Android wird immer 'granted' zurückgegeben, da keine Berechtigungen erforderlich sind. |
requestPermissions |
Berechtigung zum Zugriff auf Kompassdaten anfordern. Auf iOS wird dabei die Standortberechtigung angefordert (erforderlich für Heading-Daten). Auf Android wird dies sofort erfüllt, da keine Berechtigungen erforderlich sind. |
watchAccuracy |
Überwachung der Kompassgenauigkeit starten. Auf Android überwacht dies die Genauigkeit des Magnetometers und sendet accuracyChange-Events. Entwickler können auf diese Events hören und ihre eigene UI für Kalibrierungs-Prompts implementieren. Auf iOS und Web macht 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 die aktuelle Kompassrichtung in Grad ab. Auf iOS wird die Richtung im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Auf Android wird die Richtung beim Aufruf der Methode mithilfe von Beschleunigungs- und Magnetometersensoren berechnet. Auf Web nicht implementiert.
import { CapgoCompass } from '@capgo/capacitor-compass';
const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');
startListening()
Startet das Lauschen auf Änderungen der Kompassrichtung über Events. Dies aktiviert die Kompasssensoren und löst 'headingChange'-Events 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()
Beendet das Lauschen auf Änderungen der Kompassrichtung. Dies stoppt die Kompasssensoren und beendet das Auslösen 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 Status der Standortberechtigung 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()
Berechtigung zum Zugriff auf Kompassdaten anfordern. Auf iOS wird dabei die Standortberechtigung angefordert (erforderlich für Heading-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()
Überwachung der Kompassgenauigkeit starten. Auf Android überwacht dies die Genauigkeit des Magnetometers und sendet accuracyChange-Events. Entwickler können auf diese Events hören und ihre eigene UI für Kalibrierungs-Prompts implementieren. Auf iOS und Web macht 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
Weiter mit „Using @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.