地理位置

geolocation 属性为访问地理位置 API 提供了入口点。

Geolocation 的实例使用下表中的内部插槽进行创建

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

1. 如果 this 的 相关全局对象 的 关联 Document 未处于 完全活动状态
   1. 错误回调 errorCallback 并使用 POSITION_UNAVAILABLE。
   2. 终止此算法。
2. 请求位置，传入 this、successCallback、errorCallback 和 options。

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

1. 如果 this 的 相关全局对象 的 关联 Document 未处于 完全活动状态
   1. 错误回调，传入 errorCallback 和 POSITION_UNAVAILABLE。
   2. 返回 0。
2. 设 watchId 为一个 实现定义 的大于零的 unsigned long。
3. 追加 watchId 到 this 的 [[watchIDs]]。
4. 请求位置，传入 this、successCallback、errorCallback、options 和 watchId。
5. 返回 watchId。

当调用 clearWatch() 时，用户代理 必须

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，移除 watchId 从 watchIDs。
   2. 错误回调，传入 errorCallback 和 PERMISSION_DENIED。
   3. 终止此算法。
4. 如果 geolocation 的 环境设置对象 是一个 非安全上下文
   1. 如果传入了 watchId，移除 watchId 从 watchIDs。
   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，移除 watchId 从 watchIDs。
      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. 在 地理位置任务源 上 排队执行一个任务，其步骤为 调用 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. 在 地理位置任务源 上 排队执行一个任务，其步骤为 调用 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. 在 地理位置任务源 上 排队执行一个任务，其步骤为 调用 successCallback，传入参数 « position » 和 "report"。

   处理失败情况

   • 如果获取位置失败，根据匹配到的失败条件执行以下操作之一

     用户或系统拒绝权限

     错误回调，传入 errorCallback 和 PERMISSION_DENIED。

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

     超时过期

     错误回调，传入 errorCallback 和 TIMEOUT。

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

     错误回调，传入 errorCallback 和 POSITION_UNAVAILABLE。

当被指示 进行错误回调 时，需提供一个 PositionErrorCallback? callback 和一个 unsigned short code

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

enableHighAccuracy enableHighAccuracy 成员提供了一个提示，即应用希望接收最精确的位置数据。此成员的预期目的是允许应用告知实现其不需要高精度地理位置修正，因此实现 可以 避免使用消耗大量电能的地理位置提供商（例如 GPS）。

timeout timeout 成员表示 获取位置 过期前的最长时间，以毫秒为单位。

maximumAge maximumAge 成员表示 Web 应用愿意接受生存时间不超过指定时间（以毫秒为单位）的缓存位置。

coords 属性包含地理坐标。

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

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

GeolocationPosition 的实例使用下表中的内部插槽进行创建

本规范定义了以下 任务源。

地理位置任务源 (geolocation task source)

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

latitude 和 longitude 属性表示位置，以 [WGS84] 坐标系中以度为单位的实数指定。

accuracy 属性表示以米为单位的位置精度半径。

altitude 属性表示位置高度，指定为在 [WGS84] 椭球体之上的米数。

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

heading 属性表示宿主设备的移动方向，以度为单位，其中 0° ≤ heading < 360°，相对于真北顺时针计数。

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

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

一个新的 GeolocationPosition 的构造方式为：传入 映射 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 属性的开发者友好文本描述。