ガイド
Compass を Capacitor で使う方法
@capgo/capacitor-compass を使用
デバイスのコンパスの向きを読み取るための Capacitor Compass Plugin インターフェース。
インストール
bun add @capgo/capacitor-compass
bunx cap sync
bunx cap sync プラグインのネイティブcodeをネイティブプロジェクトにコピーします。プラグインをアップグレードするたびに再度実行してください。
インポート
import { CapgoCompass } from '@capgo/capacitor-compass';
API の概要
| メソッド | 説明 |
|---|---|
getCurrentHeading |
現在のコンパスの方位を度数で取得します。iOS では方位はバックグラウンドで更新され、最新の値が返されます。Android では、メソッド呼び出し時に加速度センサーと磁力計を使って方位が計算されます。Web では実装されていません。 |
startListening |
イベント経由でコンパスの方位変化の監視を開始します。これによりコンパスセンサーが起動し、'headingChange' イベントが発行されます。 |
stopListening |
コンパスの方位変化の監視を停止します。これによりコンパスセンサーが停止し、イベントの発行も停止します。 |
checkPermissions |
コンパスデータへのアクセスに関する現在の権限ステータスを確認します。iOS では位置情報の権限ステータスを確認します。Android では権限が不要なため、常に 'granted' を返します。 |
requestPermissions |
コンパスデータへのアクセス権限をリクエストします。iOS では位置情報の権限（方位データに必要）をリクエストします。Android では権限が不要なため、即座に解決されます。 |
watchAccuracy |
コンパスの精度モニタリングを開始します。Android では磁力計の精度を監視し、accuracyChange イベントを発行します。開発者はこれらのイベントをリッスンして、キャリブレーションのプロンプト向けに独自の UI を実装できます。iOS と Web ではコンパス精度のモニタリングが利用できないため、このメソッドは何もしません。 |
unwatchAccuracy |
コンパスの精度モニタリングを停止します。これにより精度監視が停止します。 |
getAccuracy |
現在のコンパス精度レベルを取得します。Androidでは現在の磁力計センサー精度を返します。iOSとWebでは精度モニタリングが利用できないため、常にCompassAccuracy.UNKNOWNを返します。 |
例
getCurrentHeading()
現在のコンパスの方位を度数で取得します。iOS では方位はバックグラウンドで更新され、最新の値が返されます。Android では、メソッド呼び出し時に加速度センサーと磁力計を使って方位が計算されます。Web では実装されていません。
import { CapgoCompass } from '@capgo/capacitor-compass';
const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');
startListening()
イベント経由でコンパスの方位変化の監視を開始します。これによりコンパスセンサーが起動し、'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()
コンパスの方位変化の監視を停止します。これによりコンパスセンサーが停止し、イベントの発行も停止します。
import { CapgoCompass } from '@capgo/capacitor-compass';
await CapgoCompass.stopListening();
checkPermissions()
コンパスデータへのアクセスに関する現在の権限ステータスを確認します。iOS では位置情報の権限ステータスを確認します。Android では権限が不要なため、常に 'granted' を返します。
import { CapgoCompass } from '@capgo/capacitor-compass';
const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);
requestPermissions()
コンパスデータへのアクセス権限をリクエストします。iOS では位置情報の権限（方位データに必要）をリクエストします。Android では権限が不要なため、即座に解決されます。
import { CapgoCompass } from '@capgo/capacitor-compass';
const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
// Can now use compass
}
watchAccuracy()
コンパスの精度モニタリングを開始します。Android では磁力計の精度を監視し、accuracyChange イベントを発行します。開発者はこれらのイベントをリッスンして、キャリブレーションのプロンプト向けに独自の UI を実装できます。iOS と Web ではコンパス精度のモニタリングが利用できないため、このメソッドは何もしません。
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
}
});
上記の表は 8 つのコアメソッドの一覧です。リスナーやバージョンのヘルパー、各メソッドの完全なコントラクトについては、 GitHub リポジトリ.
イベントをリッスンする
addListener ハンドルを返します。画面がアンマウントされるときに handle.remove() 画面がアンマウントされるとき、または CapgoCompass.removeAllListeners() すべてのリスナーを解除します。
完全なリファレンス
「@capgo/capacitor-compass の使用方法」から続ける
使用している場合 @capgo/capacitor-compass を使用 ダッシュボードと API の運用を計画するには、これを次と連携させます @capgo/capacitor-compass @capgo/capacitor-compass での実装の詳細については、 スタートガイド スタートガイドの実装詳細については、 API の概要 「API の概要」の実装の詳細については、 はじめに はじめにの実装詳細、および API キー API Keys の実装詳細については、