【Geolocation】

浏览器定位 API（Geolocation API） 允许网页获取用户的地理位置。这个 API 在现代浏览器中得到广泛支持，可以通过 JavaScript 获取用户的经度、纬度等信息。它通常用于基于位置的服务，比如地图应用、天气预报、位置共享等功能。

1. 获取位置

浏览器定位 API 主要通过 navigator.geolocation 对象来访问。navigator.geolocation 提供了三个主要的方法：

• getCurrentPosition()
• watchPosition()
• clearWatch()

2. getCurrentPosition() 方法

getCurrentPosition() 方法用于获取用户的当前位置。该方法会一次性返回位置信息，并且是 异步 执行的，通常需要回调函数来处理结果。

语法

navigator.geolocation.getCurrentPosition(successCallback, errorCallback, options);

• successCallback：获取位置信息成功时调用的回调函数。它接收一个 Position 对象。
• errorCallback：获取位置信息失败时调用的回调函数。它接收一个 PositionError 对象。
• options：一个可选的配置对象，指定定位的额外设置（如精度、超时时间等）。

示例

navigator.geolocation.getCurrentPosition(
  function(position) {
    console.log("经度: " + position.coords.longitude);
    console.log("纬度: " + position.coords.latitude);
  },
  function(error) {
    console.error("获取位置失败: " + error.message);
  },
  {
    enableHighAccuracy: true, // 尝试高精度定位
    timeout: 5000,            // 超时时间设置为 5 秒
    maximumAge: 0             // 不使用缓存位置
  }
);

watchPosition() 方法

watchPosition() 方法用于持续跟踪用户的位置，并在位置发生变化时调用回调函数。这个方法返回一个 watch ID，可以通过这个 ID 来停止位置追踪。

语法

const watchId = navigator.geolocation.watchPosition(successCallback, errorCallback, options);

• successCallback：当位置变化时调用的回调函数。
• errorCallback：位置追踪失败时的回调函数。
• options：与 getCurrentPosition() 相同，用来控制定位的精度等。

示例

const watchId = navigator.geolocation.watchPosition(
  function(position) {
    console.log("当前位置：", position.coords.latitude, position.coords.longitude);
  },
  function(error) {
    console.error("位置追踪失败: " + error.message);
  },
  {
    enableHighAccuracy: true,
    timeout: 10000,
    maximumAge: 10000
  }
);

clearWatch() 方法

clearWatch() 方法用于停止由 watchPosition() 启动的位置追踪。需要传入通过 watchPosition() 返回的 watchId。

语法

navigator.geolocation.clearWatch(watchId);

示例

// 停止位置追踪
navigator.geolocation.clearWatch(watchId);

3. Position 对象

getCurrentPosition() 和 watchPosition() 的成功回调会返回一个 Position 对象，包含关于当前位置的详细信息。

Position 对象的属性

• coords：一个包含位置相关坐标信息的对象。
  • latitude：纬度（单位：度，-90 到 90）
  • longitude：经度（单位：度，-180 到 180）
  • altitude：海拔高度（单位：米，如果不可用则为 null）
  • accuracy：位置的精度（单位：米，表示经纬度的误差范围）
  • altitudeAccuracy：海拔的精度（单位：米，如果不可用则为 null）
  • heading：方向（单位：度，表示设备当前方向，如果不可用则为 null）
  • speed：速度（单位：米/秒，如果不可用则为 null）

示例：

navigator.geolocation.getCurrentPosition(function(position) {
  console.log(position.coords.latitude); // 纬度
  console.log(position.coords.longitude); // 经度
  console.log(position.coords.altitude);  // 海拔
});

4. PositionError 对象

如果定位请求失败，会返回一个 PositionError 对象。PositionError 对象包含一个 code 和一个 message，用来描述错误类型。

PositionError 对象的属性

• code：一个错误代码，表示失败的原因。可以是以下三种：
  • 1：用户拒绝访问位置。
  • 2：无法获取位置。
  • 3：请求超时。
• message：一个描述错误的消息字符串。

示例：

navigator.geolocation.getCurrentPosition(
  function(position) {
    console.log("成功获取位置");
  },
  function(error) {
    console.error("错误代码: " + error.code);
    console.error("错误信息: " + error.message);
  }
);

5. options 配置项

在调用 getCurrentPosition() 或 watchPosition() 时，可以传入一个 options 配置对象，来控制定位的行为。

常用的配置项

• enableHighAccuracy（默认为 false）：布尔值，是否要求获取高精度的位置。开启后，浏览器会尽量使用 GPS 定位等高精度方式。
• timeout（默认为 0）：数字值，最大等待时间（以毫秒为单位）。如果超时，回调函数会执行错误处理。
• maximumAge（默认为 0）：数字值，表示缓存的最大时间（以毫秒为单位）。如果缓存的位置信息未过期，则直接返回缓存位置。

示例：

navigator.geolocation.getCurrentPosition(
  function(position) {
    console.log("当前位置：", position.coords.latitude, position.coords.longitude);
  },
  function(error) {
    console.error("定位失败: " + error.message);
  },
  {
    enableHighAccuracy: true, // 请求高精度
    timeout: 5000,            // 超时时间 5 秒
    maximumAge: 0             // 不使用缓存的位置信息
  }
);

6. 位置权限

在获取地理位置之前，浏览器会提示用户授权。通常浏览器会显示一个权限请求对话框，要求用户选择是否允许访问其位置。

• 用户可以选择“允许”或“拒绝”。
• 如果用户拒绝或没有选择，定位请求会失败，并返回错误。
• 如果用户允许，则可以获取地理位置数据。

7. 示例：完整实现

以下是一个完整的示例，展示如何获取并显示用户的当前位置：

if (navigator.geolocation) {
  navigator.geolocation.getCurrentPosition(
    function(position) {
      const lat = position.coords.latitude;
      const lon = position.coords.longitude;
      console.log("用户的当前位置：");
      console.log(`纬度: ${lat}, 经度: ${lon}`);
    },
    function(error) {
      console.error("定位失败: " + error.message);
    },
    {
      enableHighAccuracy: true,
      timeout: 10000,
      maximumAge: 0
    }
  );
} else {
  console.error("浏览器不支持地理定位 API");
}

总结

属性/方法	描述
getCurrentPosition()	获取一次性的位置。
watchPosition()	持续追踪位置，位置变化时回调。
clearWatch()	停止通过 watchPosition 追踪的位置。
coords.latitude	获取纬度（单位：度）。
coords.longitude	获取经度（单位：度）。
coords.accuracy	获取位置的精度（单位：米）。
PositionError.code	错误代码，表示失败的原因（1 = 用户拒绝，2 = 无法获取，3 = 超时）。
PositionError.message	错误消息，描述失败原因。
enableHighAccuracy	是否要求高精度定位（默认 false）。
timeout	设置超时的时间（以毫秒为单位）。
maximumAge	设置缓存的位置最大有效时间（以毫秒为单位）。