# 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
