Geolocation · Html5+參考

# [geolocation]() Geolocation模塊管理設備位置信息，用于獲取地理位置信息，如經度、緯度等。通過plus.geolocation可獲取設備位置管理對象。雖然W3C已經提供標準API獲取位置信息，但在某些平臺存在差異或未實現，為了保持各平臺的統一性，定義此規范接口獲取位置信息。 ### 方法： - [getCurrentPosition](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.getCurrentPosition): 獲取當前設備位置信息 - [watchPosition](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.watchPosition): 監聽設備位置變化信息 - [clearWatch](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.clearWatch): 關閉監聽設備位置信息 ### 對象： - [Position](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Position): JSON對象，設備位置信息數據 - [Coordinates](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Coordinates): JSON對象，地理坐標信息 - [PositionOption](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.PositionOption): JSON對象，監聽設備位置信息參數 ### 回調方法： - [GeolocationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationSuccessCallback): 獲取設備位置信息成功的回調函數 - [GeolocationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationErrorCallback): 獲取設備位置信息失敗的回調函數 ### 權限： permissions ~~~ "Geolocation": { "description": "訪問設備位置信息" } ~~~ # [getCurrentPosition]() 獲取當前設備位置信息 ~~~ void plus.geolocation.getCurrentPosition( successCB, errorCB, option ); ~~~ ### 說明：位置信息將通過手機GPS設備或其它信息如IP地址、移動網絡信號獲取，由于獲取位置信息可能需要較長的時間，當成功獲取位置信息后將通過successCB回調函數返回。 ### 參數： - successCB: *( [GeolocationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationSuccessCallback) ) 必選 *獲取設備位置信息成功回調函數 - errorCB: *( [GeolocationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationErrorCallback) ) 可選 *獲取設備位置信息失敗回調函數 - option: *( [PositionOption](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.PositionOption) ) 可選 *獲取設備位置信息的參數 ### 返回值： void : 無 ### 平臺支持： - Android - 2.2+ (支持): 支持 - iOS - 4.3+ (支持): 支持 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Geolocation Example</title> <script type="text/javascript" > // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); // 擴展API加載完畢，現在可以正常調用擴展API function onPlusReady() { plus.geolocation.getCurrentPosition( function ( p ) { alert( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude ); }, function ( e ) { alert( "Geolocation error: " + e.message ); } ); } </script> </head> <body > </body> </html> ~~~ # [watchPosition]() 監聽設備位置變化信息 ~~~ Number plus.geolocation.watchPosition( successCB, errorCB, option ); ~~~ ### 說明：位置信息將通過手機GPS設備或其它信息如IP地址、移動網絡信號獲取。當位置信息更新后將通過successCB回調函數返回。位置信息獲取失敗則調用回調函數errorCB。 ### 參數： - successCB: *( [GeolocationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationSuccessCallback) ) 必選 * 設備位置信息更新成功回調函數 - errorCB: *( [GeolocationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationErrorCallback) ) 可選 * 獲取設備位置信息失敗回調函數 - option: *( [PositionOption](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.PositionOption) ) 可選 * 監聽設備位置信息的參數 ### 返回值： Number : 用于標識位置信息監聽器，可通過clearWatch方法取消監聽。 ### 平臺支持： - Android - 2.2+ (支持): 支持 - iOS - 4.3+ (支持): 支持 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Geolocation Example</title> <script type="text/javascript" > // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); // 擴展API加載完畢，現在可以正常調用擴展API function onPlusReady() { plus.geolocation.watchPosition( function ( a ) { alert( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude ); }, function ( e ) { alert( "Geolocation error: " + e.message ); } ); } </script> </head> <body > </body> </html> ~~~ # [clearWatch]() 關閉監聽設備位置信息 ~~~ void plus.geolocation.clearWatch( watchId ); ~~~ ### 參數： - watchId: *( Number ) 必選 * 需要取消的位置監聽器標識，調用watchPosition方法的返回值。 ### 返回值： void : 無 ### 平臺支持： - Android - 2.2+ (支持): 支持 - iOS - 4.3+ (支持): 支持 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Geolocation Example</title> <script type="text/javascript" > // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); // 擴展API加載完畢，現在可以正常調用擴展API var wid = null; function onPlusReady() { plus.geolocation.getCurrentPosition( function ( p ) { alert( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude ); }, function ( e ) { alert( "Geolocation error: " + e.message ); } ); } function cancel() { plus.geolocation.clearWatch( wid ); wid = null; } </script> </head> <body > <input type="button" value="Cancel" onclick="cancel();" ></input> </body> </html> ~~~ # [Position]() JSON對象，設備位置信息數據 ~~~ interface Position { readonly attribute Coordinates coords; readonly attribute String coordsType; readonly attribute Number timestamp; } ~~~ ### 屬性： - coords: *([Coordinates](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Coordinates) 類型)*地理坐標信息，包括經緯度、海拔、速度等信息 - coordsType: *(String 類型)*獲取到地理坐標信息的坐標系類型可取以下坐標系類型： “gps”：表示WGS-84坐標系； “gcj02”：表示國測局經緯度坐標系； “bd09”：表示百度墨卡托坐標系； “bd09ll”：表示百度經緯度坐標系。 - timestamp: *(Number 類型)*獲取到地理坐標的時間戳信息時間戳值為從1970年1月1日至今的毫秒數。 # [Coordinates]() JSON對象，地理坐標信息 ~~~ interface Coordinates { readonly attribute double latitude; readonly attribute double longitude; readonly attribute double altitude; readonly attribute double accuracy; readonly attribute double altitudeAccuracy; readonly attribute double heading; readonly attribute double speed; } ~~~ ### 屬性： - latitude: *(Number 類型)*坐標緯度值數據類型對象，地理坐標中的緯度值。 - longitude: *(Number 類型)*坐標經度值數據類型對象，地理坐標中的經度值。 - altitude: *(Number 類型)*海拔信息數據類型對象，如果無法獲取此信息，則此值為空（null）。 - accuracy: *(Number 類型)*地理坐標信息的精確度信息數據類型對象，單位為米，其有效值必須大于0。 - altitudeAccuracy: *(Number 類型)*海拔的精確度信息數據類型對象，單位為米，其有效值必須大于0。如果無法獲取海拔信息，則此值為空（null）。 - heading: *(Number 類型)*表示設備移動的方向數據類型對象，范圍為0到360，表示相對于正北方向的角度。如果無法獲取此信息，則此值為空（null）。如果設備沒有移動則此值為NaN。 - speed: *(Number 類型)*表示設備移動的速度數據類型對象，單位為米每秒（m/s），其有效值必須大于0。如果無法獲取速度信息，則此值為空（null）。 # [PositionOption]() JSON對象，監聽設備位置信息參數 ### 屬性： - enableHighAccuracy: *(Boolean 類型)*是否高精確度獲取位置信息高精度獲取表示需要使用更多的系統資源，默認值為false。 - timeout: *(Number 類型)*獲取位置信息的超時時間單位為毫秒（ms），默認值為不超時。如果在指定的時間內沒有獲取到位置信息則觸發錯誤回調函數。 - maximumAge: *(Number 類型)*獲取位置信息的緩存時間單位為毫秒（ms），默認值為0（立即更新獲取）。如果設備緩存的位置信息超過指定的緩存時間，將重新更新位置信息后再返回。 - provider: *(String 類型)*定位數據的供應者可取以下供應者： “system”：表示系統定位模塊，支持wgs84坐標系； “baidu”：表示百度定位模塊，支持gcj02/bd09/bd09ll坐標系。默認使用“system”值，若指定的provider不存在或無效則返回錯誤回調。注意：百度定位模塊需要配置百度地圖相關參數才能正常使用。 ### 平臺支持 - Android - 2.2+ (支持) - iOS - 4.5+ (支持): provider為“baidu”時，僅支持bd09ll坐標系。 - coordsType: *(String 類型)*指定獲取的定位數據坐標系類型可取以下坐標系類型： “wgs84”：表示WGS-84坐標系； “gcj02”：表示國測局經緯度坐標系； “bd09”：表示百度墨卡托坐標系； “bd09ll”：表示百度經緯度坐標系； provider為“system”時，默認使用“wgs84”類型；provider為“baidu”是，默認使用“bd09ll”類型。如果設置的坐標系類型provider不支持，則返回錯誤。 # [GeolocationSuccessCallback]() 獲取設備位置信息成功的回調函數 ~~~ void onSuccess( position ) { // Get Position code. } ~~~ ### 參數： - position: *( [Position](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Position) ) 必選 *設備的地理位置信息，參考Position ### 返回值： void : 無 # [GeolocationErrorCallback]() 獲取設備位置信息失敗的回調函數 ~~~ void onError( error ) { // Handle error } ~~~ ### 參數： - error: *( DOMException ) 必選 *獲取位置操作的錯誤信息 ### 返回值： void : 無