地理位置 API 允许用户向 Web 应用程序提供他们的位置。出于隐私考虑,报告地理位置前会先请求用户许可。

geolocation 对象

地理位置 API 通过 navigator.geolocation 提供。

如果该对象存在,那么地理位置服务可用。

if ("geolocation" in navigator) {
  /* 地理位置服务可用 */
} else {
  /* 地理位置服务不可用 */
}

注意: 在 Firefox 24 和之前的浏览器中,即使 API 被禁止,代码 "geolocation" in navigator 也总是会得到 true。这在 Firefox 25 中已经被修复 (bug 884921)。

获取当前定位

您可以调用 getCurrentPosition() 函数获取用户当前定位位置。这会异步地请求获取用户位置,并查询定位硬件来获取最新信息。当定位被确定后,定义的回调函数就会被执行。您可以选择性地提供第二个回调函数,当有错误时会被执行。第三个参数也是可选的,您可以通过该对象参数设定最长可接受的定位返回时间、等待请求的时间和是否获取高精度定位。

注意: 默认情况下,getCurrentPosition() 会尽快返回一个低精度结果,这在您不关心准确度只关心快速获取结果的情况下很有用。有 GPS 的设备可能需要一分钟或更久来获取 GPS 定位,在这种情况下 getCurrentPosition() 会返回低精度数据(基于 IP 的定位或 Wi-Fi 定位)。

navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

上述示例中,当获取位置后 do_something() 函数会被执行。

监视定位

您可以设定一个回调函数来响应定位数据发生的变更(设备发生了移动,或获取到了更高精度的地理位置信息)。您可以通过 watchPosition() 函数实现该功能。它与 getCurrentPosition() 接受相同的参数,但回调函数会被调用多次。错误回调函数与 getCurrentPosition() 中一样是可选的,也会被多次调用。

注意: 您可以直接调用 watchPosition() 函数,不需要先调用 getCurrentPosition() 函数。

var watchID = navigator.geolocation.watchPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

watchPosition() 函数会返回一个 ID,唯一地标记该位置监视器。您可以将这个 ID 传给 clearWatch() 函数来停止监视用户位置。

navigator.geolocation.clearWatch(watchID);

调整返回结果

getCurrentPosition()watchPosition() 都接受一个成功回调、一个可选的失败回调和一个可选的 PositionOptions 对象。

watchPosition 的调用类似于这样:

function geo_success(position) {
  do_something(position.coords.latitude, position.coords.longitude);
}

function geo_error() {
  alert("Sorry, no position available.");
}

var geo_options = {
  enableHighAccuracy: true, 
  maximumAge        : 30000, 
  timeout           : 27000
};

var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, geo_options);

watchPosition 实际使用示例: http://www.thedotproduct.org/experiments/geo/

描述位置

用户的位置由一个包含 Coordinates 对象的 Position 对象描述。

处理错误

getCurrentPosition()watchPosition() 的错误回调函数以 PositionError 为第一个参数。

function errorCallback(error) {
  alert('ERROR(' + error.code + '): ' + error.message);
};

地理位置示例

HTML

<p><button onclick="geoFindMe()">Show my location</button></p>
<div id="out"></div>

 

 

JavaScript

function geoFindMe() {
  var output = document.getElementById("out");

  if (!navigator.geolocation){
    output.innerHTML = "<p>您的浏览器不支持地理位置</p>";
    return;
  }

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

    output.innerHTML = '<p>Latitude is ' + latitude + '° <br>Longitude is ' + longitude + '°</p>';

    var img = new Image();
    img.src = "http://maps.googleapis.com/maps/api/staticmap?center=" + latitude + "," + longitude + "&zoom=13&size=300x300&sensor=false";

    output.appendChild(img);
  };

  function error() {
    output.innerHTML = "无法获取您的位置";
  };

  output.innerHTML = "<p>Locating…</p>";

  navigator.geolocation.getCurrentPosition(success, error);
}

在线示例

授权请求

所有 addons.mozilla.org 上需要使用地理位置的插件必须在使用 API 前显式地请求权限。用户的响应将会存储在 pref 参数指定的偏好设置中。callback 参数指定的函数会被调用并包含一个代表用户响应的 boolean 参数。如果为 true,代表插件可以访问地理位置数据。

function prompt(window, pref, message, callback) {
    let branch = Components.classes["@mozilla.org/preferences-service;1"]
                           .getService(Components.interfaces.nsIPrefBranch);

    if (branch.getPrefType(pref) === branch.PREF_STRING) {
        switch (branch.getCharPref(pref)) {
        case "always":
            return callback(true);
        case "never":
            return callback(false);
        }
    }

    let done = false;

    function remember(value, result) {
        return function() {
            done = true;
            branch.setCharPref(pref, value);
            callback(result);
        }
    }

    let self = window.PopupNotifications.show(
        window.gBrowser.selectedBrowser,
        "geolocation",
        message,
        "geo-notification-icon",
        {
            label: "Share Location",
            accessKey: "S",
            callback: function(notification) {
                done = true;
                callback(true);
            }
        }, [
            {
                label: "Always Share",
                accessKey: "A",
                callback: remember("always", true)
            },
            {
                label: "Never Share",
                accessKey: "N",
                callback: remember("never", false)
            }
        ], {
            eventCallback: function(event) {
                if (event === "dismissed") {
                    if (!done) callback(false);
                    done = true;
                    window.PopupNotifications.remove(self);
                }
            },
            persistWhileVisible: true
        });
}

prompt(window,
       "extensions.foo-addon.allowGeolocation",
       "Foo Add-on wants to know your location.",
       function callback(allowed) { alert(allowed); });

浏览器兼容性

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

 
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 5 3.5 (1.9.1) 9 10.60
Removed in 15.0
Reintroduced in 16.0
5
Feature Android Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support ? ? 4.0 (4) 1.0.1 ? 10.60
Removed in 15.0
Reintroduced in 16.0
?

Gecko 注释

Firefox 支持根据您的 Wi-Fi 信息通过谷歌定位服务来定位。在 Firefox 和 Google 的数据交互中,Wi-Fi 接入点信息、访问令牌(类似于一个两周过期的 cookie)和用户的 IP 地址会被发送。关于数据使用情况,请查看 Mozilla 的隐私声明和 Google 的隐私声明

Firefox 3.6 (Gecko 1.9.2) 增加了 Linux 上对 GPSD (GPS daemon) 服务定位的支持。

另请参阅

文档标签和贡献者

标签: 
最后编辑者: aimilu,