maps
Maps模块管理地图控件,用于在web页面中显示地图控件,提供各种接口操作地图控件,如添加标点、路线等。通过plus.maps可获取地图管理对象。
方法:
- openSysMap: 调用系统第三方程序进行导航
- create: 创建Map对象
- getMapById: 查找已经创建的Map对象
对象:
- Map: 地图控件对象
- MapStyles: 地图控件对象的参数
- GeocodeOptions: 地理编码转换的参数
- CoordinateConvertOptions: 地图坐标转换的参数
- Point: Point对象用于表示地图元素的坐标
- Bounds: 地理区域
- MapType: 地图视图类型
- Overlay: 地图覆盖物基类对象
- Marker: 地图上显示的标点对象
- Bubble: 地图上显示的气泡对象
- Circle: 地图上显示的圆圈对象
- Polyline: 地图上显示的折线对象
- Polygon: 地图上显示的多边形对象
- Search: 地图检索对象
- SearchPolicy: 检索策略类型
- SearchPoiResult: 保存位置检索、周边检索和范围检索返回的结果
- SearchRouteResult: 保存位置检索、周边检索和范围检索返回的结果
- Position: 检索结果的位置点
- Route: 地图中的路线对象
回调方法:
- GeocodeCallback: 地理编码转换成功的回调函数
- CoordinateConvertCallback: 坐标转换成功的回调函数
- DistanceCalculateCallback: 距离计算成功的回调函数
- AreaCalculateCallback: 地理区域面积计算成功的回调函数
- UserLocationCallback: 获取用户当前位置信息成功回调
- ClickEventHandler: 用户点击地图回调事件
- StatusChangedEventHandler: 地图状态变化回调事件
- OverlayClickEventHandler: 用户点击地图覆盖物回调事件
- OverlayDragEventHandler: 用户拖拽覆盖物回调事件
- PoiSearchCallback: 兴趣点检索完成事件
- RouteSearchCallback: 线路检索完成事件
- SuccessCallback: 地图操作成功回调函数
- ErrorCallback: 地图操作失败的回调函数
权限:
permissions
{ // ... "permissions":{ // ... "Maps": { "description": "地图" } } }
Map
地图控件对象
构造:
- Map(domId, styles): 创建Map对象
方法:
- calculateArea: 静态方法,计算面积
- calculateDistance: 静态方法,计算距离
- convertCoordinates: 静态方法,坐标转换
- geocode: 静态方法,地理编码
- reverseGeocode: 静态方法,反向地理编码
- addOverlay: 向地图中添加覆盖物
- centerAndZoom: 设置地图初始中心点和缩放级别
- clearOverlays: 清除地图中所有覆盖物对象
- close: 关闭地图控件
- getBounds: 获取当前地图可视范围的地理区域
- getCenter: 获取地图中心点位置
- getCurrentCenter: 获取当前地图显示的地图中心点位置
- getMapType: 获取地图的显示类型
- getUserLocation: 获取用户的当前位置信息
- getZoom: 获取地图的缩放级别
- hide: 隐藏地图控件
- isShowUserLocation: 获取是否显示用户位置
- isShowZoomControls: 获取是否显示地图内置缩放控件
- isTraffic: 获取是否打开地图交通信息图层
- removeOverlay: 从地图中删除覆盖物对象
- reset: 重置地图
- resize: 重设地图控件大小
- setCenter: 设置地图的中心点
- setMapType: 设置地图的视图类型
- setStyles: 设置地图控件的配置参数
- setTraffic: 是否打开地图交通信息图层
- setZoom: 设置地图的缩放级别
- show: 显示地图控件
- showUserLocation: 显示用户位置
- showZoomControls: 设置是否显示地图内置缩放控件
事件:
- onclick: 用户点击地图事件
- onstatuschanged: 地图状态改变事件
MapStyles
地图控件对象的参数
interface plus.maps.MapStyles { attribute Point center; attribute Number zoom; attribute MapType type; attribute Boolean traffic; attribute Boolean zoomControls; attribute String top; attribute String left; attribute String width; attribute String height; attribute String position; }
说明:
设置地图对象显示时使用的参数,如地图的中心位置、缩放级别等。
属性:
- center: (Point
类型
)地图的中心位置
未设置则使用地图的默认中心点(由地图供应商确定)。
- zoom: (Number
类型
)地图的缩放级别
有效范围为有效范围为3-21(高德地图为3-20,百度地图为4-21),默认值为12,设置无效的值则使用默认值。
- type: (MapType
类型
)地图的视图类型
可设置普通街道视图、卫星视图,默认值为普通街道视图。
- traffic: (Boolean
类型
)地图的是否显示交通信息
true表示显示地图的交通信息图层,false则不显示,默认值为false。
- zoomControls: (Boolean
类型
)是否显示地图的内置缩放控件
true表示显示地图的内置缩放控件,false则不显示,默认值为false。
- top: (String
类型
)地图控件左上角的垂直偏移量
可取值: 像素值,如"100px"; 百分比,如"10%",相对于父Webview窗口的高度; 自动计算,如"auto",根据height值自动计算,相对于父Webview窗口垂直居中。
- left: (String
类型
)地图控件左上角的水平偏移量
可取值: 像素值,如"100px"; 百分比,如"10%",相对于父Webview窗口的宽度; 自动计算,如"auto",根据width值自动计算,相对于父Webview窗口水平居中。 默认值为"0px"。
- width: (String
类型
)地图控件的宽度
可取值: 像素值,如"100px"; 百分比,如"10%",相对于父Webview窗口的宽度。 默认值为"100%"。
- height: (String
类型
)地图控件的高度
可取值: 像素值,如"100px"; 百分比,如"10%",相对于父Webview窗口的高度。 默认值为"100%"。
- position: (String
类型
)地图控件在Webview窗口的布局模式
可取值: "static" - 静态布局模式,如果页面存在滚动条则随窗口内容滚动; "absolute" - 绝对布局模式,如果页面存在滚动条不随窗口内容滚动; 默认值为"static"。
GeocodeOptions
地理编码转换的参数
属性:
- coordType: (String
类型
)源数据的坐标系类型
仅在反向地理编码转换时生效。 “wgs84”:表示WGS-84坐标系; “gcj02”:表示国测局经纬度坐标系; “bd09”:表示百度墨卡托坐标系; “bd09ll”:表示百度经纬度坐标系; 默认使用wgs84坐标系。
- city: (String
类型
)源地址所属的城市
仅在地理编码转换时生效,如果不指定则在全国范围内区配转换。
CoordinateConvertOptions
地图坐标转换的参数
属性:
- coordType: (String
类型
)源数据的坐标系类型
“wgs84”:表示WGS-84坐标系; “gcj02”:表示国测局经纬度坐标系; “bd09”:表示百度墨卡托坐标系; “bd09ll”:表示百度经纬度坐标系; 默认使用wgs84坐标系。
Point
Point对象用于表示地图元素的坐标
说明:
常用语对地图上元素进行定位时使用。
构造:
- Point(lng,lat): 创建Point对象
方法:
Bounds
地理区域
说明:
有西南及东北坐标点数据组成的矩形区域。
构造:
- Bounds(northease,southwest): 创建Bounds对象
- Bounds(nelng,nelat,swlng,swlat): 创建Bounds对象
方法:
- setNorthEase: 设置地理区域的东北坐标点
- getNorthEase: 地理区域的东北坐标点
- setSouthWest: 设置地理区域的西南坐标点
- getSouthWest: 地理区域的西南坐标点
- contains: 判断制定的坐标是否在地理区域中
- equals: 判断两个地理区域是否相等
- getCenter: 获取地理区域的中心点坐标
MapType
地图视图类型
常量:
- MAPTYPE_NORMAL: (Number
类型
)普通街道视图类型
地图视图类型常量,普通街道视图。
- MAPTYPE_SATELLITE: (Number
类型
)卫星视图
地图视图类型常量,卫星视图。
Overlay
地图覆盖物基类对象
interface Overlay { function Boolean isVisible(); function void show(); function void hide(); }
说明:
Overlay是地图上显示元素的基类,用于抽象地图元素,不用于实例化。
方法:
Marker
地图上显示的标点对象
说明:
从Overlay对象继承而来,可通过Map对象的addOverlay()方法将对象添加地图中。
构造:
- Marker( point ): 创建地图标点Marker对象
方法:
- bringToTop: 覆盖物显示到最上层
- setPoint: 设置标点对象的坐标
- getPoint: 获取标点的坐标
- setIcon: 设置标点上显示的图标
- setIcons: 设置标点上显示的图标数组
- setLabel: 设置标点上显示的文本标注
- getLabel: 获取标点上显示的文本标注
- setBubble: 设置标点的气泡内容
- getBubble: 获取标点上显示的文本标注
- hideBubble: 隐藏标点上显示的气泡
- setDraggable: 设置标点的是否允许拖拽
- isDraggable: 获取标点是否允许拖拽
事件:
Bubble
地图上显示的气泡对象
说明:
此对象不能直接添加到地图上显示,只可关联到地图标点覆盖物上,用户点击标点时弹出显示。
构造:
- Bubble( label ): 创建气泡对象
方法:
- setIcon: 设置气泡上显示的图标
- setLabel: 设置气泡上显示的文字内容
- getLabel: 获取气泡上显示的文字内容
- belongMarker: 获取气泡所属的标点对象
- loadImage: 从图片加载气泡显示的内容
- loadImageDataURL: 从图片数据加载气泡显示的内容
事件:
- onclick: 用户点击气泡事件
Circle
地图上显示的圆圈对象
说明:
从Overlay对象继承而来,可通过Map对象的addOverlay()方法将对象添加地图中。
构造:
- Circle( center, radius ): 创建Circle对象
方法:
- setCenter: 设置圆圈中心点的经纬度坐标
- getCenter: 获取圆圈中心点的坐标
- setRadius: 设置圆圈的半径,单位为米
- getRadius: 获取圆圈的半径
- setStrokeColor: 设置圆圈的边框颜色
- getStrokeColor: 获取圆圈的边框颜色
- setStrokeOpacity: 设置圆圈的边框颜色
- getStrokeOpacity: 获取圆圈边框的透明度
- setFillColor: 设置圆圈的填充颜色
- getFillColor: 获取圆圈的填充颜色
- setFillOpacity: 设置圆圈填充颜色的透明度
- getFillOpacity: 获取圆圈填充色的透明度
- setLineWidth: 设置圆圈边框的线条宽度
- getLineWidth: 获取圆圈边框的线条宽度
Polyline
地图上显示的折线对象
说明:
从Overlay对象继承而来,可通过Map对象的addOverlay()方法将对象添加地图中。
构造:
- Polyline( points ): 创建Polyline对象
方法:
- setPath: 设置折线的顶点坐标
- getPath: 获取折线的顶点坐标
- setStrokeColor: 设置折线的颜色
- getStrokeColor: 获取折线的颜色
- setStrokeOpacity: 设设置折线的透明度
- getStrokeOpacity: 获取折线的透明度
- setLineWidth: 设置折线的线条宽度
- getLineWidth: 获取折线的线条宽度
Polygon
地图上显示的多边形对象
说明:
从Overlay对象继承而来,可通过Map对象的addOverlay()方法将对象添加地图中。
构造:
- Polygon( points ): 创建Polygon对象
方法:
- setPath: 设置多边形的顶点坐标
- getPath: 获取多边形的顶点坐标
- setStrokeColor: 设置多边形的颜色
- getStrokeColor: 获取多边形边框的颜色
- setStrokeOpacity: 设置多边形的透明度
- getStrokeOpacity: 获取多边形边框的透明度
- setFillColor: 设置多边形的填充颜色
- getFillColor: 获取多边形的填充色
- setFillOpacity: 设置多边形填充色的透明度
- getFillOpacity: 获取多边形填充色的透明度
- setLineWidth: 设置多边形的边框宽度
- getLineWidth: 获取多边形边框的宽度
Search
地图检索对象
说明:
Search对象用于管理地图上的检索功能,包括位置检索、周边检索和范围检索。
构造:
- Search( map ): 创建Search对象
方法:
- setPageCapacity: 设置检索返回结果每页的信息数目
- getPageCapacity: 获取检索返回结果每页的信息数目
- poiSearchInCity: 城市兴趣点检索
- poiSearchNearBy: 周边检索
- poiSearchInbounds: 指定范围检索
- setTransitPolicy: 设置公交路线检索策略
- transitSearch: 公交路线检索
- setDrivingPolicy: 设置驾车路线检索策略
- drivingSearch: 驾车路线检索
- walkingSearch: 步行路线检索
事件:
- onPoiSearchComplete: 兴趣点检索完成事件
- onRouteSearchComplete: 线路检索完成事件
SearchPolicy
检索策略类型
说明:
在线路检索时设置检索策略时使用。
常量:
- TRANSIT_TIME_FIRST: (Number
类型
)时间优先
检索策略类型常量,用于公交检索策略
- TRANSIT_TRANSFER_FIRST: (Number
类型
)最少换乘优先
检索策略类型常量,用于公交检索策略
- TRANSIT_WALK_FIRST: (Number
类型
)最少步行距离优先
检索策略类型常量,用于公交检索策略
- TRANSIT_FEE_FIRST: (Number
类型
)选择车票花销最少优先
检索策略类型常量,用于公交检索策略
- DRIVING_DIS_FIRST: (Number
类型
)最短距离优先
检索策略类型常量,用于驾车检索策略
- DRIVING_NO_EXPRESSWAY: (Number
类型
)无高速公路线路
检索策略类型常量,用于驾车检索策略
- DRIVING_FEE_FIRST: (Number
类型
)最少费用优先
检索策略类型常量,用于驾车检索策略
SearchPoiResult
保存位置检索、周边检索和范围检索返回的结果
属性:
- totalNumber: POI检索总结果数
- currentNumber: 当前页的POI检索结果数
- pageNumber: 本次POI检索的总页数
- pageIndex: 获取当前页的索引
- poiList: 本次POI检索结果数组
方法:
- getPosition: 获取指定索引的检索结果
SearchRouteResult
保存位置检索、周边检索和范围检索返回的结果
说明:
不可通过new操作符创建SearchRouteResult对象,在触发onRouteSearchComplete()时自动创建。
属性:
- startPosition: 线路的起点位置
- endPosition: 线路的终点位置
- routeNumber: 本次线路检索的总方案数
- routeList: 线路检索结果数组
方法:
- getRoute: 获取指定索引的线路方案
Position
检索结果的位置点
构造:
- Position( point ): 创建Position对象
属性:
Route
地图中的路线对象
说明:
从Overlay对象继承而来,可通过Map对象的addOverlay()方法将对象添加地图中。
构造:
- Route( ptStart, ptEnd ): 创建Route对象
属性:
- startPoint: 路线起点地理坐标点
- endPoint: 路线终点地理坐标点
- pointCount: 路线坐标点段数
- pointList: 路线的地理坐标点数组
- distance: 路线总距离
- routeTip: 线路的提示信息
GeocodeCallback
地理编码转换成功的回调函数
void onGeocodeSuccess( Event event ) { // JS code. var address = event.address; // 转换后的地理位置 var point = event.coord; // 转换后的坐标信息 var coordType = event.coordType; // 转换后的坐标系类型 }
说明:
在地理编码转换成功触发,并返回转换结果。
参数:
- event:
(
Event
)
可选 转换后的坐标信息
可通过event.coord(Point类型)获取转换后的坐标值。 可通过event.coordType(String类型)获取转换后的坐标系类型,“wgs84”:表示WGS-84坐标系; “gcj02”:表示国测局经纬度坐标系; “bd09”:表示百度墨卡托坐标系; “bd09ll”:表示百度经纬度坐标系。
返回值:
void : 无CoordinateConvertCallback
坐标转换成功的回调函数
void onConvertSuccess( Event event ) { // JS code. var point = event.coord; // 转换后的坐标值 var coordType = event.coordType; // 转换后的坐标系类型 }
说明:
在坐标转换成功触发,并返回转换结果。
参数:
- event:
(
Event
)
可选 转换后的坐标信息
可通过event.coord(Point类型)获取转换后的坐标值。 可通过event.coordType(String类型)获取转换后的坐标系类型,“wgs84”:表示WGS-84坐标系; “gcj02”:表示国测局经纬度坐标系; “bd09”:表示百度墨卡托坐标系; “bd09ll”:表示百度经纬度坐标系。
返回值:
void : 无DistanceCalculateCallback
距离计算成功的回调函数
void onCalculateSuccess( Event event ) { // JS code. var distance = event.distance; // 转换后的距离值 }
说明:
在距离计算成功触发,并返回计算结果。
参数:
- event:
(
Event
)
可选 距离计算后的信息
可通过event.distance(Number类型)获取计算后的距离值,单位为米(m)。
返回值:
void : 无AreaCalculateCallback
地理区域面积计算成功的回调函数
void onCalculateSuccess( Event event ) { // JS code. var area = event.area; // 计算后的面积值 }
说明:
在地理区域面积计算成功触发,并返回计算结果。
参数:
- event:
(
Event
)
可选 地理区域面积计算后的信息
可通过event.area(Number类型)获取计算后的面积值,单位为平方米。
返回值:
void : 无UserLocationCallback
获取用户当前位置信息成功回调
void onSuccess( state, point ) { // Get location code }
参数:
- state:
(
Number
)
必选 获取用户位置操作状态码,0表示成功,其它为错误码
- point:
(
Point
)
必选 位置经纬度坐标,如果获取操作失败则为null对象
返回值:
void : 无ClickEventHandler
用户点击地图回调事件
void onClick( point ) { // Click code }
参数:
- point:
(
Point
)
必选 用户在地图上点击的坐标点
返回值:
void : 无StatusChangedEventHandler
地图状态变化回调事件
void onStatusChanged( event ) { // Click code var target = event.target; // 状态变化的地图对象(plus.maps.Map) var bounds = event.bounds; // 地图的可视地理区域(plus.maps.Bounds) var center = event.center; // 地图的中心点坐标(plus.maps.Point) var zoom = event.zoom; // 地图的缩放级别(Number) }
参数:
- event:
(
Event
)
必选 地图状态变化对象
可通过event.target(plus.maps.Map类型)获取状态变化的地图对象; 可通过event.bounds(plus.maps.Bounds类型)获取地图当前的可视区域; 可通过event.center(plus.maps.Point类型)获取地图当前的中心点坐标; 可通过event.zoom(Number类型)获取地图当前的缩放级别。
返回值:
void : 无OverlayClickEventHandler
用户点击地图覆盖物回调事件
void onClick( overlay ) { // Click code }
参数:
- overlay:
(
Overlay
)
必选 用户在地图上点击的覆盖物对象
overlay可以是Marker、Bubble、Circle、Polyline、Polygon对象的引用。
返回值:
void : 无OverlayDragEventHandler
用户拖拽覆盖物回调事件
void onDrag( target ) { // Click code var marker = target; // 拖拽的覆盖物对象 }
参数:
- target:
(
Event
)
必选 拖拽事件对象
可通过target(Overlay类型)获取拖拽的覆盖物对象,target可以是Marker、Bubble、Circle、Polyline、Polygon对象的引用。
返回值:
void : 无PoiSearchCallback
兴趣点检索完成事件
void onPoiSearchComplete( state, result ) { // JS code. }
说明:
在兴趣点检索完成时触发,并返回检索结果。
参数:
- state:
(
Number
)
必选 检索结果状态号
0表示检索正确并返回结果,其它表示检索错误。 - result:
(
SearchPoiResult
)
必选 POI检索结果
若检索错误,则为null对象。
返回值:
void : 无RouteSearchCallback
线路检索完成事件
void onRouteSearchComplete( state, result ) { // JS code. }
说明:
在线路检索完成时触发,并返回检索结果。
参数:
- state:
(
Number
)
必选 检索结果状态号
0表示检索正确并返回结果,其它表示检索错误。 - result:
(
SearchRouteResult
)
必选 线路检索结果
若检索错误,则为null对象。
返回值:
void : 无SuccessCallback
地图操作成功回调函数
void onSuccess(){ // Success code. }
说明:
地图操作成功后触发回调函数。
参数:
无
返回值:
void : 无ErrorCallback
地图操作失败的回调函数
function void onError( error ) { // Handle error var code = error.code; // 错误编码 var message = error.message; // 错误描述信息 }
参数:
- error:
(
Exception
)
必选 地图操作的错误信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。