メインコンテンツへスキップ
@capgo/capacitor-compass 位置情報 オープンソース

コンパス Capacitor プラグイン

継続的な更新と権限管理を備えた、デバイスのコンパス方位(度)の取得

インストール

bun add @capgo/capacitor-compass bunx cap sync
npm、pnpm、または yarn
  • npm install @capgo/capacitor-compass
  • pnpm add @capgo/capacitor-compass
  • yarn add @capgo/capacitor-compass

ガイド

Compass を Capacitor で使う方法

実機でテストする

Capgo アプリをダウンロードして、QR code をスキャンしてください。

Compass プラグインのプレビューQR code

@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 の実装詳細については、

よくある質問

Compass プラグイン FAQ

Capacitor アプリに Compass プラグインをインストールするには?

"bun add @capgo/capacitor-compass" (または "npm install @capgo/capacitor-compass") を実行し、続けて "bunx cap sync" を実行すると、iOS と Android プロジェクトがネイティブ code を読み込みます。アプリの code で "@capgo/capacitor-compass" からインポートしてください。

@capgo/capacitor-compass は React、Vue、Angular で動作しますか?

はい。Compass は Capacitor パッケージなので、Ionic、React、Vue、Angular、Svelte、素の JavaScript など、Capacitor 内で動く Web フレームワークならどれでも動作します。

@capgo/capacitor-compass はどの Capacitor バージョンをサポートしていますか?

Capgo プラグインは Capacitor のメジャーバージョンに合わせています。使用している Capacitor のメジャーバージョンに一致するプラグインのメジャーバージョンを使ってください (例: Capacitor 8 ならプラグイン v8)。GitHub の README にある互換性テーブルに、メンテナンス中のバージョンが記載されています。

@capgo/capacitor-compass は無料でオープンソースですか?

はい。ソースcodeは https://github.com/Cap-go/capacitor-compass/ のGitHubで公開されており、npmから無料でインストールできます。バグ報告やプルリクエストをお待ちしています。

Compass を使用している code を、App Store のレビューなしで更新できますか?

プラグインのインストールやアップグレードはネイティブの code を変更するため、新しいストアビルドが必要です。その後は、プラグインを呼び出す JavaScript、HTML、CSS の変更を Capgo Live Updates で即座に配信できます。

アプリのレビューを待たずにコンパスの変更をリリース

プラグインをストア用ビルドに組み込めば、Capgo live updates で JavaScript、HTML、CSS の変更を数分でユーザーに配信できます

Capgo から始める