mirror of
https://github.com/wangdoc/webapi-tutorial.git
synced 2025-12-30 08:59:04 +08:00
157 lines
5.7 KiB
Markdown
157 lines
5.7 KiB
Markdown
# Geolocation API
|
||
|
||
Geolocation API 用于获取用户的地理位置。
|
||
|
||
由于该功能涉及用户隐私，所以浏览器会提示用户，是否同意给出地理位置，用户可能会拒绝。另外，这个 API 只能在 HTTPS 环境使用。
|
||
|
||
浏览器通过`navigator.geolocation`属性提供该 API。
|
||
|
||
## Geolocation 对象
|
||
|
||
`navigator.geolocation`属性返回一个 Geolocation 对象。该对象具有以下三个方法。
|
||
|
||
- `Geolocation.getCurrentPosition()`：返回一个 Position 对象，表示用户的当前位置。
|
||
- `Geolocation.watchPosition()`：指定一个监听函数，每当用户的位置发生变化，就执行该监听函数。
|
||
- `Geolocation.clearWatch()`：取消`watchPosition()`方法指定的监听函数。
|
||
|
||
### Geolocation.getCurrentPosition()
|
||
|
||
`Geolocation.getCurrentPosition()`方法用于获取用户的位置。
|
||
|
||
```javascript
|
||
navigator.geolocation.getCurrentPosition(success, error, options)
|
||
```
|
||
|
||
该方法接受三个参数。
|
||
|
||
- `success`：用户同意给出位置时的回调函数，它的参数是一个 Position 对象。
|
||
- `error`：用户拒绝给出位置时的回调函数，它的参数是一个 PositionError 对象。该参数可选。
|
||
- `options`：参数对象，该参数可选。
|
||
|
||
Position 对象有两个属性。
|
||
|
||
- `Position.coords`：返回一个 Coordinates 对象，表示当前位置的坐标。
|
||
- `Position.timestamp`：返回一个对象，代表当前时间戳。
|
||
|
||
PositionError 对象主要有两个属性。
|
||
|
||
- `PositionError.code`：整数，表示发生错误的原因。`1`表示无权限，有可能是用户拒绝授权；`2`表示无法获得位置，可能设备有故障；`3`表示超时。
|
||
- `PositionError.message`：字符串，表示错误的描述。
|
||
|
||
参数对象`option`可以指定三个属性。
|
||
|
||
- `enableHighAccuracy`：布尔值，是否返回高精度结果。如果设为`true`，可能导致响应时间变慢或（移动设备的）功耗增加；反之，如果设为`false`，设备可以更快速地响应。默认值为`false`。
|
||
- `timeout`：正整数，表示等待查询的最长时间，单位为毫秒。默认值为`Infinity`。
|
||
- `maximumAge`：正整数，表示可接受的缓存最长时间，单位为毫秒。如果设为`0`，表示不返回缓存值，必须查询当前的实际位置；如果设为`Infinity`，必须返回缓存值，不管缓存了多少时间。默认值为`0`。
|
||
|
||
下面是一个例子。
|
||
|
||
```javascript
|
||
var options = {
|
||
enableHighAccuracy: true,
|
||
timeout: 5000,
|
||
maximumAge: 0
|
||
};
|
||
|
||
function success(pos) {
|
||
var crd = pos.coords;
|
||
|
||
console.log(`经度：${crd.latitude}`);
|
||
console.log(`纬度：${crd.longitude}`);
|
||
console.log(`误差：${crd.accuracy} 米`);
|
||
}
|
||
|
||
function error(err) {
|
||
console.warn(`ERROR(${err.code}): ${err.message}`);
|
||
}
|
||
|
||
navigator.geolocation.getCurrentPosition(success, error, options);
|
||
```
|
||
|
||
### Geolocation.watchPosition()
|
||
|
||
`Geolocation.watchPosition()`对象指定一个监听函数，每当用户的位置发生变化，就是自动执行这个函数。
|
||
|
||
```javascript
|
||
navigator.geolocation.watchPosition(success[, error[, options]])
|
||
```
|
||
|
||
该方法接受三个参数。
|
||
|
||
- `success`：监听成功的回调函数，该函数的参数为一个 Position 对象。
|
||
- `error`：该参数可选，表示监听失败的回调函数，该函数的参数是一个 PositionError 对象。
|
||
- `options`：该参数可选，表示监听的参数配置对象。
|
||
|
||
该方法返回一个整数值，表示监听函数的编号。该整数用来供`Geolocation.clearWatch()`方法取消监听。
|
||
|
||
下面是一个例子。
|
||
|
||
```javascript
|
||
var id;
|
||
|
||
var target = {
|
||
latitude : 0,
|
||
longitude: 0
|
||
};
|
||
|
||
var options = {
|
||
enableHighAccuracy: false,
|
||
timeout: 5000,
|
||
maximumAge: 0
|
||
};
|
||
|
||
function success(pos) {
|
||
var crd = pos.coords;
|
||
|
||
if (target.latitude === crd.latitude && target.longitude === crd.longitude) {
|
||
console.log('恭喜，你已经到达了指定位置。');
|
||
navigator.geolocation.clearWatch(id);
|
||
}
|
||
}
|
||
|
||
function error(err) {
|
||
console.warn('ERROR(' + err.code + '): ' + err.message);
|
||
}
|
||
|
||
id = navigator.geolocation.watchPosition(success, error, options);
|
||
```
|
||
|
||
### Geolocation.clearWatch()
|
||
|
||
`Geolocation.clearWatch()`方法用来取消`watchPosition()`方法指定的监听函数。它的参数是`watchPosition()`返回的监听函数的编号。
|
||
|
||
```javascript
|
||
navigator.geolocation.clearWatch(id);
|
||
```
|
||
|
||
使用方法的例子见上一节。
|
||
|
||
## Coordinates 对象
|
||
|
||
Coordinates 对象是地理位置的坐标接口，`Position.coords`属性返回的就是这个对象。
|
||
|
||
它有以下属性，全部为只读属性。
|
||
|
||
- `Coordinates.latitude`：浮点数，表示纬度。
|
||
- `Coordinates.longitude`：浮点数，表示经度。
|
||
- `Coordinates.altitude`：浮点数，表示海拔（单位：米）。如果不可得，返回`null`。
|
||
- `Coordinates.accuracy`：浮点数，表示经度和纬度的精度（单位：米）。
|
||
- `Coordinates.altitudeAccuracy`：浮点数，表示海拔的精度（单位：米）。返回`null`。
|
||
- `Coordinates.speed`：浮点数，表示设备的速度（单位：米/秒）。如果不可得，返回`null`。
|
||
- `Coordinates.heading`：浮点数，表示设备前进的方向（单位：度）。方向按照顺时针，北方是0度，东方是90度，西方是270度。如果`Coordinates.speed`为0，`heading`属性返回`NaN`。如果设备无法提供方向信息，该属性返回`null`。
|
||
|
||
下面是一个例子。
|
||
|
||
```javascript
|
||
navigator.geolocation.getCurrentPosition( function (position) {
|
||
let lat = position.coords.latitude;
|
||
let long = position.coords.longitude;
|
||
console.log(`纬度：${lat.toFixed(2)}`);
|
||
console.log(`经度：${long.toFixed(2)}`);
|
||
});
|
||
```
|
||
|
||
## 参考链接
|
||
|
||
- [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API), by MDN
|