Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-compass` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

npm install @capgo/capacitor-compass
npx cap sync

Importieren

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

Quickstart

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

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

Beispiel: startListening

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);
});

Beispiel: stopListening

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

await CapgoCompass.stopListening();

Häufige Stolperfallen

• Berechtigungen: aufrufen checkPermissions() dann requestPermissions() bei Bedarf.
• Listener: Handles beim Unmounten von Screens entfernen.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

API Übersicht

getCurrentHeading

Gibt die aktuelle Kompassrichtung in Grad zurück. Unter iOS wird die Richtung im Hintergrund aktualisiert und der aktuellste Wert zurückgegeben. Unter Android wird die Richtung beim Aufruf der Methode mithilfe von Beschleunigungs- und Magnetometersensoren berechnet. Im Web nicht implementiert.

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

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

startListening

Startet das Abhören von Kompassänderungen via Events. Dadurch werden die Kompasssensoren aktiviert und ‚headingChange‘-Events emittiert.

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

Das Abhören von Kompass-Änderungen stoppen. Dies deaktiviert die Kompass-Sensoren und stoppt das Senden von Events.

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

await CapgoCompass.stopListening();

checkPermissions

Den aktuellen Berechtigungsstatus für den Zugriff auf Kompass-Daten prüfen. 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

Berechtigung für den Zugriff auf Kompass-Daten anfordern. Auf iOS wird die Standort-Berechtigung angefordert (notwendig für Heading-Daten). Auf Android wird dies sofort abgeschlossen, 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

Die Kompass-Genauigkeit überwachen. Auf Android wird die Magnetometer-Genauigkeit überwacht und accuracyChange-Events gesendet. 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 Kompass-Genauigkeit dort 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
  }
});

unwatchAccuracy

Das Monitoring der Kompassgenauigkeit beenden. Damit wird die Überwachung der Genauigkeit gestoppt.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Die aktuelle Kompassgenauigkeit abrufen. Auf Android wird die Genauigkeit des Magnetometers zurückgegeben. Auf iOS und Web wird immer CompassAccuracy.UNKNOWN zurückgegeben, da dort kein Accuracy-Monitoring verfügbar ist.

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

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

Typreferenz

CompassHeading

Ergebnis, das den Kompasskurs enthält.

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

ListeningOptions

Optionen zum Konfigurieren des Listening-Verhaltens des Compass.

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

Event-Daten für Heading-Change-Events.

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

AccuracyChangeEvent

Event-Daten für Accuracy-Change-Events.

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

PermissionStatus

Berechtigungsstatus des Compass-Plugins.

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 Genauigkeitsstufe des Compass.

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

Berechtigungsstatus für den Kompass-Zugriff.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit Verwendung von @capgo/capacitor-compass für die native Funktionalität bei der Nutzung von @capgo/capacitor-compass, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.