地理位置

The geolocation 属性提供访问 Geolocation API 的入口点。

使用下表所示的内部槽创建 Geolocation 的实例：

The getCurrentPosition(successCallback, errorCallback, options) 方法步骤如下：

1. If this's relevant global object's associated Document is not fully active:
   1. 使用错误回调 errorCallback 并传入 POSITION_UNAVAILABLE。
   2. 终止此算法。
2. 请求一个位置，传入 this、successCallback, errorCallback, 和 options。

The watchPosition(successCallback, errorCallback, options) 方法步骤如下：

1. If this's relevant global object's associated Document is not fully active:
   1. 使用错误回调，传入 errorCallback 以及 POSITION_UNAVAILABLE。
   2. 返回 0。
2. 令 watchId 为一个 实现定义的 unsigned long，且其值大于零。
3. 将 watchId 附加到 this 的 [[watchIDs]]。
4. 请求一个位置，传入 this、successCallback, errorCallback, options，以及 watchId。
5. 返回 watchId。

When clearWatch() is invoked, the user agent MUST:

1. 移除 watchId 从 this 的 [[watchIDs]]。

要 请求位置， 传入一个 Geolocation geolocation，一个 PositionCallback successCallback，一个 PositionErrorCallback? errorCallback，一个 PositionOptions options，以及一个可选的 watchId：

1. 令 watchIDs 为 geolocation 的 [[watchIDs]]。
2. 令 document 为 geolocation 的 相关全局对象 的 关联的 Document。
3. 如果 document 不被 允许使用 “geolocation” 功能：
   1. 如果传入了 watchId，则 从 watchIDs 中移除 watchId。
   2. 使用错误回调，传入 errorCallback 和 PERMISSION_DENIED。
   3. 终止此算法。
4. 如果 geolocation 的 环境设置对象 是一个 非安全上下文：
   1. 如果传入了 watchId，则 从 watchIDs 中移除 watchId。
   2. 使用错误回调，传入 errorCallback 和 PERMISSION_DENIED。
   3. 终止此算法。
5. 如果 document 的 可见性状态 为 "hidden"，等待以下 页面可见性变更步骤 运行：
   1. 断言：document 的 可见性状态 为 "visible"。
   2. 继续下面的下一步。
6. 令 descriptor 为一个新的 PermissionDescriptor，其 name 为 "geolocation"。
7. 并行 执行：
   1. 将 permission 设为 请求使用 descriptor 的权限。
   2. 如果 permission 为 "denied"，则：
      1. 如果传入了 watchId，则 从 watchIDs 中移除 watchId。
      2. 使用错误回调，传入 errorCallback 和 PERMISSION_DENIED。
      3. 终止此算法。
   3. 等待 获取位置，传入 successCallback， errorCallback， options，以及 watchId。
   4. 如果未传入 watchId，则终止此算法。
   5. 当 watchIDs 包含 watchId 时：
      1. 等待地理位置发生显著变化。什么构成显著的地理位置变化由实现决定。用户代理 可以 对报告位置变化的频率施加速率限制。用户代理 必须 考虑将 设置模拟位置数据 视为显著变化。
      2. 如果 document 不是 完全激活 或 可见性状态 不是 "visible"，则返回到上一步并再次 等待地理位置发生显著变化。
         注意: 位置更新仅针对完全激活且可见的文档
      3. 等待 获取位置，传入 successCallback, errorCallback, options，以及 watchId。

要 获取位置，传入 PositionCallback successCallback，一个 PositionErrorCallback? errorCallback， PositionOptions options，以及一个可选的 watchId。

1. 如果传入了 watchId 并且 this 的 [[watchIDs]] 不包含 watchId，则终止此算法。
2. 令 acquisitionTime 为一个新的 EpochTimeStamp，表示现在。
3. 令 timeoutTime 为 acquisitionTime 与 options.timeout 的和。
4. 令 cachedPosition 为 this 的 [[cachedPosition]]。
5. 创建一个在 timeoutTime 到期的实现特定的 timeout 任务，在此期间它通过运行以下步骤尝试获取设备的位置：
   1. 令 permission 为 获取当前权限状态 的 "geolocation"。
   2. 如果 permission 为 "denied"：
      1. 停止 timeout。
      2. 执行 用户或系统拒绝权限 的失败情况步骤。
   3. 如果 permission 为 "granted"：
      1. 通过运行以下步骤检查是否应使用模拟位置：
         1. 令 emulatedPositionData 为 获取模拟位置数据，传入 this。
         2. 如果 emulatedPositionData 不为 null：
            1. 如果 emulatedPositionData 是一个 GeolocationPositionError：
               1. 使用错误回调，传入 errorCallback 和 emulatedPositionData.code。
               2. 终止此算法。
            2. 令 position 为 一个新的 GeolocationPosition，传入 emulatedPositionData、acquisitionTime 和 options.enableHighAccuracy。
            3. 在 geolocation 任务源 上排队一个任务，其步骤为 调用 successCallback，参数为 « position » 和 "report"。
            4. 终止此算法。
      2. 令 position 为 null。
      3. 如果 cachedPosition 不为 null，且 options.maximumAge 大于 0：
         1. 令 cacheTime 为 acquisitionTime 减去 options.maximumAge 成员的值。
         2. 如果 cachedPosition 的 timestamp 的值大于 cacheTime，且 cachedPosition 的 [[isHighAccuracy]] 等于 options.enableHighAccuracy：
            1. 在 geolocation 任务源 上排队一个任务，其步骤为 调用 successCallback，参数为 « cachedPosition » 和 "report"。
            2. 终止此算法。
      4. 否则，如果 position 不是 cachedPosition， 尝试从底层系统获取位置数据，获取时可选择考虑 options.enableHighAccuracy 的值。
      5. 如果在获取过程中 timeout 到期，或获取设备位置失败：
         1. 停止 timeout。
         2. 转到 处理失败。
         3. 终止此算法。
      6. 如果从系统获取位置数据成功：
         1. 令 positionData 为一个包含基于获取到的位置数据的以下名/值对的 映射：

            "accuracy"

            一个非负的 double， 表示以米为单位的 95% 置信水平的精度值。精度衡量测量坐标与真实位置的接近程度。

            "altitude"

            一个 double?， 表示相对于 [WGS84] 椭球体的海拔（以米为单位），若不可用则为 null。海拔衡量相对于海平面的高度。

            "altitudeAccuracy"

            一个非负的 double?， 表示海拔精度，若不可用则为 null，以米为单位表示 95% 的置信水平。海拔精度衡量测量海拔与真实海拔的接近程度。

            "heading"

            一个 double?， 表示以度为单位的航向，若不可用或设备静止则为 null。航向衡量设备相对于真北的移动方向。

            "latitude"

            一个 double， 表示使用 [WGS84] 坐标系的地球表面纬度坐标（以度为单位）。纬度衡量一个点相对于赤道的南北距离。

            "longitude"

            一个 double， 表示使用 [WGS84] 坐标系的地球表面经度坐标（以度为单位）。经度衡量一个点相对于本初子午线的东西距离。

            "speed"

            一个非负的 double?， 表示以米每秒为单位的速度，若不可用则为 null。速度衡量设备移动的快慢。

         2. 令 position 为 一个新的 GeolocationPosition，传入 positionData、acquisitionTime 和 options.enableHighAccuracy。
         3. 将 this 的 [[cachedPosition]] 设置为 position。
      7. 停止 timeout。
      8. 在 geolocation 任务源 上排队一个任务， 其步骤为 调用 successCallback，参数为 « position » 和 "report"。

   处理失败：

   • 如果获取位置失败，则根据匹配故障的条件执行以下之一：

     用户或系统拒绝权限：

     使用错误回调，传入 errorCallback 和 PERMISSION_DENIED。

     注意: 浏览器权限 与 操作系统权限

     超时到期：

     使用错误回调，传入 errorCallback 和 TIMEOUT。

     数据获取错误或任何其他原因：

     使用错误回调，传入 errorCallback 和 POSITION_UNAVAILABLE。

当被指示 使用错误回调 时，给定一个 PositionErrorCallback? callback 和一个 unsigned short code：

1. 如果 callback 为 null，则返回。
2. 令 error 为新创建的 GeolocationPositionError 实例，其 code 属性初始化为 code。
3. 在 geolocation 任务源 上排队一个任务，其步骤为 调用 callback，参数为 « error » 和 "report"。

The enableHighAccuracy 成员提供了一个提示， 表示应用希望接收尽可能精确的位置数据。 该成员的预期用途是允许应用告知实现它们不需要高精度的地理定位结果，因此实现 可以 避免使用 消耗大量电力的定位提供者（例如 GPS）。

The timeout 成员表示以毫秒为单位的最长等待时间， 在该时间之后 获取位置 操作便会过期。

The maximumAge 成员指示 Web 应用愿意接受一个其年龄不大于 指定毫秒数的缓存位置。

The coords 属性包含地理坐标。

The timestamp 属性表示获取设备地理位置的时间。

The toJSON() 方法返回 GeolocationPosition 对象的 JSON 表示。

GeolocationPosition 的实例 使用下表所示的内部槽创建：

下列 task source 由本规范定义。

The geolocation task source

本规范使用它在执行 位置请求 时排队非阻塞的 PositionCallback 和 PositionErrorCallback。

The latitude 和 longitude 属性表示位置，单位为度的实数，使用 [WGS84] 坐标系。

The accuracy 属性表示位置精度半径，单位为米。

The altitude 属性表示位置的高度， 以相对于 [WGS84] 椭球体的米为单位。

The altitudeAccuracy 属性表示以米为单位的海拔精度（例如 10 米）。

The heading 属性表示承载设备的行驶方向，以度为单位指定，且满足 0° ≤ heading < 360°，按顺时针方向相对于真北计。

The speed 属性表示承载设备当前速度的水平分量的大小，单位为米每秒。

The toJSON() 方法返回 GeolocationCoordinates 对象的 JSON 表示。

一个新的 GeolocationPosition 使用 map positionData、EpochTimeStamp timestamp 和 布尔值 isHighAccuracy 构造，执行以下步骤：

1. 令 coords 为新创建的 GeolocationCoordinates 实例。
2. 对于 positionData 中的每个 key → value：
   1. 将 coords 的名为 key 的属性设置为 value。
3. 返回一个新创建的 GeolocationPosition 实例，其 coords 属性初始化为 coords，其 timestamp 属性初始化为 timestamp，并将其 [[isHighAccuracy]] 内部槽设置为 isHighAccuracy。

PERMISSION_DENIED（数值 1）

请求位置 失败，因为用户拒绝了使用该 API 的权限，或请求是在 非安全上下文 发起的。

POSITION_UNAVAILABLE（数值 2）

获取位置 失败。

TIMEOUT（数值 3）

指定在 timeout 成员中的时间在用户代理成功 获取位置 之前已过期。

code 属性返回其被 初始化为 的值（可能的值见 10.1 常量）。

message 属性是对 code 属性的对开发者友好的文本描述。