PhoneGap API介紹:Geolocation
方法:
參數(shù):
對(duì)象(只讀):
geolocation.getCurrentPosition
- 返回一個(gè)Position對(duì)象表示設(shè)備的當(dāng)前位置。
- navigator.geolocation.getCurrentPosition(geolocationSuccess,
- [geolocationError],
- [geolocationOptions]);
參數(shù):
- geolocationSuccess:獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù),參數(shù)為當(dāng)前的位置信息。
- geolocationError:(可選項(xiàng))獲取位置信息出錯(cuò)時(shí)調(diào)用的回調(diào)函數(shù)。
- geolocationOptions:(可選項(xiàng))地理位置選項(xiàng)。
說明:
- geolocation.getCurrentPositon是一個(gè)異步函數(shù)。它回傳一個(gè)包含設(shè)備當(dāng)前位置信息的Position對(duì)象給geolocationSuccess回調(diào)函數(shù)。如果發(fā)生錯(cuò)誤,觸發(fā)geolocationError回調(diào)函數(shù)并傳遞一個(gè)PositionError對(duì)象。
支持的平臺(tái):
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0或更高版本)
- iPhone
簡單的范例:
- // 獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù)
- // 該方法接受一個(gè)“Position”對(duì)象,包含當(dāng)前GPS坐標(biāo)信息
- 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: ' + new Date(position.timestamp) + '\n');
- };
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- navigator.geolocation.getCurrentPosition(onSuccess, onError);
完整的范例:
- <!DOCTYPE html>
- <html>
- <head>
- <title>Device Properties Example</title>
- <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
- <script type="text/javascript" charset="utf-8">
- // 等待加載PhoneGap
- document.addEventListener("deviceready", onDeviceReady, false);
- // PhoneGap加載完畢
- function onDeviceReady() {
- navigator.geolocation.getCurrentPosition(onSuccess, onError);
- }
- // 獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù)
- function onSuccess(position) {
- var element = document.getElementById('geolocation');
- element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
- 'Longitude: ' + position.coords.longitude + '<br />' +
- 'Altitude: ' + position.coords.altitude + '<br />' +
- 'Accuracy: ' + position.coords.accuracy + '<br />' +
- 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br />' +
- 'Heading: ' + position.coords.heading + '<br />' +
- 'Speed: ' + position.coords.speed + '<br />' +
- 'Timestamp: ' + new Date(position.timestamp) + '<br />';
- }
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- </script>
- </head>
- <body>
- <p id="geolocation">Finding geolocation...</p>
- </body>
- </html>
- 監(jiān)視設(shè)備的當(dāng)前位置的變化。
- var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
- [geolocationError],
- [geolocationOptions]);
參數(shù):
- geolocationSuccess: 獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù),參數(shù)為當(dāng)前位置信息。
- geolocationError:(可選項(xiàng))獲取位置信息出錯(cuò)時(shí)調(diào)用的回調(diào)函數(shù)。
- geolocationOptions:(可選項(xiàng))地理位置選項(xiàng)。
返回:
- String:返回的watch id是位置監(jiān)視String:返回的watch id是位置監(jiān)視周期的引用??梢酝ㄟ^geolocation.clearWatch調(diào)用該watch ID以停止對(duì)位置變化的監(jiān)視。
說明:
- geolocation.watchPosition是一個(gè)異步函數(shù)。當(dāng)檢測(cè)到設(shè)備的位置發(fā)生改變時(shí),它返回設(shè)備的當(dāng)前位置。當(dāng)設(shè)備檢索到一個(gè)新的位置,會(huì)觸發(fā)geolocationSuccess回調(diào)函數(shù)并傳遞一個(gè)Position對(duì)象作為參數(shù)。如果發(fā)生錯(cuò)誤,會(huì)觸發(fā)geolocationError回調(diào)函數(shù)并傳遞一個(gè)PositionError對(duì)象。
支持的平臺(tái):
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0或更高版本)
- iPhone
簡單的范例:
- // 獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù)
- // 該方法接受一個(gè)“Position”對(duì)象,包含當(dāng)前GPS坐標(biāo)信息
- function onSuccess(position) {
- var element = document.getElementById('geolocation');
- element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br>' +
- 'Longitude: ' + position.coords.longitude + '<br>' +
- '<hr>' + element.innerHTML;
- }
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- // Options: 每隔3秒鐘檢索一次位置信息
- var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });
完整的范例:
- <!DOCTYPE html>
- <html>
- <head>
- <title>Device Properties Example</title>
- <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
- <script type="text/javascript" charset="utf-8">
- // 等待加載PhoneGap
- document.addEventListener("deviceready", onDeviceReady, false);
- var watchID = null;
- // PhoneGap加載完畢
- function onDeviceReady() {
- // 每隔3秒鐘更新一次
- var options = { frequency: 3000 };
- watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
- }
- // 獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù)
- function onSuccess(position) {
- var element = document.getElementById('geolocation');
- element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
- 'Longitude: ' + position.coords.longitude + '<br />' +
- <hr />'' + element.innerHTML;
- }
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- </script>
- </head>
- <body>
- <p id="geolocation">Finding geolocation...</p>
- </body>
- </html>
- 停止watchID參數(shù)指向的設(shè)備位置變化監(jiān)視。
- navigator.geolocation.clearWatch(watchID);
參數(shù):
- watchID:要清除的watchPosition周期的id。(字符串類型)
說明:
- geolocation.clearWatch函數(shù)通過清除watchID指向的geolocation.watchPosition來停止對(duì)設(shè)備位置變化的監(jiān)視。
支持的平臺(tái):
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0或更高版本)
- iPhone
簡單的范例:
- // 選項(xiàng): 每隔3秒鐘檢索一次位置信息
- var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });
- // ...后繼處理...
- navigator.geolocation.clearWatch(watchID);
完整的范例:
- <!DOCTYPE html>
- <html>
- <head>
- <title>Device Properties Example</title>
- <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
- <script type="text/javascript" charset="utf-8">
- // 等待加載PhoneGap
- document.addEventListener("deviceready", onDeviceReady, false);
- var watchID = null;
- // PhoneGap加載完畢
- function onDeviceReady() {
- // 每隔3秒鐘更新一次
- var options = { frequency: 3000 };
- watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
- }
- // 獲取位置信息成功時(shí)調(diào)用的回調(diào)函數(shù)
- function onSuccess(position) {
- var element = document.getElementById('geolocation');
- element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
- 'Longitude: ' + position.coords.longitude + '<br />' +
- '<hr />' + element.innerHTML;
- }
- // 清除前述已經(jīng)開始的監(jiān)視
- function clearWatch() {
- if (watchID != null) {
- navigator.geolocation.clearWatch(watchID);
- watchID = null;
- }
- }
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- </script>
- </head>
- <body>
- <p id="geolocation">Finding geolocation...</p>
- <button onclick="clearWatch();">Clear Watch</button>
- </body>
- </html>
- 當(dāng)?shù)玫揭粋€(gè)有效地理位置信息時(shí),此用戶回調(diào)函數(shù)被調(diào)當(dāng)獲得一個(gè)地理位置信息時(shí),此用戶回調(diào)函數(shù)被調(diào)用。
- function(position) {
- // 進(jìn)行處理
- }
參數(shù):
- position:設(shè)備返回的地理位置信息。(Position類型)
范例:
- function geolocationSuccess(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: ' + new Date(position.timestamp) + '\n');
- }
- 當(dāng)geolocation函數(shù)發(fā)生錯(cuò)誤時(shí),此用戶回調(diào)函數(shù)被調(diào)用。
- function(error) {
- // 處理錯(cuò)誤
- }
參數(shù):
- error:設(shè)備返回的錯(cuò)誤信息。(PositionError類型)
- 用戶定制地理位置檢索的可選參數(shù)。
- { maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
選項(xiàng):
- frequency:以毫秒為單位的檢索位置周期。這個(gè)選項(xiàng)并非W3C規(guī)范的一部分,未來會(huì)被刪除并用maximumAge來替代該選項(xiàng)。(數(shù)字類型)(默認(rèn)值:10000)
- enableHighAccuracy:提供一個(gè)表明應(yīng)用程序希望獲得最佳可能結(jié)果的提示。(布爾類型)
- timeout:允許的以毫秒為單位的最大時(shí)間間隔,該時(shí)間間隔是從geolocation.getCurrentPosition或geolocation.watchPosition的調(diào)用到相應(yīng)的geolocationSuccess回調(diào)函數(shù)被調(diào)用。(數(shù)字類型)
- maximumAge:應(yīng)用程序?qū)⒔邮芤粋€(gè)緩存的位置信息,當(dāng)該緩存的位置信息的年齡不大于此參數(shù)設(shè)定值,單位是毫秒。(數(shù)字類型)
Android的特異情況:
- 除非enableHighAccuracy選項(xiàng)被設(shè)定為true,否則Android 2.X模擬器不會(huì)返回一個(gè)地理位置結(jié)果。
- { enableHighAccuracy: true }
- 包含由geolocation API創(chuàng)建的Position坐標(biāo)信息。
屬性:
- coords:一系列地理坐標(biāo)。(Coordinates類型)
- timestamp:以毫秒為單位的coords的創(chuàng)建時(shí)間戳。(DOMTimeStamp類型)
說明:
- Position對(duì)象是由PhoneGap創(chuàng)建和填充的,并通過一個(gè)回調(diào)函數(shù)返回用戶。
支持的平臺(tái):
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0或更高版本)
- iPhone
簡單的范例:
- // 獲取位置信息成功后調(diào)用的回調(diào)函數(shù)
- 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: ' + new Date(position.timestamp) + '\n');
- };
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- navigator.geolocation.getCurrentPosition(onSuccess, onError);
完整的范例:
- <!DOCTYPE html>
- <html>
- <head>
- <title>Device Properties Example</title>
- <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
- <script type="text/javascript" charset="utf-8">
- // 等待加載PHoneGap
- document.addEventListener("deviceready", onDeviceReady, false);
- // PhoneGap加載完畢
- function onDeviceReady() {
- navigator.geolocation.getCurrentPosition(onSuccess, onError);
- }
- // 獲取位置信息成功后調(diào)用的回調(diào)函數(shù)
- function onSuccess(position) {
- var element = document.getElementById('geolocation');
- element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
- 'Longitude: ' + position.coords.longitude + '<br />' +
- 'Altitude: ' + position.coords.altitude + '<br />' +
- 'Accuracy: ' + position.coords.accuracy + '<br />' +
- 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br />' +
- 'Heading: ' + position.coords.heading + '<br />' +
- 'Speed: ' + position.coords.speed + '<br />' +
- 'Timestamp: ' + new Date(position.timestamp) + '<br />';
- }
- // onError回調(diào)函數(shù)接收一個(gè)PositionError對(duì)象
- function onError(error) {
- alert('code: ' + error.code + '\n' +
- 'message: ' + error.message + '\n');
- }
- </script>
- </head>
- <body>
- <p id="geolocation">Finding geolocation...</p>
- </body>
- </html>
iPhone的特異情況:
- timestamp:單位為秒而非毫秒。
一種變通方法是手動(dòng)將時(shí)間戳轉(zhuǎn)換為毫秒(*1000):
- var onSuccess = function(position) {
- alert('Latitude: ' + position.coords.latitude + '\n' +
- 'Longitude: ' + position.coords.longitude + '\n' +
- 'Timestamp: ' + new Date(position.timestamp * 1000) + '\n');
- };
- 當(dāng)發(fā)生錯(cuò)誤時(shí),一個(gè)PositionError對(duì)象會(huì)傳遞給geolocationError回調(diào)函數(shù)。
屬性:
- code:一個(gè)在下面常量列表中定義的錯(cuò)誤代碼。
- message:說明錯(cuò)誤細(xì)節(jié)的錯(cuò)誤信息。
常量:
- PositionError.PERMISSIONPositionError.PERMISSION_DENIED:權(quán)限被拒絕
- PositionError.POSITION_UNAVAILABLE:位置不可用
- PositionError.TIMEOUT:超時(shí)
說明:
- 當(dāng)使用Geolocation發(fā)生錯(cuò)誤時(shí),一個(gè)PositionError對(duì)象會(huì)作為geolocationError回調(diào)函數(shù)的參數(shù)傳遞給用戶。
- 一系列用來描述位置的地理坐標(biāo)信息的屬性。
屬性:
- latitude:以十進(jìn)制表示的緯度。(數(shù)字類型)
- longitude:以十進(jìn)制表示的經(jīng)度。(數(shù)字類型)
- altitude:位置相對(duì)于橢圓球面的高度,單位為米。(數(shù)字類型)
- accuracy:以米為單位的緯度和經(jīng)度坐標(biāo)的精度水平。(數(shù)字類型)
- altitudeAccuracy:以米為單位的高度坐標(biāo)的精度水平。(數(shù)字類型)
- heading:運(yùn)動(dòng)的方向,通過相對(duì)正北做順時(shí)針旋轉(zhuǎn)的角度指定。(數(shù)字類型)
- speed:以米/秒為單位的設(shè)備當(dāng)前地面速度。(數(shù)字類型)
說明:
- 作為Position對(duì)象的一部分,Coordinates對(duì)象是由PhoneGap創(chuàng)建和填充的。該P(yáng)osition對(duì)象會(huì)作為一個(gè)回調(diào)函數(shù)的參數(shù)返回用戶。
支持的平臺(tái):
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0或更高版本)
- iPhone
簡單的范例:
- // 獲取位置信息成功后調(diào)用的回調(diào)函數(shù)
- 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: ' + new Date(position.timestamp) + '\n');
- };
- // 獲取位置信息出錯(cuò)后調(diào)用的回調(diào)函數(shù)
- var onError = function() {
- alert('onError!');
- };
- navigator.geolocation.getCurrentPosition(onSuccess, onError);
完整的范例:
- <!DOCTYPE html>
- <html>
- <head>
- <title>Geolocation Position Example</title>
- <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
- <script type="text/javascript" charset="utf-8">
- // 設(shè)置一個(gè)當(dāng)PhoneGap加載完畢后觸發(fā)的事件
- document.addEventListener("deviceready", onDeviceReady, false);
- // PhoneGap加載完畢并就緒
- function onDeviceReady() {
- navigator.geolocation.getCurrentPosition(onSuccess, onError);
- }
- // 顯示位置信息中的“Position”屬性
- function onSuccess(position) {
- var div = document.getElementById('myDiv');
- div.innerHTML = 'Latitude: ' + position.coords.latitude + '<br/>' +
- 'Longitude: ' + position.coords.longitude + '<br/>' +
- 'Altitude: ' + position.coords.altitude + '<br/>' +
- 'Accuracy: ' + position.coords.accuracy + '<br/>' +
- 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br/>' +
- 'Heading: ' + position.coords.heading + '<br/>' +
- 'Speed: ' + position.coords.speed + '<br/>';
- }
- // 如果獲取位置信息出現(xiàn)問題,則顯示一個(gè)警告
- function onError() {
- alert('onError!');
- }
- </script>
- </head>
- <body>
- <div id="myDiv"></div></body>
- </html>
Android的特異情況:
- altitudeAccuracy: Android設(shè)備上不支持該屬性,返回值總是null。