# 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对象

## 方法：

- setLng: 设置坐标点的经度
- getLng: 获取坐标的经度
- setLat: 设置坐标的纬度
- getLat: 获取坐标的纬度
- equals: 判断两个坐标点是否相等

# 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是地图上显示元素的基类，用于抽象地图元素，不用于实例化。

## 方法：

- isVisible: 判断地图覆盖物是否可见
- show: 显示地图上的覆盖物
- hide: 隐藏地图上的覆盖物

# Marker

地图上显示的标点对象

## 说明：

从Overlay对象继承而来，可通过Map对象的addOverlay()方法将对象添加地图中。

## 构造：

- Marker( point ): 创建地图标点Marker对象

## 方法：

- bringToTop: 覆盖物显示到最上层
- setPoint: 设置标点对象的坐标
- getPoint: 获取标点的坐标
- setIcon: 设置标点上显示的图标
- setIcons: 设置标点上显示的图标数组
- setLabel: 设置标点上显示的文本标注
- getLabel: 获取标点上显示的文本标注
- setBubble: 设置标点的气泡内容
- getBubble: 获取标点上显示的文本标注
- hideBubble: 隐藏标点上显示的气泡
- setDraggable: 设置标点的是否允许拖拽
- isDraggable: 获取标点是否允许拖拽

## 事件：

- onclick: 用户点击地图标点事件
- onDrag: 用户拖拽标点事件

# 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对象

## 属性：

- point: 位置点的经纬度坐标
- address: 位置点的地址信息
- city: 位置点的所属城市信息
- name: 位置点的名称
- phone: 位置点的电话信息
- postcode: 位置点的邮编信息

# 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类型）获取错误描述信息。

## 返回值：

void : 无