# 端末のオリエンテーション検知 プラグイン

{% hint style="danger" %}
非推奨プラグイン (Cordova 9.0 以降)\
 cordova-plugin-device-orientation の移行については、[こちら](https://blog.phonegap.com/migrating-from-the-cordova-device-orientation-plugin-8442b869e6cc)を参照ください。 
{% endhint %}

テスト環境 ( バージョン番号 ) : [1.0.7](https://github.com/apache/cordova-plugin-device-orientation/releases/tag/1.0.7)

{% hint style="info" %}
このプラグインの詳細は、 [こちらの原文 ( GitHub )](https://github.com/apache/cordova-plugin-device-orientation) をご確認ください。
{% endhint %}

このプラグインを使用して、端末のコンパスにアクセスします。コンパスは、端末が指し示す方向・方位を検知するセンサーの `1` 種です。通常、端末の上部最先端を起点として、`0` から `359.99` 度の角度で方位を示します。`0` は、北を意味します。

このプラグインは、グローバルな `navigator.compass` オブジェクトを定義します。 グローバルスコープでは、`deviceready` イベントの発火後まで使用できません。

```javascript
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.compass);
}
```

## プラグイン ID

```javascript
cordova-plugin-device-orientation
```

## プラグインの追加方法 ( Monaca 上での処理 )

このプラグインを使用する場合には、Monaca クラウド IDE の \[ Cordova プラグインの管理 ] 上で、`Device Orientation` プラグインを[有効](/products_guide/monaca_ide/dependencies/cordova_plugin.md#cordova-puraguin-noinpto)にします。

## サポート対象のプラットフォーム

* Android
* iOS

## メソッド

* navigator.compass.getCurrentHeading
* navigator.compass.watchHeading
* navigator.compass.clearWatch

### navigator.compass.getCurrentHeading

コンパスの現在の方位を取得します。コンパスの方位は、`CompassHeading` オブジェクトから取得できます。また、このオブジェクトは、`compassSuccess` コールバック関数で使用します。

```javascript
navigator.compass.getCurrentHeading(compassSuccess, compassError);
```

#### 例

```javascript
function onSuccess(heading) {
    alert('Heading: ' + heading.magneticHeading);
};

function onError(error) {
    alert('CompassError: ' + error.code);
};

navigator.compass.getCurrentHeading(onSuccess, onError);
```

### navigator.compass.watchHeading

端末の方位を、一定の間隔で取得します。方位情報を取得するたび、`headingSuccess` コールバック関数が実行されます。

返された watch ID を使用して、コンパスの監視状態を確認できます。navigator.compass を停止するときには、`navigator.compass.clearWatch` に、この watchID を渡します。

```javascript
var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);
```

`compassOptions` には、次のパラメーターを使用できます

* **frequency**: 方位情報の取得頻度です ( ミリ秒単位、デフォルトでは100 )。 *(Number)*
* **filter**: watchHeadingの成功時のコールバック関数を実行するか否かの しきい値

  となる、角度の変化です。値を設定した場合、\**frequency*\*は無視されます。 *(Number)*

#### 例

```javascript
function onSuccess(heading) {
    var element = document.getElementById('heading');
    element.innerHTML = 'Heading: ' + heading.magneticHeading;
};

function onError(compassError) {
    alert('Compass error: ' + compassError.code);
};

var options = {
    frequency: 3000
}; // Update every 3 seconds

var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
```

#### iOS 特有の動作

iOS では、1 度に 1 つの `watchHeading` のみ有効です。`watchHeading` で filter を設定した場合、`getCurrentHeading` または `watchHeading` のいずれを呼び出したときでも、設定された filter 値を使用して、方位の変化を特定します。これは、filter を使用した方位の監視の方が、時間の間隔 ( frequency ) を使用するより、有効な方法のためです。

#### Android 特有の動作

* `filter` は使用できません。

### navigator.compass.clearWatch

watchID パラメーターを使用して、方位の監視を停止します。

```javascript
navigator.compass.clearWatch(watchID);
```

* **watchID**: `navigator.compass.watchHeading` が返す ID

#### 例

```javascript
var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

// ... later on ...

navigator.compass.clearWatch(watchID);
```

### CompassHeading

`CompassHeading` オブジェクトは、`compassSuccess` コールバック関数に渡されます。

#### プロパティ

* **magneticHeading**: ある瞬間の磁方位 ( 磁北を基準 )。0 から 359.99度の方位角で表します。 *(Number)*
* **trueHeading**: ある瞬間の真方位 ( 真北を基準 )。0 から 359.99度の方位角で表します。負の値は、真方位の値が定まっていないことを示します。*(Number)*
* **headingAccuracy**: 取得した磁方位と真方位との角度の差 ( 偏角 )*(Number)*
* **timestamp**: 方位を取得した時間 *(DOMTimeStamp)*

#### Android 特有の動作

* `trueHeading` は使用できません。`magneticHeading`と同じ値が返ってきます。
* `trueHeading` と `magneticHeading`が同じ値になるため、`headingAccuracy` は、常に 0 となります。

#### iOS 特有の動作

* 位置情報サービスを有効にした場合のみ、`navigator.geolocation.watchLocation()`

  経由で、`trueHeading` プロパティを取得できます。

### CompassError

エラーが発生した場合、`CompassError` オブジェクトが `compassError` コールバック関数に渡されます。

#### プロパティ

* **code**: 次のエラーコードのいずれか

#### 定数

* `CompassError.COMPASS_INTERNAL_ERR`
* `CompassError.COMPASS_NOT_SUPPORTED`

関連項目:

* [サードパーティー製プラグイン](/reference/third_party_phonegap.md)
* [基本プラグイン](/reference/core-cordova-plugins.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ja.docs.monaca.io/reference/core-cordova-plugins/cordova_9.0/device-orientation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.