Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command 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 memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

npm install @capgo/capacitor-compass
npx cap sync

Impor

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

Mulai cepat

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

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

Contoh: startListening

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);
});

Contoh: stopListening

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

await CapgoCompass.stopListening();

Kesalahan umum

• Izin: panggil checkPermissions() kemudian requestPermissions() saat dibutuhkan.
• Listeners: hapus handle saat screen unmount.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Ringkasan API

getCurrentHeading

Dapatkan heading kompas saat ini dalam derajat. Di iOS, heading diperbarui di background, dan nilai terbaru akan dikembalikan. Di Android, heading dihitung saat method dipanggil menggunakan sensor accelerometer dan magnetometer. Tidak diimplementasikan di Web.

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

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

startListening

Mulai mendengarkan perubahan heading kompas melalui event. Ini akan mengaktifkan sensor kompas dan memancarkan 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 memantau perubahan heading kompas. Ini menghentikan sensor kompas dan berhenti mengirim event.

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

await CapgoCompass.stopListening();

checkPermissions

Cek status izin saat ini untuk mengakses data kompas. Di iOS, ini mengecek status izin lokasi. Di Android, ini selalu mengembalikan ‘granted’ karena tidak diperlukan izin.

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

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

requestPermissions

Minta izin untuk mengakses data kompas. Di iOS, ini meminta izin lokasi (diperlukan untuk data heading). Di Android, ini langsung resolve karena tidak diperlukan izin.

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

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

watchAccuracy

Mulai memantau akurasi kompas. Di Android, ini memantau akurasi magnetometer dan mengirim event accuracyChange. Developer bisa mendengarkan event ini dan membuat UI sendiri untuk prompt kalibrasi. Di iOS dan Web, metode ini tidak melakukan apa pun karena pemantauan akurasi kompas tidak tersedia.

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

Berhenti memantau akurasi kompas. Ini akan menghentikan pemantauan akurasi.

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

await CapgoCompass.unwatchAccuracy();

getAccuracy

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

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

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

Referensi Tipe

CompassHeading

Hasil yang berisi nilai heading kompas.

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

ListeningOptions

Opsi untuk konfigurasi perilaku listening compass.

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 event untuk perubahan heading.

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

AccuracyChangeEvent

Data event untuk perubahan akurasi.

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

PermissionStatus

Status izin untuk plugin compass.

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

Status izin untuk akses compass.

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

Sumber Kebenaran

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan operasi dashboard dan API, hubungkan dengan Menggunakan @capgo/capacitor-compass untuk kapabilitas native saat menggunakan @capgo/capacitor-compass, Ringkasan API untuk detail implementasi di API Overview, Pendahuluan untuk detail implementasi di Introduction, Kunci API untuk detail implementasi di API Keys, dan Perangkat untuk detail implementasi di Devices.