Mulai Menggunakan

Install

Anda dapat menggunakan Setup Bantuan AI kami untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI Anda menggunakan perintah berikut:

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

Maka gunakan prompt berikut:

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

Jika Anda lebih suka Setup Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

bun add @capgo/capacitor-compass
bunx cap sync

Import

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

API Pengantar

getCurrentHeading

Beri arah kompas saat ini dalam derajat. Pada iOS, arah kompas diperbarui di latar belakang, dan nilai terbaru dikembalikan. Pada Android, arah kompas dihitung ketika metode dipanggil menggunakan sensor accelerometer dan magnetometer. Belum diimplementasikan pada Web.

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

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

startListening

Mulai mendengarkan perubahan arah kompas melalui event. Fungsi ini memulai sensor kompas dan mengirimkan event ‘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

Hentikan mendengarkan perubahan arah kompas. Fungsi ini menghentikan sensor kompas dan menghentikan emisi event.

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

await CapgoCompass.stopListening();

checkPermissions

Check the current permission status for accessing compass data. On iOS, this checks location permission status. On Android, this always returns ‘granted’ as no permissions are required.

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

const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);

requestPermissions

Request permission to access compass data. On iOS, this requests location permission (required for heading data). On Android, this resolves immediately as no permissions are required.

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

const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
  // Can now use compass
}

watchAccuracy

Start monitoring compass accuracy. On Android, this monitors the magnetometer accuracy and emits accuracyChange events. Developers can listen to these events and implement their own UI for calibration prompts. On iOS and Web, this method does nothing as compass accuracy monitoring is not available.

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

Hentikan pemantauan akurasi kompas. Hal ini menghentikan pemantauan akurasi.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Get the current compass accuracy level. On Android, returns the current magnetometer sensor accuracy. On iOS and Web, always returns CompassAccuracy.UNKNOWN as accuracy monitoring is not available.

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

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

Referensi Tipe

CompassHeading

Nilai arah kompas yang terkandung dalam hasil.

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

ListeningOptions

Opsi untuk mengonfigurasi perilaku mendengarkan kompas.

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

Data peristiwa perubahan heading.

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

AccuracyChangeEvent

Data peristiwa perubahan akurasi.

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

PermissionStatus

Status izin untuk plugin kompas.

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

Konstanta tingkat akurasi kompas.

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

Status izin untuk akses kompas.

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

Sumber Kebenaran

Halaman ini dihasilkan dari plugin’s src/definitions.tsRe-run sinkronisasi ketika API publik berubah di atas.

Teruskan dari Mulai Menggunakan

Jika Anda menggunakan Mulai Berjalan untuk merencanakan dashboard dan API operasi, hubungkannya dengan Menggunakan @capgo/capacitor-compass untuk kemampuan asli dalam Menggunakan @capgo/capacitor-compass, Ringkasan API untuk detail implementasi dalam Ringkasan API, Pendahuluan untuk detail implementasi dalam Pendahuluan, Kunci API untuk detail implementasi dalam Kunci API, dan Perangkat Untuk detail implementasi di Perangkat.