master.

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

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

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

支持的平台

安卓
iOS
Windows

方法

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

对象（只读）

位置
位置错误
坐标

navigator.geolocation.getCurrentPosition

将设备的当前位置返回给 geolocationSuccess 回调，并将 Position 对象作为参数。如果出现错误，则 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 硬件，请使用变量 GPS_REQUIRED 设置为 false 安装插件

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

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

navigator.geolocation.watchPosition

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

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

参数

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

字符串：返回一个 watch ID，它引用 watch 位置间隔。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 特性

如果地理位置服务已关闭，则 onError 回调将在 timeout 间隔（如果指定）后调用。如果未指定 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 坐标和时间戳，由地理位置 API 创建。

属性

coords：一组地理坐标。（坐标）
timestamp：coords 的创建时间戳。（DOMTimeStamp）

坐标

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

属性

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

Android 特性

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

位置错误

当 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 的。您需要一个密钥，但如果您只是尝试一下，它是免费的。

添加对地图服务的引用。


 <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 密钥。

添加对地点服务的引用。


<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 });
}