geolocation
Geolocation模块管理设备位置信息,用于获取地理位置信息,如经度、纬度等。通过plus.geolocation可获取设备位置管理对象。虽然W3C已经提供标准API获取位置信息,但在某些平台存在差异或未实现,为了保持各平台的统一性,定义此规范接口获取位置信息。
方法:
- getCurrentPosition: 获取当前设备位置信息
- watchPosition: 监听设备位置变化信息
- clearWatch: 关闭监听设备位置信息
对象:
- Position: JSON对象,设备位置信息数据
- Coordinates: JSON对象,地理坐标信息
- PositionOption: JSON对象,监听设备位置信息参数
回调方法:
- GeolocationSuccessCallback: 获取设备位置信息成功的回调函数
- GeolocationErrorCallback: 获取设备位置信息失败的回调函数
权限:
permissions
"Geolocation": { "description": "访问设备位置信息" }
getCurrentPosition
获取当前设备位置信息
void plus.geolocation.getCurrentPosition( successCB, errorCB, option );
说明:
位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取,由于获取位置信息可能需要较长的时间,当成功获取位置信息后将通过successCB回调函数返回。
参数:
- successCB:
(
GeolocationSuccessCallback
)
必选 获取设备位置信息成功回调函数
- errorCB:
(
GeolocationErrorCallback
)
可选 获取设备位置信息失败回调函数
- option:
(
PositionOption
)
可选 获取设备位置信息的参数
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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
)
必选
设备位置信息更新成功回调函数 - errorCB:
(
GeolocationErrorCallback
)
可选
获取设备位置信息失败回调函数 - option:
(
PositionOption
)
可选
监听设备位置信息的参数
返回值:
Number : 用于标识位置信息监听器,可通过clearWatch方法取消监听。平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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 : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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 DOMTimeStamp timestamp; }
属性:
- coords: (Coordinates
类型
)地理坐标信息,包括经纬度、海拔、速度等信息
- timestamp: (DOMTimeStamp
类型
)获取到地理坐标的时间戳信息
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(立即更新获取)。如果设备缓存的位置信息超过指定的缓存时间,将重新更新位置信息后再返回。
GeolocationSuccessCallback
获取设备位置信息成功的回调函数
void onSuccess( position ) { // Get Position code. }
参数:
- position:
(
Position
)
必选 设备的地理位置信息,参考Position
返回值:
void : 无GeolocationErrorCallback
获取设备位置信息失败的回调函数
void onError( error ) { // Handle error }
参数:
- error:
(
DOMException
)
必选 获取位置操作的错误信息