Getting Started

Instalasi

Anda dapat menggunakan Pengaturan Bantu 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

Lalu 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 Pengaturan 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 Ringkasan

getCurrentHeading

Peroleh arah kompas dalam derajat. Di iOS, arah kompas diperbarui di latar belakang, dan nilai terbaru dikembalikan. Di Android, arah kompas dihitung ketika metode dipanggil menggunakan sensor accelerometer dan magnetometer. Belum diimplementasikan di 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

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

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

await CapgoCompass.stopListening();

checkPermissions

Periksa status izin saat ini untuk mengakses data kompas. Pada iOS, fungsi ini memeriksa status izin lokasi. Pada Android, fungsi ini selalu mengembalikan ‘diberikan’ karena tidak ada izin yang diperlukan.

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

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

requestPermissions

Minta izin untuk mengakses data kompas. Pada iOS, fungsi ini meminta izin lokasi (diperlukan untuk data arah). Pada Android, fungsi ini segera diselesaikan karena tidak ada izin yang diperlukan.

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

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

watchAccuracy

Mulai memantau akurasi kompas. Pada Android, fungsi ini memantau akurasi magnetometer dan mengemiskan event perubahan akurasi. Para pengembang dapat mendengarkan event ini dan menerapkan UI untuk permintaan kalibrasi. Pada iOS dan Web, fungsi ini tidak melakukan apa-apa karena pemantauan akurasi kompas tidak tersedia.

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

Berhenti memantau akurasi kompas. Hal ini menghentikan pemantauan akurasi.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

Dapatkan tingkat akurasi kompas saat ini. Pada Android, mengembalikan akurasi sensor magnetometer saat ini. Pada iOS dan Web, selalu mengembalikan CompassAccuracy.UNKNOWN karena pemantauan akurasi tidak tersedia.

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

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

Referensi Tipe

CompassHeading

Hasil berisi nilai arah kompas.

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

ListeningOptions

Pilihan 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 acara perubahan arah.

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

AccuracyChangeEvent

Data acara perubahan ketepatan.

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 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 publik API berubah di atas.

Lanjutkan dari Getting Started

Jika Anda menggunakan Mulai untuk merencanakan dashboard dan API operasi, hubungkannya dengan Menggunakan @capgo/capacitor-compass for the native capability in Using @capgo/capacitor-compass, untuk detail implementasi dalam Ringkasan API for the implementation detail in API Overview, untuk detail implementasi dalam Pendahuluan __CAPGO_KEEP_0__ Kunci untuk detail implementasi dalam API Kunci, dan for the implementation detail in API Keys, and Perangkat untuk detail implementasi di Perangkat.