Html 简明教程

HTML - Geolocation API

Web 应用程序中使用 HTML 地理位置 API 访问用户的地理位置信息。大多数现代浏览器和移动设备都支持地理位置 API。

JavaScript 可以捕获用户的经度和纬度并将其发送到后端 Web 服务器上,并执行基于位置的信息任务,如找到本地业务或在地图上显示用户的当前位置。

Syntax

var geolocation = navigator.geolocation;

地理位置对象是一个允许小组件检索有关设备地理位置信息的服务对象。

Geolocation Methods

地理位置对象提供以下方法:

Method

Description

getCurrentPosition()

此方法检索用户的当前地理位置。

watchPosition()

此方法检索有关设备当前地理位置的定期更新信息。

clearWatch()

此方法取消正在进行的 watchPosition 调用。

以下是一个使用上述任一方法的示例代码:

function getLocation() {
   var geolocation = navigator.geolocation;
   geolocation.getCurrentPosition(showLocation, errorHandler);

   watchId = geolocation.watchPosition(showLocation, errorHandler, {
      enableHighAccuracy: true,
      timeout: 5000,
      maximumAge: 0
  });

  navigator.geolocation.clearWatch(watchId);
}

在这里,showLocation 和 errorHandler 是一些回调方法,它们会像下一节中解释的那样,被用来获取实际位置,以及在有错误的时候处理错误。

Location Properties

地理位置方法 getCurrentPosition()getPositionUsingMethodName() 指定了检索位置信息回调方法。这些方法会与一个对象位置异步调用,该位置储存了完整的位置信息。

Position 对象指定了设备当前的地理位置。位置被表示成一组地理坐标,以及关于航向和速度的信息。

下表描述了位置对象的属性。对于可选属性,如果系统无法提供一个值,那么属性的值就会被设置为 null。

Property

Type

Description

coords

objects

指定设备的地理位置。位置被表示成一组地理坐标,以及关于航向和速度的信息。

coords.latitude

Number

指定以十进制度为单位的纬度估计。值范围是 [-90.00, +90.00]。

coords.longitude

Number

指定以十进制度为单位的经度估计。值范围是 [-180.00, +180.00]。

coords.altitude

Number

[可选] 指定以米为单位,高于 WGS 84 椭球仪面的海拔高度估计。

coords.accuracy

Number

[可选] 指定维度和经度估计的精度,以米为单位。

coords.altitudeAccuracy

Number

[可选] 指定海拔估计的精度,以米为单位。

coords.heading

Number

[可选] 指定设备当前运动方向,以顺时针相对于真北为计算方式,单位为度。

coords.speed

Number

[可选] 指定设备当前的地面速度,以米/秒为单位。

timestamp

date

指定在检索位置信息和创建位置对象时的时间。

下面是一个示例代码,它利用了位置对象。在这里,showLocation 方法是一个回调方法:

function showLocation( position ) {
  var latitude = position.coords.latitude;
  var longitude = position.coords.longitude;
  ...
}

Handling Errors

地理位置很复杂,很有必要抓住任何错误并巧妙地处理它。

地理位置方法 getCurrentPosition() 和 watchPosition() 利用了报错处理回调方法,该方法给出了位置错误对象。这个对象有以下两个属性:

Property

Type

Description

code

Number

包含一个错误数字代码。

message

String

包含一个错误的人类可读描述。

下表描述了在位置错误对象中返回的错误代码。

Code

Constant

Description

0

UNKNOWN_ERROR

方法由于未知错误而无法检索设备的位置。

1

PERMISSION_DENIED

方法无法获取设备的位置,因为应用程序没有使用位置服务的权限。

2

POSITION_UNAVAILABLE

无法确定设备的位置。

3

TIMEOUT

方法无法在指定的最大超时时间间隔内检索位置信息。

以下是利用 PositionError 对象的示例代码。此处 errorHandler 方法是一种回调方法:

function errorHandler( err ) {
   if (err.code == 1) {
      // access is denied
   }
   ...
}

Position Options

以下是 getCurrentPosition() 方法的实际语法:

getCurrentPosition(callback, ErrorCallback, options)

这里的第三个参数是 PositionOptions 对象,它指定了一组用于检索设备地理位置的选项。

以下是可指定为第三个参数的选项:

Property

Type

Description

enableHighAccuracy

Boolean

指定小工具是否希望接收到最准确的位置估计值。默认情况下,此值为 false。

timeout

Number

timeout 属性是您的 Web 应用程序愿意等待位置的毫秒数。

maximumAge

Number

指定缓存位置信息的过期时间(以毫秒为单位)。

以下是一个示例代码,它演示了如何使用上述方法:

function getLocation() {
   var geolocation = navigator.geolocation;
   geolocation.getCurrentPosition(showLocation,
                                  errorHandler,
                                  {maximumAge: 75000});
}

Examples of HTML Geolocation API

以下是一些显示如何访问 HTML 中的地理位置的示例。

Get Current Location

以下代码显示了如何使用 JavaScript 和 HTML 访问设备的当前位置。

<!DOCTYPE html>
<html>
<head>
      <title>
         Geolocation API Example
      </title>
</head>
<body>

   <h2>Geolocation API Example</h2>
   <p id="demo">
      Click the button to get your coordinates:
   </p>
   <button onclick="getLocation()">
      Show Location
   </button>

   <script>
      var x = document.getElementById("demo");

      function getLocation() {
         if (navigator.geolocation) {
            navigator.geolocation.getCurrentPosition(showPosition);
         } else {
            x.innerHTML =
            "Geolocation is not supported by this browser.";
         }
      }

      function showPosition(position) {
         x.innerHTML = "Latitude: " + position.coords.latitude +
         "<br>Longitude: " + position.coords.longitude;
      }

   </script>

</body>
</html>

Error Handling in Geolocation

以下代码显示了如何在用户访问位置时处理潜在的错误。

<!DOCTYPE html>
<html>
<head>
      <title>Geolocation API Example</title>
</head>

<body>
   <h2>Geolocation API Example</h2>
   <p id="demo">
      Turn off location service of your device,
      See how the error is handled.
   </p>
   <button onclick="getLocation()">
      Show Location
   </button>

   <script>
      var x = document.getElementById("demo");

      function getLocation() {
         if (navigator.geolocation) {
            navigator.geolocation.getCurrentPosition(showPosition, showError);
         } else {
            x.innerHTML = "Geolocation is not supported by this browser.";
         }
      }

      function showPosition(position) {
         x.innerHTML = "Latitude: " + position.coords.latitude +
         "<br>Longitude: " + position.coords.longitude;
      }

      function showError(error) {
         switch(error.code) {
            case error.PERMISSION_DENIED:
                  x.innerHTML =
                  "User denied the request for Geolocation.";
                  break;
            case error.POSITION_UNAVAILABLE:
                  x.innerHTML =
                  "Location information is unavailable.";
                  break;
            case error.TIMEOUT:
                  x.innerHTML =
                  "The request to get user location timed out.";
                  break;
            case error.UNKNOWN_ERROR:
                  x.innerHTML =
                  "An unknown error occurred.";
                  break;
         }
      }
   </script>

</body>
</html>

Supported Browsers