Langsung ke konten utama
@capgo/capacitor-compass Lokasi Open source

Kompas plugin Capacitor

Baca heading kompas perangkat dalam derajat dengan update berkelanjutan dan penanganan izin

Instal

bun add @capgo/capacitor-compass bunx cap sync
npm, pnpm atau yarn
  • npm install @capgo/capacitor-compass
  • pnpm add @capgo/capacitor-compass
  • yarn add @capgo/capacitor-compass

Panduan

Cara menggunakan Compass di Capacitor

Tes di perangkat

Download aplikasi Capgo, lalu scan QR code.

Pratinjau QR code plugin Compass

Menggunakan @capgo/capacitor-compass

Antarmuka Capacitor Compass Plugin untuk membaca heading kompas perangkat.

Instal

bun add @capgo/capacitor-compass
bunx cap sync

bunx cap sync menyalin code native plugin ke dalam proyek native Anda. Jalankan kembali setiap kali melakukan upgrade plugin.

Impor

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

Sekilas tentang API

Metode Deskripsi
getCurrentHeading Dapatkan heading kompas saat ini dalam derajat. Di iOS, heading diperbarui di background dan nilai terbaru dikembalikan. Di Android, heading dihitung saat method dipanggil menggunakan sensor accelerometer dan magnetometer. Tidak diimplementasikan di Web.
startListening Mulai mendengarkan perubahan heading kompas melalui event. Ini mengaktifkan sensor kompas dan mengirim event 'headingChange'.
stopListening Berhenti mendengarkan perubahan heading kompas. Ini akan menonaktifkan sensor kompas dan menghentikan pengiriman event.
checkPermissions Cek status izin saat ini untuk mengakses data kompas. Di iOS, ini memeriksa status izin lokasi. Di Android, ini selalu mengembalikan 'granted' karena tidak ada izin yang diperlukan.
requestPermissions Minta permission untuk mengakses data kompas. Di iOS, ini meminta permission lokasi (diperlukan untuk data heading). Di Android, ini langsung resolve karena tidak ada permission yang diperlukan.
watchAccuracy Mulai memantau akurasi kompas. Di Android, ini memantau akurasi magnetometer dan mengirim event accuracyChange. Developer dapat mendengarkan event ini dan membuat UI sendiri untuk prompt kalibrasi. Di iOS dan Web, method ini tidak melakukan apa pun karena pemantauan akurasi kompas tidak tersedia.
unwatchAccuracy Hentikan pemantauan akurasi kompas. Ini menghentikan pemantauan akurasi.
getAccuracy Dapatkan tingkat 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.

Contoh

getCurrentHeading()

Dapatkan heading kompas saat ini dalam derajat. Di iOS, heading diperbarui di background dan nilai terbaru 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 mengaktifkan sensor kompas dan mengirim 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 heading kompas. Ini akan menonaktifkan sensor kompas dan menghentikan pengiriman event.

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

await CapgoCompass.stopListening();

checkPermissions()

Cek status izin saat ini untuk mengakses data kompas. Di iOS, ini memeriksa status izin lokasi. Di Android, ini selalu mengembalikan 'granted' 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 permission untuk mengakses data kompas. Di iOS, ini meminta permission lokasi (diperlukan untuk data heading). Di Android, ini langsung resolve karena tidak ada permission 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. Di Android, ini memantau akurasi magnetometer dan mengirim event accuracyChange. Developer dapat mendengarkan event ini dan membuat UI sendiri untuk prompt kalibrasi. Di iOS dan Web, method 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
  }
});

Tabel di atas mencantumkan 8 metode inti. Helper listener, versi, dan kontrak lengkap setiap metode didokumentasikan di repositori GitHub.

Mendengarkan event

addListener mengembalikan sebuah handle. Panggil handle.remove() saat layar di-unmount, atau CapgoCompass.removeAllListeners() untuk menghapus semua listener.

Referensi lengkap

Lanjutkan dari bagian Menggunakan @capgo/capacitor-compass

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

FAQ

FAQ plugin Compass

Bagaimana cara menginstal plugin Compass di aplikasi Capacitor?

Jalankan "bun add @capgo/capacitor-compass" (atau "npm install @capgo/capacitor-compass"), lalu jalankan "bunx cap sync" agar proyek iOS dan Android mengenali code native. Impor dari "@capgo/capacitor-compass" di code aplikasi Anda.

Apakah @capgo/capacitor-compass bekerja dengan React, Vue, dan Angular?

Ya. Compass adalah paket Capacitor, jadi bekerja dengan framework web apa pun yang berjalan di dalam Capacitor, termasuk Ionic, React, Vue, Angular, Svelte, dan JavaScript murni.

Versi Capacitor mana yang didukung @capgo/capacitor-compass?

Plugin Capgo mengikuti versi mayor Capacitor: gunakan versi mayor plugin yang sesuai dengan versi mayor Capacitor Anda (contoh: plugin v8 dengan Capacitor 8). Tabel kompatibilitas di README GitHub mencantumkan versi yang masih di-maintain.

Apakah @capgo/capacitor-compass gratis dan open source?

Ya. Source code code tersedia untuk publik di GitHub pada https://github.com/Cap-go/capacitor-compass/ dan paketnya gratis dipasang dari npm. Laporan bug dan pull request sangat kami terima.

Bisakah saya memperbarui code yang menggunakan Compass tanpa review App Store?

Instalasi atau upgrade plugin akan mengubah native code, jadi butuh build store baru. Setelah itu, perubahan JavaScript, HTML, dan CSS yang memanggil plugin bisa langsung dikirim lewat live updates Capgo.

Rilis perubahan Compass tanpa menunggu review aplikasi

Setelah plugin ada di build store Anda, live updates Capgo akan mengirim perubahan JavaScript, HTML, dan CSS ke pengguna dalam hitungan menit.

Mulai dengan Capgo