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

Dann verwenden Sie folgenden Befehl:

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 die darunter angegebenen Plattform-spezifischen Anweisungen befolgen.

bun add @capgo/capacitor-compass
bunx cap sync

Importieren

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

API Übersicht

getCurrentHeading

Ermitteln Sie den aktuellen Kompasswinkel in Grad. Bei iOS wird der Winkel im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Bei Android wird der Winkel mithilfe von Beschleunigungssensor und Magnetometer berechnet, wenn die Methode aufgerufen wird. Nicht implementiert auf Web.

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

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

startListening

Starten Sie die Abhörung von Kompasswinkeländerungen über Ereignisse. Dies startet die Kompass-Sensoren und sendet 'headingChange'-Ereignisse.

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ört 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üfe 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

Berechtigung zum Zugriff auf Kompass-Daten anfordern. Auf iOS wird die Standortberechtigung angefordert (erforderlich für die Winkeldaten). Auf Android wird diese Methode 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

Überwache die Genauigkeit des Kompasses. Auf Android überwacht dies die Magnetometergenauigkeit und emittiert Genauigkeitsänderungsereignisse. Entwickler können auf diese Ereignisse lauschen und eigene UI-Ansagen für Kalibrierungsanfragen implementieren. Auf iOS und Web tut 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
  }
});

unwatchAccuracy

Kompassgenauigkeit beenden. Dies beendet die Genauigkeitsüberwachung.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Aktuelle Kompassgenauigkeit abrufen. Bei Android gibt es die aktuelle Magnetometer-Sensoren Genauigkeit zurück. Bei iOS und Web wird immer CompassAccuracy.UNKNOWN als Genauigkeitsüberwachung zurückgegeben.

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

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

Typenreferenz

CompassHeading

Ergbnis mit dem Kompasswinkelinhalt.

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

ListeningOptions

Einstellungen für die 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 für Ereignisse der Kopfänderung.

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

AccuracyChangeEvent

Daten für Ereignisse der Genauigkeitsänderung.

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

PermissionStatus

Berechtigungsstatus 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

Genauigkeitsstufen für 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

Zugriffsstatus für Compass.

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

Quellwahrheit

Diese Seite wurde aus dem Plugin generiert. src/definitions.tsRe-run the Sync, wenn die öffentliche API upstream geändert wird.

Weiter mit der Einführung

Wenn Sie das Plugin verwenden Anfangsphase um das Dashboard und API-Operationen zu planen, verbinden Sie es mit Mit @capgo/capacitor-compass zur nativen Fähigkeit in Mit @capgo/capacitor-compass, API-Übersicht zur Implementierungsdetails in API-Übersicht, Einführung zur Implementierungsdetails in Einführung, API-Schlüssel zur Implementierungsdetails in API-Schlüssel und Geräte für die Implementierungsdetails in Geräten.