Getting Started

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer KI-Tool mithilfe der folgenden Befehl hinzu:

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

Verwenden Sie dann die folgende Anfrage:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten angegebenen Plattform-spezifischen Anweisungen:

bun add @capgo/capacitor-compass
bunx cap sync

Importieren

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

API Übersicht

getCurrentHeading

Der aktuelle Kompasswinkel in Grad erhalten. Bei iOS wird der Winkel im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Bei Android wird der Winkel bei Aufruf der Methode mithilfe von Beschleunigungssensor und Magnetometer berechnet. Nicht implementiert auf Web.

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

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

startListening

Der Kompasswinkel ändert sich lauschen. Dies startet die Kompass-Sensoren und emittiert Ereignisse von Typ „headingChange“.

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

Hören Sie auf, auf Änderungen des Kompasswinkels zu lauschen. Dies stoppt die Kompass-Sensoren und stoppt die Ereignis-Emission.

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

await CapgoCompass.stopListening();

checkPermissions

Überprüfen Sie den aktuellen Berechtigungsstatus für den Zugriff auf Kompass-Daten. Auf iOS überprüft dies die Standortberechtigung. Auf 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

Berechtigungen anfordern, um auf Kompass-Daten zuzugreifen. Auf iOS wird die Standortberechtigung angefordert (erforderlich für die Kopfdaten). Auf Android wird sofort gelö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

Starten Sie die Überwachung der Kompassgenauigkeit. Auf Android überwacht dies die Magnetometergenauigkeit und sendet Genauigkeitsänderungsereignisse. Entwickler können auf diese Ereignisse lauschen und eigene UI-Einblendungen für Kalibrierungsanfragen implementieren. Auf iOS und Web tut sich 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

Kompassgenauigkeit stoppen. Dies stoppt die Genauigkeitsüberwachung.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Aktuelle Kompassgenauigkeit abrufen. Bei Android-Geräten gibt es die aktuelle Magnetometer-Sensor-Genauigkeit zurück. 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

Ergebnis, das den Kompassrichtungswert enthält.

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

ListeningOptions

Optionen zur Konfiguration des Kompass-Hörverhaltens.

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 zum Ereignis des Kompass-Headings-Wechsels.

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

AccuracyChangeEvent

Daten zum Ereignis der Genauigkeitsänderung.

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

PermissionStatus

Zustand der Berechtigung für den Kompass-Plugin.

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 Kompassgenauigkeit.

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

Zustand der Genehmigung für den Zugriff auf den Kompass.

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

Quelle der Wahrheit

Diese Seite wird aus dem Plugin generiert. src/definitions.ts. Wenn sich die öffentliche API im Hintergrund ändert, starten Sie den Sync erneut.

Weitermachen von Getting Started

Wenn Sie verwenden Einstieg um das Dashboard und API-Operationen zu planen, verbinden Sie es mit Verwendung von @capgo/capacitor-compass for the native capability in Using @capgo/capacitor-compass, für die Implementierungsdetails in Übersicht über API for the implementation detail in API Overview, für die Implementierungsdetails in Einführung __CAPGO_KEEP_0__-Schlüssel für die Implementierungsdetails in API-Schlüssel und for the implementation detail in API Keys, and Getting Started to plan dashboard and __CAPGO_KEEP_0__ operations, connect it with für die Implementierungsdetails in Geräten.