HTMLGeolocationElement

コンストラクター

HTMLGeolocationElement()

新しい HTMLGeolocationElement オブジェクトインスタンスを生成します。なお、このコンストラクターは直接呼び出されず、Document.createElement() などの DOM メソッドを通じて呼び出されます。

インスタンスプロパティ

親インターフェイスである HTMLElement から継承したプロパティもあります。

autolocate

論理値で、<geolocation> 要素がレンダリングされた際に、ブラウザーが直ちに位置情報をリクエストすべきかどうかを示します（事前にその権限を得ている場合）。<geolocation> 要素の autolocate 属性の値を反映します。

error 読取専用

データ取得に失敗した場合のエラー情報を表す GeolocationPositionError オブジェクトです。

initialPermissionStatus 読取専用

ページが初めて読み込まれた際の geolocation 機能に対する権限の状態を表す列挙値。

invalidReason 読取専用

<geolocation> 要素が無効である（ブロックされている）場合の理由を表す列挙値。

isValid 読取専用

<geolocation> 要素が有効か不正な状態（ブロックされている）かを示す論理値。

permissionStatus 読取専用

geolocation 機能の現在の権限の状態を表す文字列。

position 読取専用

位置データの取得に成功した場合に、ユーザーの位置を表す GeolocationPosition オブジェクトです。

watch

論理値で、ブラウザーが端末の位置が変更されるたびにユーザーの現在地データを継続的に更新すべきか、それとも一度だけ取得すべきかを示します。<geolocation> の watch 属性の値を反映します。

インスタンスメソッド

親インターフェイスである HTMLElement から継承したメソッドもあります。

イベント

親インターフェイスである HTMLElement から継承したイベントもあります。

location

位置データを受信したとき、または位置データリクエストが失敗した際のエラー情報を受信したときに発生します。

promptaction

ユーザーが <geolocation> 要素をアクティブ化し、表示されるダイアログから geolocation 権限を許可または拒否するオプションを選択するたびに発生します。

promptdismiss

ユーザーが <geolocation> 要素をアクティブ化し、結果として表示されるダイアログが「閉じる」ボタンまたは Esc キーの押下によって閉じられた際に発生します。

validationstatuschange

<geolocation>要素の isValid 値が変更されるたびに発生します。

解説

HTMLGeolocationElement インターフェイスは、<geolocation> 要素を表します。この要素は、ユーザーが位置データをページと共有することができる操作可能なコントロールを作成します。

ユーザーがコントロールを有効にすると、位置情報の共有許可を求めるダイアログボックスが表示されます。許可が与えられた場合、ブラウザーはバックグラウンドで位置情報 API を使用してユーザーの位置情報の取得を試みます。

デフォルトでは、ブラウザーは位置情報を一度だけリクエストします。これは、Geolocation.getCurrentPosition() メソッドが呼び出された場合と同様です。しかし、watch 属性が true に設定されている場合、ブラウザーは端末の位置が変化するたびにデータを更新します。これは、Geolocation.watchPosition() が呼び出される場合と同様です。

データリクエストが返ると、location イベントが発生します。これにより、データを取得して地図上に位置を表示するなど、例えば適切な対応をすることができます。

• 位置データが正常に取得された場合、HTMLGeolocationElement.position プロパティで利用可能となり、このプロパティには GeolocationPosition オブジェクトが含まれています。
• データ取得に失敗した場合、HTMLGeolocationElement.error プロパティにエラー情報が格納され、このプロパティには GeolocationPositionError オブジェクトが含まれます。

promptaction イベントと promptdismiss イベントは、<geolocation> ダイアログボックスに対するユーザーの操作に対応することができます。例えば、データへのアクセス権限を拒否した場合に、別の選択を依頼するといった対応が可能です。

ブロッカー が <geolocation> 要素に対して有効になっている場合、その要素は機能しなくなり（無効）、理由に応じて、一時的または永続的になります。無効状態かどうかを調べるには、HTMLGeolocationElement.isValid プロパティを問い合わせます。また、無効な理由を返すには HTMLGeolocationElement.invalidReason プロパティを使用します。考えられる理由の完全な一覧については、該当ページを参照してください。

例

基本的な使い方

<geolocation> 要素と関連付けられた HTMLGeolocationElement オブジェクトを使用して位置データを返す最小限の例については、基本的な例（ソースコード）および基本的な監視の例（ソースコード）を参照してください。

詳しい手順については、<geolocation> のリファレンスページを参照してください。

組み込み地図の例

この例では <geolocation> 要素を使用して現在の位置情報を取得し、Leaflet JS で描画された地図上にプロットします。また、非対応ブラウザーでは通常の <button> による代替手段で位置データを取得します。

HTML

<geolocation> 要素に autolocate 属性を記載することで、あらかじめ geolocation 権限が許可されている場合、ブラウザーが自動的に位置情報を取得しようと試みます。<geolocation>要素内部には、<geolocation> に対応していないブラウザー向けに位置情報のリクエストを可能にするための <button> の代替手段を内蔵しています。

<geolocation autolocate>
  <button id="fallback">位置情報を使用</button>
</geolocation>

次に、状態メッセージやエラーを表示するための <p> 要素を記述します。

<p id="status">状態:</p>

最後に、地図を描画するための <div> 要素を記述します。

<div id="map"></div>

JavaScript

スクリプトでは、まず状態の <p> 要素への参照を取得します。

const statusElem = document.querySelector("#status");

次に、typeof HTMLGeolocationElement === "function" を検査することで、<geolocation> 要素に対応しているかどうかを検出します。

if (typeof HTMLGeolocationElement === "function") {
  // <geolocation> に対応
} else {
  // <geolocation> に非対応、代替ボタンを使用
}

<geolocation> に対応している場合、if ブロックが実行されます。まず <geolocation> 要素への参照を取得します。

const geo = document.querySelector("geolocation");

次に location イベントリスナーを、結果として得られる HTMLGeolocationElement オブジェクトに追加し、位置データリクエストが返されるタイミングを検出します。データが正常に返された場合、HTMLGeolocationElement.position プロパティ経由でアクセスし、緯度と経度の値を取得します。これらの値をコンソールに記録した後、drawMap() 関数（後述）に HTMLGeolocationElement オブジェクトへの参照と共に渡すことで地図上にプロットします。データリクエストが失敗した場合、HTMLGeolocationElement.error プロパティ経由でエラーにアクセスし、エラーメッセージをコンソールに記録します。

geo.addEventListener("location", () => {
  if (geo.position) {
    console.log(
      `${geo.position.coords.latitude},${geo.position.coords.longitude}`,
    );
    drawMap(geo.position.coords.latitude, geo.position.coords.longitude, geo);
  } else if (geo.error) {
    console.log(geo.error.message);
  }
});

次に promptdismiss イベントと promptaction イベントのリスナーを、結果として得られる HTMLGeolocationElement オブジェクトに追加します。これにより、ユーザーが <geolocation> プロンプトを閉じる操作を行った場合、またはプロンプトからオプションを選択した場合にそれぞれ対応する関数を実行することができる。

geo.addEventListener("promptdismiss", notifyUserRetrySelection);
geo.addEventListener("promptaction", notifyUserGrantPermission);

最後に if ブロックでは、前述の 2 つのイベントリスナーで参照されている notifyUserRetrySelection() 関数と notifyUserGrantPermission() 関数を定義します。前者は状態の段落にメッセージを表示し、ユーザーにボタンを再度押して位置情報の許可をすることができるよう指示します。この場合、常に再試行を促す必要があるためです。後者は HTMLGeolocationElement.permissionStatus プロパティを使用して、権限の状態が denied または prompt かどうかを調べます。該当する場合は、ボタンを再度押して位置情報の許可を求めるようユーザーに依頼します。既に許可を与えている場合には、この確認は必要ありません。

function notifyUserRetrySelection() {
  statusElem.textContent =
    "再度「位置情報を使用」ボタンを押し、このサイトへの位置情報へのアクセス許可してください。";
}

function notifyUserGrantPermission() {
  if (geo.permissionStatus === "denied" || geo.permissionStatus === "prompt") {
    statusElem.textContent =
      "再度「位置情報を使用」ボタンを押し、このサイトへの位置情報へのアクセス許可してください。";
  }
}

<geolocation> に対応していない場合、else ブロックが実行されます。まず、代替となる <button> 要素への参照を取得します。

const fallback = document.querySelector("#fallback");