HTML5 简介(五):地理位置 API

HTML5 允许你通过 Geolocation API 获取用户的地理位置。

Geolocation API介绍

请求用户许可

HTML5 中的地理位置是通过经纬度提供的;为了获得用户的许可,应该首先执行以下 JavaScript 语句:

navigator.geolocation.getCurrentPosition(on_success, on_error, options);

getCurrentPosition包含三个参数,前两个为函数名,第三个为一个对象。其中只有第一个是必须的。当你执行上面的 JavaScript 语句后,浏览器通常会弹出一个提示,询问用户是否允许网站跟踪位置信息;同时getCurrentPosition函数会立即返回。如果用户选择了允许,则会执行上述on_success函数,这时你才真正得到位置信息(这就是这件事情为什么要分两步的原因——用户需要一定时间才能对请求作出反应,同时地理位置信息可能需要一定时间才能生成,而函数需要立即返回)。

获得地理位置

下面是函数on_success的写法示例。它有一个参数,你将最终通过这个函数获取到用户的位置。经纬度分别存在longitudelatitude变量中,同时还有精度、时间戳,以及一些其他额外信息:

function on_success(pos) {
    // 将会获得以下信息
    var latitude = pos.coords.latitude;
    var longitude = pos.coords.longitude;
    var accuracy = pos.coords.accuracy;
    var timestamp = pos.timestamp;
    // 以下信息不一定提供,和具体设备有关
    var altitude = pos.coords.altitude;
    var altitudeAccuracy = pos.coords.altitudeAccuracy;
    var heading = pos.coords.heading;
    var speed = pos.coords.speed;
}

其中altitudealtitudeAccuracyheadingspeed则根据用户的终端不同,可能提供,可能为null

错误处理

上面我们还有一个on_error。显然,如果用户不同意,那我们无法获得任何信息,这时候系统会自动调用这个函数。

function on_error(error) {
    console.log(error.message);
    if (error.code == error.PERMISSION_DENIED) {
        console.log("User denied Geolocation.");
    } else // handle other cases...
}

其中error.code为一个枚举类型,可能的取值如下:

  • PERMISSION_DENIED:用户拒绝
  • POSITION_UNAVAILABLE:地理位置获取失败(可能是用户没网或卫星搜不到等原因)
  • TIMEOUT:地理位置获取超时

error.message则为一个可以帮助开发者调试的错误信息(此信息一般不适合直接显示在网页中给用户查看)。

可选项

事实上,上述getCurrentPosition函数还支持第三个可选的参数,是一个 Option Object,一共有三个选项可以设定:

var options = {
    enableHighAccuracy: false,
    timeout: 5000,
    maximumAge: 60000
}

其中timeout是设定地理位置获取的超时时间(单位为毫秒,用户选择允许的时间不计算在内);而maximumAge表示允许设备从缓存中读取位置,缓存的过期时间,单位是毫秒,设为0来禁用缓存读取。如果返回的是缓存中的时间,会在timestamp中反映出来。

watchPosition

除了getCurrentPosition,HTML5 还提供了watchPosition方法。这两个方法非常类似,都有同样的三个参数,都立即返回。下面介绍watchPosition的特殊之处:

  • 该函数会返回一个整数,表示这个监视任务的 ID。
  • 将持续追踪用户的位置;相应,on_success函数会被多次地调用来更新信息。
  • 通过clearWatch(id)函数调用来停止监视。

调用 Google Maps API

HTML5 为我们提供了用户的经纬度信息,利用这个信息你可以做很多事情。这里只介绍一个最简单的:利用 Google Maps API 在地图上显示用户所处的地点。

需要说明的是,Google Maps API 非常强大,这里只使用了它最基本的功能。以下代码来自官方示例:

HTML 部分:

<script src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=true"></script>
<div id="map-canvas"></div>

JavaScript 部分:

var map;
function initialize() {
    var mapOptions = {
        zoom: 15
    };
    map = new google.maps.Map(document.getElementById('map-canvas'), mapOptions);

    // Try HTML5 geolocation
    if (navigator.geolocation) {
        navigator.geolocation.getCurrentPosition(function(position) {
            var pos = new google.maps.LatLng(position.coords.latitude, position.coords.longitude);
            var infowindow = new google.maps.InfoWindow({
                map: map,
                position: pos,
                content: 'Location found using HTML5.'
            });
            map.setCenter(pos);
        }, function() {
            handleNoGeolocation(true);
        });
    } else {
        // Browser doesn't support Geolocation
        handleNoGeolocation(false);
    }
}

function handleNoGeolocation(errorFlag) {
    if (errorFlag) {
        var content = 'Error: The Geolocation service failed.';
    } else {
        var content = 'Error: Your browser doesn\'t support geolocation.';
    }
    var options = {
        map: map,
        position: new google.maps.LatLng(60, 105),
        content: content
    };
    var infowindow = new google.maps.InfoWindow(options);
    map.setCenter(options.position);
}

google.maps.event.addDomListener(window, 'load', initialize);

兼容性

兼容性列表

支持 Geolocation API 的浏览器/终端/操作系统:

  • Firefox 3.5+
  • Google Chrome 5.0+
  • Safari 5.0+
  • Opera 10.60+
  • Internet Explorer 9.0+
  • Android 2.0+
  • iOS 3.0+
  • Opera Mobile 10.1+
  • Blackberry OS 6

测试兼容性

要测试是否支持 Geolocation API 很简单:

if (navigator.geolocation) {
    console.log("Geolocation is there for you.");
} else {
    console.log("Geolocation is not supported.");
}
本文作者为,最后修订于

讨论