地理位置 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（需要用户确认提示）使用位置信息的访问权限。