Zum Hauptinhalt springen

Kompass Capacitor Plugin

Kompasskurs des Geräts in Grad auslesen, mit kontinuierlichen Updates und Permission-Handling

Installieren

bun add @capgo/capacitor-compass bunx cap sync
npm, pnpm oder yarn
  • npm install @capgo/capacitor-compass
  • pnpm add @capgo/capacitor-compass
  • yarn add @capgo/capacitor-compass

Anleitung

So nutzt du Compass in Capacitor

Auf dem Gerät testen

Lade die Capgo App herunter und scanne den QR code.

Compass-Plugin-Vorschau-QR code

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.

FAQ

Compass-Plugin-FAQ

Wie installiere ich das Compass-Plugin in einer Capacitor-App?

Führe &quot;bun add @capgo/capacitor-compass&quot; (oder &quot;npm install @capgo/capacitor-compass&quot;) aus und danach &quot;bunx cap sync&quot;, damit die iOS- und Android-Projekte die nativen code übernehmen. Importiere es aus &quot;@capgo/capacitor-compass&quot; in deiner App code.

Funktioniert @capgo/capacitor-compass mit React, Vue und Angular?

Ja. Compass ist ein Capacitor-Package und funktioniert daher mit jedem Web-Framework, das in Capacitor läuft, einschließlich Ionic, React, Vue, Angular, Svelte und reinem JavaScript.

Welche Capacitor-Version unterstützt @capgo/capacitor-compass?

Capgo Plugins folgen der Major-Version von Capacitor: Nutze die Plugin-Major-Version, die zu deiner Capacitor Major-Version passt (z. B. Plugin v8 bei Capacitor 8). Die Kompatibilitätstabelle im GitHub README listet die gepflegten Versionen auf.

Ist @capgo/capacitor-compass kostenlos und Open Source?

Ja. Der Quellcode von code ist öffentlich auf GitHub unter https://github.com/Cap-go/capacitor-compass/ einsehbar, und das Paket lässt sich kostenlos über npm installieren. Bug-Reports und Pull Requests sind willkommen.

Kann ich code, das Compass verwendet, ohne App-Store-Review aktualisieren?

Die Installation oder ein Upgrade des Plugins ändert den nativen code, weshalb ein neuer Store-Build nötig ist. Danach können JavaScript-, HTML- und CSS-Änderungen, die das Plugin aufrufen, sofort per Capgo Live Updates ausgeliefert werden.

Compass-Änderungen veröffentlichen, ohne auf die App-Prüfung zu warten

Sobald das Plugin in deinem Store-Build ist, bringt Capgo mit Live-Updates deine JavaScript-, HTML- und CSS-Änderungen in Minuten zu den Nutzern.

Starte mit Capgo