地理位置 API

Baseline 已廣泛支援

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

安全上下文： 此功能僅在安全上下文（HTTPS）中可用，且支援此功能的瀏覽器數量有限。

地理定位 API 允許使用者在他們願意的情況下向 Web 應用程式提供其位置。出於隱私原因，系統會請求使用者許可來報告位置資訊。

希望使用 Geolocation 物件的 WebExtensions 必須在其 manifest 中新增 "geolocation" 許可權。使用者作業系統會在首次請求位置訪問時提示使用者允許。

概念與用法

您通常會在 Web 應用中檢索使用者的位置資訊，例如在地圖上標記他們的位置，或顯示與其位置相關的個性化資訊。

地理定位 API 透過呼叫 navigator.geolocation 來訪問；這將導致使用者的瀏覽器請求他們訪問其位置資料的許可權。如果他們同意，瀏覽器將使用裝置上可用的最佳功能來訪問此資訊（例如，GPS）。

開發者現在可以通過幾種不同的方式訪問此位置資訊

Geolocation.getCurrentPosition()：檢索裝置的當前位置。
Geolocation.watchPosition()：註冊一個處理函式，當裝置位置發生變化時，該函式將自動呼叫，並返回更新後的位置。

在這兩種情況下，方法呼叫最多可以接受三個引數

一個必需的成功回撥：如果位置檢索成功，回撥函式將執行，並將一個 GeolocationPosition 物件作為其唯一引數，提供位置資料的訪問許可權。
一個可選的錯誤回撥：如果位置檢索不成功，回撥函式將執行，並將一個 GeolocationPositionError 物件作為其唯一引數，提供有關發生錯誤的資訊。
一個可選的物件，用於提供位置資料檢索的選項。

有關地理定位使用的更多資訊，請參閱使用地理定位 API。

介面

Geolocation: 此 API 的主要類 — 包含用於檢索使用者當前位置、監視其位置變化以及清除先前設定的監視的方法。
GeolocationPosition: 表示使用者的位置。在對 Geolocation 中包含的某個方法進行成功呼叫後，在成功回撥中返回一個 GeolocationPosition 例項，其中包含一個時間戳和一個 GeolocationCoordinates 物件例項。
GeolocationCoordinates: 表示使用者位置的座標；GeolocationCoordinates 例項包含緯度、經度以及其他重要的相關資訊。
GeolocationPositionError: 在對 Geolocation 中包含的某個方法進行不成功呼叫後，在錯誤回撥中返回一個 GeolocationPositionError，其中包含一個錯誤程式碼和訊息。

其他介面的擴充套件

Navigator.geolocation: API 的入口點。返回一個 Geolocation 物件例項，所有其他功能都可以透過它訪問。

安全注意事項

地理定位 API 允許使用者以程式設計方式訪問安全上下文中的位置資訊。

訪問可能進一步受 Permissions Policy 指令 geolocation 控制。geolocation 的預設允許列表是 self，僅允許訪問同源巢狀框架中的位置資訊。透過設定 Permissions-Policy 響應頭以授予特定第三方源許可權來啟用第三方使用。

http

Permissions-Policy: geolocation=(self b.example.com)

然後必須將 allow="geolocation" 屬性新增到具有來自該源的 iframe 元素中。

html

<iframe src="https://b.example.com" allow="geolocation"></iframe>

地理定位資料可能會洩露裝置所有者不想共享的資訊。因此，當呼叫 Geolocation.getCurrentPosition() 或 Geolocation.watchPosition() 時（除非許可權狀態已經是 granted 或 denied），使用者必須透過提示明確授予許可權。授予許可權的有效期取決於使用者代理，可能是基於時間、會話或永久的。Permissions API 的 geolocation 許可權可用於測試是否 granted、denied 或 prompt（需要使用者確認提示）使用位置資訊的訪問許可權。