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 AI-Werkzeugleiste hinzu, indem Sie den folgenden Befehl ausführen:

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

Verwenden Sie dann den folgenden Prompt:

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 darunter angegebenen Plattform-spezifischen Anweisungen:

bun add @capgo/capacitor-compass
bunx cap sync

Import

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

API Übersicht

getCurrentHeading

Der aktuelle Kompasswinkel in Grad erhältlich. Auf iOS wird der Winkel im Hintergrund aktualisiert und der neueste Wert zurückgegeben. Auf 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

Starten Sie die Abhörung von Kompasswinkeländerungen über Ereignisse. Dies startet die Kompass-Sensoren und emittiert Ereignisse vom 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

Stop auf Kompassänderungen hören. Dies stoppt die Kompasssensor und stoppt Ereignisse auszusenden.

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

await CapgoCompass.stopListening();

checkPermissions

Überprüfen Sie den aktuellen Berechtigungsstatus für den Zugriff auf Kompassdaten. Bei iOS überprüft dies die Standortberechtigung. Bei Android gibt es immer ‘erteilt’ zurück, 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. Bei iOS wird die Standortberechtigung angefordert (erforderlich für die Kopfdaten). Bei 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. Bei Android überwacht dies die Magnetometergenauigkeit und sendet Genauigkeitsänderungsereignisse aus. Entwickler können auf diese Ereignisse hören und eigene UI für Kalibrierungsanfragen implementieren. Bei iOS und Web tut dies 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

Stop die Kompassgenauigkeit überwachen. Dies beendet die Genauigkeitsüberwachung.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Ermitteln Sie derzeitige Kompassgenauigkeitsebene. Bei Android gibt es die derzeitige Magnetometer-Sensoren Genauigkeit zurück. Bei iOS und Web gibt es immer CompassAccuracy.UNKNOWN zurück, 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

Erfolgsmeldung, die den Kompassrichtungswert enthält.

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

ListeningOptions

Optionen zur Konfiguration der Kompass-Hörverhaltensweise.

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 von Änderungen der Kopfzeile.

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

AccuracyChangeEvent

Daten für Ereignisse von Änderungen der Genauigkeit.

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

PermissionStatus

Status 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 Genauigkeitsstufe des Kompasses.

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

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

Quellwahrheit

Diese Seite wurde generiert aus dem Plugin. src/definitions.ts Wiederholen Sie die Synchronisierung, wenn die öffentliche API sich im Hintergrund ändert.

Weitermachen von Getting Started

Wenn Sie Getting Started verwenden Getting Started Um das Dashboard und die API-Operationen zu planen, verbinden Sie es mit Mit @capgo/capacitor-compass Für die native Fähigkeit in Mit @capgo/capacitor-compass API Übersicht Für die Implementierungsdetails in API Übersicht Einführung Für die Implementierungsdetails in Einführung API Schlüssel Für die Implementierungsdetails in API Schlüssel und Geräte Für die Implementierungsdetails in Geräte.