主分支.

cordova-plugin-geolocation

此插件提供有关设备位置的信息，例如纬度和经度。

位置信息的常见来源包括全球定位系统 (GPS) 和从网络信号（例如 IP 地址、RFID、WiFi 和蓝牙 MAC 地址以及 GSM/CDMA 蜂窝 ID）推断出的位置。不保证 API 返回设备的实际位置。

要获取一些想法，请查看此页面底部的示例或直接转到参考内容。

警告：收集和使用地理位置数据会引发重要的隐私问题。您的应用的隐私政策应讨论该应用如何使用地理位置数据、是否与任何其他方共享以及数据的精确程度（例如，粗略、精细、邮政编码级别等）。地理位置数据通常被认为是敏感的，因为它可能会泄露用户的位置，如果存储，还会泄露他们的旅行历史。因此，除了应用的隐私政策外，您还应强烈考虑在应用访问地理位置数据之前提供即时通知（如果设备操作系统尚未这样做）。该通知应提供上述相同信息，并获得用户的许可（例如，通过提供确定和 不，谢谢 的选项）。有关更多信息，请参阅隐私指南。

此插件定义了一个全局 navigator.geolocation 对象（对于其他情况下缺少此对象的平台）。

尽管该对象在全局范围内，但只有在 deviceready 事件之后，此插件提供的功能才可用。

    document.addEventListener("deviceready", onDeviceReady, false);
    function onDeviceReady() {
        console.log("navigator.geolocation works well");
    }

安装

这需要 cordova 5.0+（当前稳定版本 1.0.0）

cordova plugin add cordova-plugin-geolocation

旧版本的 cordova 仍然可以通过已弃用的 ID（过时的 0.3.12）安装

cordova plugin add org.apache.cordova.geolocation

也可以直接通过 repo URL 安装（不稳定）

cordova plugin add https://github.com/apache/cordova-plugin-geolocation.git

支持的平台

Android
iOS
Windows

方法

navigator.geolocation.getCurrentPosition
navigator.geolocation.watchPosition
navigator.geolocation.clearWatch

对象（只读）

Position
PositionError
Coordinates

navigator.geolocation.getCurrentPosition

使用 Position 对象作为参数，将设备的当前位置返回到 geolocationSuccess 回调。如果发生错误，则向 geolocationError 回调传递一个 PositionError 对象。

navigator.geolocation.getCurrentPosition(geolocationSuccess,
                                         [geolocationError],
                                         [geolocationOptions]);

参数

geolocationSuccess：传递当前位置的回调。
geolocationError：（可选）如果发生错误则执行的回调。
geolocationOptions：（可选）地理位置选项。

示例

    // onSuccess Callback
    // This method accepts a Position object, which contains the
    // current GPS coordinates
    //
    var onSuccess = function(position) {
        alert('Latitude: '          + position.coords.latitude          + '\n' +
              'Longitude: '         + position.coords.longitude         + '\n' +
              'Altitude: '          + position.coords.altitude          + '\n' +
              'Accuracy: '          + position.coords.accuracy          + '\n' +
              'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
              'Heading: '           + position.coords.heading           + '\n' +
              'Speed: '             + position.coords.speed             + '\n' +
              'Timestamp: '         + position.timestamp                + '\n');
    };

    // onError Callback receives a PositionError object
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }

    navigator.geolocation.getCurrentPosition(onSuccess, onError);

iOS 怪癖

自 iOS 10 起，如果尝试访问隐私敏感数据，则必须在 info.plist 中提供使用说明。当系统提示用户允许访问时，此使用说明字符串将显示为权限对话框的一部分，但是如果您没有提供使用说明，则应用会在显示对话框之前崩溃。此外，Apple 将拒绝访问私有数据但不提供使用说明的应用。

此插件需要以下使用说明

NSLocationWhenInUseUsageDescription 描述了应用访问用户位置的原因，这在应用在前台运行时使用。
NSLocationAlwaysAndWhenInUseUsageDescription 描述了应用请求始终访问用户位置信息的原因。如果您的 iOS 应用在后台和前台运行时都访问位置信息，请使用此键。
NSLocationAlwaysUsageDescription 描述了应用请求始终访问用户位置的原因。如果您的应用在后台访问位置信息并且您部署到早于 iOS 11 的目标，请使用此键。对于 iOS 11 及更高版本，请将 NSLocationAlwaysUsageDescription 和 NSLocationAlwaysAndWhenInUseUsageDescription 都添加到应用的 Info.plist 文件中，并使用相同的消息。

要将这些条目添加到 info.plist 中，您可以使用 config.xml 中的 edit-config 标记，如下所示

<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

<edit-config target="NSLocationAlwaysAndWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

<edit-config target="NSLocationAlwaysUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

Android 怪癖

由于历史原因，此插件需要 Android 设备上的 GPS 硬件，因此您的应用将无法在没有 GPS 硬件的设备上运行。如果您想在您的应用中使用此插件，但您不需要设备上的实际 GPS 硬件，请使用设置为 false 的变量 GPS_REQUIRED 安装插件

cordova plugin add cordova-plugin-geolocation --variable GPS_REQUIRED="false"

如果地理位置服务已关闭，则在 timeout 间隔后调用 onError 回调（如果指定）。如果未指定 timeout 参数，则不会调用任何回调。

navigator.geolocation.watchPosition

当检测到位置变化时，返回设备的当前位置。当设备检索到新的位置时，geolocationSuccess 回调会执行，并使用 Position 对象作为参数。如果发生错误，则 geolocationError 回调会执行，并使用 PositionError 对象作为参数。

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
                                                  [geolocationError],
                                                  [geolocationOptions]);

参数

geolocationSuccess：传递当前位置的回调。
geolocationError：(可选) 如果发生错误则执行的回调。
geolocationOptions：(可选) 地理位置选项。

字符串：返回一个 watch id，该 watch id 引用监视位置间隔。 watch id 应与 navigator.geolocation.clearWatch 一起使用，以停止监视位置的变化。

示例

    // onSuccess Callback
    //   This method accepts a `Position` object, which contains
    //   the current GPS coordinates
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                            'Longitude: ' + position.coords.longitude     + '<br />' +
                            '<hr />'      + element.innerHTML;
    }

    // onError Callback receives a PositionError object
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }

    // Options: throw an error if no update is received every 30 seconds.
    //
    var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });

geolocationOptions

自定义检索地理位置 Position 的可选参数。

{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };

选项

enableHighAccuracy：提供应用程序需要最佳结果的提示。默认情况下，设备尝试使用基于网络的方法检索 Position。将此属性设置为 true 会告诉框架使用更准确的方法，例如卫星定位。 （布尔值）
timeout：从调用 navigator.geolocation.getCurrentPosition 或 geolocation.watchPosition 到执行相应的 geolocationSuccess 回调所允许的最大时间长度（毫秒）。如果在此时间内未调用 geolocationSuccess 回调，则会向 geolocationError 回调传递一个 PositionError.TIMEOUT 错误代码。（请注意，当与 geolocation.watchPosition 结合使用时，geolocationError 回调可能会每 timeout 毫秒间隔调用一次！）（数字）
maximumAge：接受缓存的位置，其存在时间不超过指定的时间（以毫秒为单位）。 （数字）

Android 怪癖

如果地理位置服务已关闭，则在 timeout 间隔后调用 onError 回调（如果指定）。如果未指定 timeout 参数，则不会调用任何回调。

navigator.geolocation.clearWatch

停止监视由 watchID 参数引用的设备位置变化。

navigator.geolocation.clearWatch(watchID);

参数

watchID：要清除的 watchPosition 间隔的 ID。(字符串)

示例

    // Options: watch for changes in position, and use the most
    // accurate position acquisition method available.
    //
    var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });

    // ...later on...

    navigator.geolocation.clearWatch(watchID);

Position

包含 Position 坐标和时间戳，由地理位置 API 创建。

属性

coords：一组地理坐标。 (Coordinates)
timestamp：coords 的创建时间戳。 (DOMTimeStamp)

Coordinates

Coordinates 对象附加到 Position 对象，该对象在请求当前位置的回调函数中可用。它包含一组描述位置的地理坐标的属性。

属性

latitude：以十进制度表示的纬度。 （数字）
longitude：以十进制度表示的经度。 （数字）
altitude：位置在椭球面以上的高度，以米为单位。 （数字）
accuracy：纬度和经度坐标的精度水平，以米为单位。 （数字）
altitudeAccuracy：高度坐标的精度水平，以米为单位。 （数字）
heading：行进方向，以相对于正北的顺时针方向（以度为单位）指定。 （数字）
speed：设备当前的地面速度，以米/秒为单位指定。 （数字）

Android 怪癖

altitudeAccuracy：Android 设备不支持，返回 null。

PositionError

当 navigator.geolocation 发生错误时，会将 PositionError 对象传递给 geolocationError 回调函数。

属性

code：下面列出的预定义错误代码之一。
message：描述遇到错误的详细信息的错误消息。

常量

PositionError.PERMISSION_DENIED
- 当用户不允许应用检索位置信息时返回。这取决于平台。
PositionError.POSITION_UNAVAILABLE
- 当设备无法检索位置时返回。通常，这意味着设备未连接到网络或无法获得卫星信号。
PositionError.TIMEOUT
- 当设备无法在 geolocationOptions 中包含的 timeout 指定的时间内检索到位置时返回。当与 navigator.geolocation.watchPosition 一起使用时，此错误可能会每 timeout 毫秒重复传递到 geolocationError 回调。

示例：使用地理位置获取天气、查找商店以及查看附近事物的照片

使用此插件可帮助用户找到附近的物品，例如 Groupon 优惠、待售房屋、正在上映的电影、体育和娱乐活动等等。

以下是一些帮助您入门的想法“食谱”。在下面的代码片段中，我们将向您展示将这些功能添加到应用程序的一些基本方法。

获取您的坐标.
获取天气预报.
在您四处开车时接收更新的天气预报.
在地图上查看您所在的位置.
查找您附近的商店.
查看您周围事物的图片.

获取您的地理位置坐标

function getWeatherLocation() {

    navigator.geolocation.getCurrentPosition
    (onWeatherSuccess, onWeatherError, { enableHighAccuracy: true });
}

获取天气预报

// Success callback for get geo coordinates

var onWeatherSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getWeather(Latitude, Longitude);
}

// Get weather by using coordinates

function getWeather(latitude, longitude) {

    // Get a free key at http://openweathermap.org/. Replace the "Your_Key_Here" string with that key.
    var OpenWeatherAppKey = "Your_Key_Here";

    var queryString =
      'http://api.openweathermap.org/data/2.5/weather?lat='
      + latitude + '&lon=' + longitude + '&appid=' + OpenWeatherAppKey + '&units=imperial';

    $.getJSON(queryString, function (results) {

        if (results.weather.length) {

            $.getJSON(queryString, function (results) {

                if (results.weather.length) {

                    $('#description').text(results.name);
                    $('#temp').text(results.main.temp);
                    $('#wind').text(results.wind.speed);
                    $('#humidity').text(results.main.humidity);
                    $('#visibility').text(results.weather[0].main);

                    var sunriseDate = new Date(results.sys.sunrise);
                    $('#sunrise').text(sunriseDate.toLocaleTimeString());

                    var sunsetDate = new Date(results.sys.sunrise);
                    $('#sunset').text(sunsetDate.toLocaleTimeString());
                }

            });
        }
    }).fail(function () {
        console.log("error getting location");
    });
}

// Error callback

function onWeatherError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

在您四处开车时接收更新的天气预报

// Watch your changing position

function watchWeatherPosition() {

    return navigator.geolocation.watchPosition
    (onWeatherWatchSuccess, onWeatherError, { enableHighAccuracy: true });
}

// Success callback for watching your changing position

var onWeatherWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        // Calls function we defined earlier.
        getWeather(updatedLatitude, updatedLongitude);
    }
}

在地图上查看您所在的位置

Bing 和 Google 都有地图服务。我们将使用 Google 的服务。您需要一个密钥，但是如果您只是想试用一下，则是免费的。

添加对 maps 服务的引用。


 <script src="https://maps.googleapis.com/maps/api/js?key=Your_API_Key"></script>

然后，添加代码以使用它。

var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getMapLocation() {

    navigator.geolocation.getCurrentPosition
    (onMapSuccess, onMapError, { enableHighAccuracy: true });
}

// Success callback for get geo coordinates

var onMapSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getMap(Latitude, Longitude);

}

// Get map by using coordinates

function getMap(latitude, longitude) {

    var mapOptions = {
        center: new google.maps.LatLng(0, 0),
        zoom: 1,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    };

    map = new google.maps.Map
    (document.getElementById("map"), mapOptions);


    var latLong = new google.maps.LatLng(latitude, longitude);

    var marker = new google.maps.Marker({
        position: latLong
    });

    marker.setMap(map);
    map.setZoom(15);
    map.setCenter(marker.getPosition());
}

// Success callback for watching your changing position

var onMapWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getMap(updatedLatitude, updatedLongitude);
    }
}

// Error callback

function onMapError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchMapPosition() {

    return navigator.geolocation.watchPosition
    (onMapWatchSuccess, onMapError, { enableHighAccuracy: true });
}

查找您附近的商店

您可以对此使用相同的 Google 密钥。

添加对 places 服务的引用。


<script src=
"https://maps.googleapis.com/maps/api/js?key=Your_API_Key&libraries=places">
</script>

然后，添加代码以使用它。

var Map;
var Infowindow;
var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getPlacesLocation() {
    navigator.geolocation.getCurrentPosition
    (onPlacesSuccess, onPlacesError, { enableHighAccuracy: true });
}

// Success callback for get geo coordinates

var onPlacesSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getPlaces(Latitude, Longitude);

}

// Get places by using coordinates

function getPlaces(latitude, longitude) {

    var latLong = new google.maps.LatLng(latitude, longitude);

    var mapOptions = {

        center: new google.maps.LatLng(latitude, longitude),
        zoom: 15,
        mapTypeId: google.maps.MapTypeId.ROADMAP

    };

    Map = new google.maps.Map(document.getElementById("places"), mapOptions);

    Infowindow = new google.maps.InfoWindow();

    var service = new google.maps.places.PlacesService(Map);
    service.nearbySearch({

        location: latLong,
        radius: 500,
        type: ['store']
    }, foundStoresCallback);

}

// Success callback for watching your changing position

var onPlacesWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getPlaces(updatedLatitude, updatedLongitude);
    }
}

// Success callback for locating stores in the area

function foundStoresCallback(results, status) {

    if (status === google.maps.places.PlacesServiceStatus.OK) {

        for (var i = 0; i < results.length; i++) {

            createMarker(results[i]);

        }
    }
}

// Place a pin for each store on the map

function createMarker(place) {

    var placeLoc = place.geometry.location;

    var marker = new google.maps.Marker({
        map: Map,
        position: place.geometry.location
    });

    google.maps.event.addListener(marker, 'click', function () {

        Infowindow.setContent(place.name);
        Infowindow.open(Map, this);

    });
}

// Error callback

function onPlacesError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchPlacesPosition() {

    return navigator.geolocation.watchPosition
    (onPlacesWatchSuccess, onPlacesError, { enableHighAccuracy: true });
}

查看您周围事物的图片

数码照片可以包含地理坐标，用来标识照片拍摄的地点。

使用 Flickr API 查找您附近其他人拍摄的照片。就像 Google 服务一样，您需要一个密钥，但如果您只是想尝试一下，它是免费的。

var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getPicturesLocation() {

    navigator.geolocation.getCurrentPosition
    (onPicturesSuccess, onPicturesError, { enableHighAccuracy: true });

}

// Success callback for get geo coordinates

var onPicturesSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getPictures(Latitude, Longitude);
}

// Get pictures by using coordinates

function getPictures(latitude, longitude) {

    $('#pictures').empty();

    var queryString =
    "https://api.flickr.com/services/rest/?method=flickr.photos.search&api_key=Your_API_Key&lat="
    + latitude + "&lon=" + longitude + "&format=json&jsoncallback=?";

    $.getJSON(queryString, function (results) {
        $.each(results.photos.photo, function (index, item) {

            var photoURL = "http://farm" + item.farm + ".static.flickr.com/" +
                item.server + "/" + item.id + "_" + item.secret + "_m.jpg";

            $('#pictures').append($("<img />").attr("src", photoURL));

           });
        }
    );
}

// Success callback for watching your changing position

var onPicturesWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getPictures(updatedLatitude, updatedLongitude);
    }
}

// Error callback

function onPicturesError(error) {

    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchPicturePosition() {

    return navigator.geolocation.watchPosition
    (onPicturesWatchSuccess, onPicturesError, { enableHighAccuracy: true });
}