Map

---

    API中的核心类，用于创建地图实例。

创建Map类的语法	参数
new TMap.Map(domId, options);	domId : {string}     (必填) 地图DOM容器的id，创建地图需要在页面中创建一个空div元素，传入该div元素的id options : {MapOptions}     地图参数，对象规范详见 MapOptions

方法	返回值	说明
setCenter(center:LatLng)	this	设置地图中心点。
setZoom(zoom:Number)	this	设置地图缩放级别。
setRotation(rotation:Number)	this	设置地图水平面上的旋转角度。
setPitch(pitch:Number)	this	设置地图俯仰角。
setScale(scale:Number)	this	设置地图显示比例。
setOffset(offset: Object)	this	设置地图与容器偏移量，Object的格式为{x:Number, y:Number}，x方向向右偏移为正值，y方向向下偏移为正值；中心点偏移功能不支持与MVTLayer共同使用。
setCursorStyle(style:String)	this	设置地图鼠标样式，需要符合css cursor规范
setDraggable(draggable:Boolean)	this	设置地图是否支持拖拽。
setScrollable(scrollable:Boolean)	this	设置地图是否支持滚轮缩放。
setMaxZoom(maxZoom:Number)	this	设置地图最大缩放级别，支持3～20。
setMinZoom(minZoom:Number)	this	设置地图最小缩放级别，支持3～20。
setPitchable(pitchable:Boolean)	this	设置地图是否支持改变俯仰角度。在2D视图下，此方法无效。
setRotatable(rotatable:Boolean)	this	设置地图是否支持改变旋转角度。在2D视图下，此方法无效。
setTouchZoomable(touchZoomable:Boolean)	this	设置地图是否支持手势缩放。
setDoubleClickZoom(doubleClickZoom: Boolean)	this	设置地图是否支持双击缩放。
setBoundary(boundary:LatLngBounds)	this	设置地图限制边界，拖拽、缩放等操作无法将地图移动至边界外。
setSkyOptions(options: SkyOptions)	this	设置地图天空背景
setViewMode(viewMode: String)	this	设置地图视图模式。
setBaseMap(baseMap:BaseMap I BaseMap[])	this	动态设置地图底图，BaseMap目前支持矢量底图（VectorBaseMap）、卫星底图（SatelliteBaseMap）、路况底图（TrafficBaseMap），可以使用数组形式实现多种底图叠加。
setMapStyleId(mapStyleId: String)	this	动态设置个性化地图样式。
panTo(latLng:LatLng, opts:EaseOptions)	this	将地图中心平滑移动到指定的经纬度坐标。
zoomTo(zoom:Number, opts:EaseOptions)	this	平滑缩放到指定级别。
rotateTo(rotation:Number, opts:EaseOptions	this	平滑旋转到指定角度。
pitchTo(pitch:Number, opts:EaseOptions)	this	平滑变化到指定俯仰角度。
easeTo(mapStatus:Object, opts:EaseOptions)	this	平滑过渡到指定状态，mapStatus为key-value格式，可以设定center、zoom、rotation、pitch。
fitBounds(bounds:LatLngBounds,options:FitBoundsOptions)	this	根据指定的地理范围调整地图视野。
getCenter()	LatLng	获取地图中心。
getZoom()	Number	获取地图缩放级别。
getRotation()	Number	获取地图水平面上的旋转角度。
getPitch()	Number	获取地图俯仰角度。
getBounds()	LatLngBounds	返回当前地图的视野范围，该视野范围实际会大于等于地图的可视区域范围，尤其是当地图发生旋转和俯仰变化时，得到的是一个当前视野范围的最小外包矩形。
getScale()	Number	获取地图显示比例。
getOffset()	Object	获取地图与容器的偏移量Object的格式为 {x:Number, y:Number}，x方向向右偏移为正值，y方向向下偏移为正值。
getCursorStyle()	String	获取地图鼠标样式
getDraggable()	Boolean	获取地图是否支持拖拽。
getScrollable()	Boolean	获取地图是否支持滚轮缩放。
getTouchZoomable()	Boolean	获取地图是否支持手势缩放。
getDoubleClickZoom()	Boolean	获取地图是否支持双击缩放。
getBoundary()	LatLngBounds	获取地图限制边界。
addControl(control:Control)	this	添加控件到地图,传入控件对象。
removeControl(id: String)	this	从地图容器移出控件,默认控件的id列表参考 DEFAULT_CONTROL_ID
getControl(id: String)	Control	根据控件id获取对应的控件对象,默认控件的id列表参考 DEFAULT_CONTROL_ID。
getViewMode()	String	获取地图视图模式。
getBaseMap()	BaseMap I BaseMap[]	获取当前的底图类型。
getIndoorManager()	IndoorManager	获取室内地图管理器。
destroy()		销毁地图。
projectToContainer(latLng: LatLng)	Point	经纬度坐标转换为容器像素坐标，容器像素坐标系以地图容器左上角点为原点。
unprojectFromContainer(pixel: Point)	LatLng	容器像素坐标转换为经纬度坐标。
on(eventName:String, listener:Function)	this	添加listener到eventName事件的监听器数组中。
off(eventName:String, listener:Function)	this	从eventName事件的监听器数组中移除指定的listener。
once(eventName:String, listener:Function)	this	添加listener到eventName事件的监听器数组中，一次性监听，listener执行一次后自动移除监听器
moveLayer(layerId: String, level: LAYER_LEVEL)	this	修改图层层级顺序，根据输入 LAYER_LEVEL 常量调整 layerId 对应图层的渲染层级 ，其中layerId可以通过图层getId方法获取。注： 设置ZIndex 可调整同一大类层级下的不同图层顺序，此方法则是调整目标图层的大类层级。
startAnimation(keyFrames: MapKeyFrame[], opts: AnimationOptions)	none	开始动画，通过keyFrames定义关键帧 ，查看示例
stopAnimation()	none	停止动画，停止后无法通过resumeAnimation恢复
pauseAnimation()	none	暂停动画
resumeAnimation()	none	恢复动画
enableAreaHighlight(opts: highlightOptions)	this	启用地图区域高亮功能， 查看示例
disableAreaHighlight()	this	禁用地图区域高亮功能
enableAreaClip(opts: ClipOptions)	this	启用地图区域掩膜功能
disableAreaClip()	this	停用地图区域掩膜功能

事件名	参数	说明
idle	none	地图进入空闲状态时触发。
tilesloaded	none	当地图容器中可见的瓦片加载完后会触发此事件。
click	evt:MapEvent	鼠标左键单击地图时触发，移动与桌面web都触发。
rightclick	evt:MapEvent	鼠标右键单击地图时触发，只在桌面浏览器触发。
dblclick	evt:MapEvent	鼠标左键双击地图时触发，移动与桌面web都触发。
mousedown	evt:MapEvent	鼠标在地图区域中按下时触发，只在桌面浏览器中触发。
mouseup	evt:MapEvent	鼠标在地图区域中按下又弹起时触发，只在桌面浏览器中触发。
mousemove	evt:MapEvent	鼠标在地图上移动时触发，只在桌面浏览器中触发。
touchstart	evt:MapEvent	在地图区域触摸开始时触发，只在移动浏览器中触发。
touchmove	evt:MapEvent	在地图区域触摸移动时触发，只在移动浏览器中触发。
touchend	evt:MapEvent	在地图区域触摸结束时触发，只在移动浏览器中触发。
dragstart	none	地图开始发生拖拽交互时触发。
drag	none	地图发生拖拽交互时触发，拖拽交互可能产生pan，rotate, picth事件。
dragend	none	地图拖拽交互结束时触发。
panstart	none	地图开始平移时触发。
pan	none	地图移动时触发。
panend	none	地图平移结束时触发。
rotatestart	none	地图开始旋转时触发。
rotate	none	地图旋转时触发。
rotateend	none	地图旋转结束时触发。
pitchstart	none	地图开始发生俯仰角变化时触发。
pitch	none	地图俯仰角变化时触发。
pitchend	none	地图俯仰角变化结束时触发。
zoom	none	地图缩放时触发。
resize	none	地图容器大小发生变化时触发。
center_changed	none	当地图中心点变化时会触发此事件。
bounds_changed	none	当可视区域范围更改时会触发此事件。
scale_changed	none	地图显示比例变化时触发此事件。
control_added	none	给map添加控件的时候触发此事件。
control_removed	none	从map移出控件的时候触发此事件。
animation_playing	AnimationEvent	动画进行中
animation_looped	Number	动画进入下一循环，返回循环序号
animation_ended	none	动画结束
animation_stopped	none	动画停止
context_lost		地图渲染上下文丢失时触发此事件；地图渲染依赖浏览器硬件加速(GPU)，浏览器对硬件加速的使用存在限制，当整个浏览器使用硬件加速的元素过多时，未防止整个GPU崩溃导致设备黑屏，浏览器会自动会将之前元素使用的硬件资源回收，导致该元素无法继续渲染（浏览器丢车保帅的策略）；当触发此事件时，需要检查业务代码是否使用了过多的硬件加速资源（如创建太多**WebGLRenderingContext** 、 WebGL2RenderingContext 、 GPUCanvasContext ）
destroyed		地图被完全销毁时触发此事件

示例1：
    本示例中，介绍如何在div容器中创建地图

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>简单地图</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <script charset="utf-8" src="https://map.qq.com/api/gljs?v=1.exp&key=OB4BZ-D4W3U-B7VVO-4PJWW-6TKDJ-WPB77"></script>
    <style type="text/css">
        html,
        body {
            height: 100%;
            margin: 0px;
            padding: 0px
        }
        #container {
            width: 100%;
            height: 100%
        }
    </style>
</head>
 
<body onload="initMap()">
    <div id="container"></div>
    <script type="text/javascript">
    function initMap() {
        var container = document.getElementById("container");
        var center = new TMap.LatLng(39.984104, 116.307503);
        //初始化地图
        var map = new TMap.Map(container, {
            rotation: 20,//设置地图旋转角度
            pitch:30, //设置俯仰角度（0~45）
            zoom:12,//设置地图缩放级别
            center: center//设置地图中心点坐标
        });
    }
    </script>
</body>
</html>

新窗口打开   在线试一试

示例2：
    本示例中，介绍如何异步加载api展现地图

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>异步加载地图</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <style type="text/css">
        html,
        body {
            height: 100%;
            margin: 0px;
            padding: 0px
        }
        #container {
            width: 100%;
            height: 100%
        }
    </style>
</head>
 
<body>
    <div id="container"></div>
    <script>
    function initMap() {
        var map = new TMap.Map("container", {
            pitch:45,
            zoom:12,
            center: new TMap.LatLng(39.984104, 116.307503)
        });
    }
    function loadScript() {
        //创建script标签，并设置src属性添加到body中
        var script = document.createElement("script");
        script.type = "text/javascript";
        script.src = "https://map.qq.com/api/gljs?v=1.exp&key=OB4BZ-D4W3U-B7VVO-4PJWW-6TKDJ-WPB77&callback=initMap";
        document.body.appendChild(script);
    }
    window.onload = loadScript;
    </script>
</body>
</html>

新窗口打开   在线试一试

MapOptions

---

    地图配置参数，通过这个参数来控制初始化地图的中心点、缩放级别、俯仰角度等。

属性名称	类型	说明
center	LatLng	地图中心点经纬度。
zoom	Number	地图缩放级别，支持3～22。
minZoom	Number	地图最小缩放级别，默认为3。
maxZoom	Number	地图最大缩放级别，默认为20。
rotation	Number	地图在水平面上的旋转角度，顺时针方向为正，默认为0。
pitch	Number	地图俯仰角度，取值范围为0~80，默认为0。
scale	Number	地图显示比例，默认为1。
offset	Object	地图中心与容器的偏移量，Object的格式为 {x:Number, y:Number}（右方下方为正，单位为像素）；中心点偏移功能不支持与MVTLayer共同使用。
cursor	String	地图鼠标样式，需要符合css cursor属性规范，默认为’default’
draggable	Boolean	是否支持拖拽移动地图，默认为true。
scrollable	Boolean	是否支持鼠标滚轮缩放地图，默认为true。
touchZoomable	Boolean	是否允许手势捏合缩放；默认为true。
pitchable	Boolean	是否允许设置俯仰角度；默认为true。在2D视图下，此属性无效。
rotatable	Boolean	是否允许设置旋转角度；默认为true。在2D视图下，此属性无效。
doubleClickZoom	Boolean	是否支持双击缩放地图，默认为true。
mapZoomType	MAP_ZOOM_TYPE	地图缩放焦点控制。
boundary	LatLngBounds	地图边界，设置后拖拽、缩放等操作无法将地图移动至边界外，默认为null。
mapStyleId	String	地图样式ID，有效值为”style[编号]”，与key绑定，详见 个性化地图配置页面。
baseMap	BaseMap I BaseMap[]	地图底图，BaseMap目前只支持矢量底图 （VectorBaseMap） 、卫星底图 （SatelliteBaseMap） 、路况底图 （TrafficBaseMap） ，可以使用数组形式实现多种底图叠加。默认为 VectorBaseMap ，如果传入null地图不显示任何地物。
viewMode	String	地图视图模式，支持2D和3D，默认为3D。2D模式下不可对地图进行拖拽旋转，pitch和rotation始终保持为0。
showControl	Boolean	是否显示地图上的控件，默认true。
renderOptions	MapRenderOptions	地图渲染配置参数
clip	ClipOptions	clip区域掩膜配置参数

MapRenderOptions

---

  地图渲染配置参数属性

名称	类型	说明
preserveDrawingBuffer	Boolean	保留地图的渲染缓冲，在一些结合开源库需要导出图片的场景下（如 dom-to-image html2canvas），需要设置这个参数为true；默认为false，查看示例
enableBloom	Boolean	是否启用泛光效果（请确认浏览器支持WebGL2）
fogOptions	fogOptions	边际雾化设置
skyOptions	SkyOptions	天空背景设置

SkyOptions 对象规范

---

  天空背景设置，可控制天空颜色、纹理和动态效果。

名称	类型	说明
color	String	天空颜色，若使用纯色天空背景，可通过此参数设置天空颜色，支持#RRGGBB、rgb()、rgba()格式
src	String	天空纹理，若使用图片作为天空背景，可通过此参数设置天空纹理，可传入图片url或者base64编码。纹理图将头尾相接形成360度环形，跟随地图旋转。 图片支持png、jpeg、jpg格式。 建议图片分辨率 4096 * 700，如果天空出现黑色背景请降低图片分辨率直至图片显示。
width	Number	纹理宽度，不大于图片真实宽度
height	Number	纹理高度，不大于图片真实高度
horizontal	IMAGE_DISPLAY	纹理水平方向呈现方式，默认为IMAGE_DISPLAY.SCALE，拉伸铺满
vertical	IMAGE_DISPLAY	纹理纵向呈现方式，默认为IMAGE_DISPLAY.ORIGIN，保持原图片高度
brightness	Number	天空亮度，默认为1
animated	Boolean	是否开启云雾动画效果，默认为false

FogOptions 对象规范 对象规范

---

雾化参数。

名称	类型	说明
color	String	雾气颜色，支持#RRGGBB和rgb()格式，若不设置则使用矢量地图地面颜色

FitBoundsOptions

---

    地图自适应地理范围配置参数，可控制边距以及限制缩放等级。

属性名称	类型	说明
padding	Number I Object	设定的地理范围与可视窗口之间的距离，可以通过{top:Number, bottom:Number, left:Number, right:Number}的格式明确各方向的边距，或仅传入一个数字统一各方向的边距，不可为负数。
minZoom	Number	调整视野时的最小缩放等级，默认值且最小值为地图的最小缩放等级。
maxZoom	Number	调整视野时的最大缩放等级，默认值且最大值为地图的最大缩放等级。
ease	EaseOptions	缓动配置，可设置地图视野变化过程的动画效果。

AnimationOptions 对象规范

---

动画参数。

名称	类型	说明
duration	Number	动画周期时长，单位为ms，默认为1000
loop	Number	动画周期循环次数，若为Infinity则无限循环，默认为1

AnimationEvent 对象规范

---

动画事件回调参数规范。

名称	类型	说明
percentage	Number	动画进行百分比
frame	Object	当前帧状态

MapKeyFrame 对象规范

---

地图动画关键帧对象。

名称	类型	说明
percentage	Number	动画过程中该关键帧的百分比，取值范围为0~1
center	LatLng	地图中心点经纬度
zoom	Number	地图缩放级别
rotation	Number	地图在水平面上的旋转角度
pitch	Number	地图俯仰角度，取值范围为0~80

HighlightOptions 对象规范

地图高亮区域设置。

名称	类型	说明
paths	LatLng[]	高亮区域轮廓坐标点串
highlightColor	String	高亮色，区域内地图元素将与该色进行混合，支持rgb()，rgba()，#RRGGBB等形式，默认为rgba(0, 0, 0, 0)
shadeColor	String	阴影色，区域外地图元素将与该色进行混合，支持rgb()，rgba()，#RRGGBB等形式，默认为rgba(0, 0, 0, 0.4)

ClipOptions 对象规范

地图掩膜区域设置。

名称	类型	说明
paths	LatLng[]	掩膜区域轮廓坐标点串

EaseOptions

---

    地图缓动变化配置参数，可控制动画时长等。

属性名称	类型	说明
duration	Number	缓动动画时长，单位为ms，默认为500。

VectorBaseMap

---

    VectorBaseMap 对象规范

属性名称	类型	说明
type	String	必须为vector。
features	String[]	矢量底图要素类型，通过控制features可以控制矢量底图中不同类型要素的显示与否，目前支持道路及底面（base）、建筑物（building3d）、建筑物平面(building2d)、poi文字（point）、道路文字（label）、道路箭头（arrow）；若features为非数组则默认为全部显示，若features为空数组不显示任何地物。
buildingRange	Number[]	[min, max], 用于设置建筑物显示层级区间。min默认值为16.5, 最小值不低于14.5， 低于14.5则按照min=14.5 进行建筑渲染。max 默认值为20，若地图实例启用了enableExtendZoom则默认值为25。buildingRange仅当features中包含building2d或者building3d时生效。

SatelliteBaseMap

---

    SatelliteBaseMap 对象规范

属性名称	类型	说明
type	String	必须为satellite。
features	String[]	卫星图要素类型，目前支持卫星影像图（base）、路网图（road）；若features为非数组则默认为全部显示，若features为空数组不显示任何地物。

TrafficBaseMap

---

    TrafficBaseMap 对象规范

属性名称	类型	说明
type	String	须为traffic。
features	String[]	路况图要素类型，目前支持路况线网（base）、流动粒子（flow），默认为只显示路况线网图。
filter	String[]	指定特定类型的道路才显示路况，对线网和粒子图同时生效，可选值高速"highway"，快速路 “motorway” ，国道"national"，省道"provincial"，县道"county"，乡道"country"，其他道路"other"。默认不传或者传入非数组对象都显示，空数组都所有道路路况都不显示。
opacity	Number	路况线网图的透明度，默认为1。
flowColor	String[]	路况流动粒子颜色组合，长度为4的数组，0-3位分别对应流畅、缓行、拥堵、极度拥堵，颜色支持rgb()，rgba()，#RRGGBB等形式。
flowSpeed	Number[]	路况流动粒子速度组合，长度为4的数组，0-3位分别对应流畅、缓行、拥堵、极度拥堵，单位为pixel/s，默认为[80, 30, 10, 5] 。

TMap.constants.MAP_ZOOM_TYPE 常量说明

---

    地图缩放焦点常量。

常量	说明
MAP_ZOOM_TYPE.DEFAULT	默认缩放，双指中心位置（移动端），鼠标的光标位置（PC端）
MAP_ZOOM_TYPE.CENTER	根据地图中心点缩放（移动端和PC端）

TMap.constants.LAYER_LEVEL 常量说明

---

    图层渲染层级常量。

常量	说明	包含的图层类型
LAYER_LEVEL.UNDERGROUND	地下层，底图下方，默认无图层在此层级	无
LAYER_LEVEL.BASE	基础底图层，底图平面元素所在层级	矢量底图（卫星图、路况图）
LAYER_LEVEL.GROUND	贴地层，用户创建的平面图层所在层级	ImageTileLayer，ImageGroundLayer、CanvasGroundLayer
LAYER_LEVEL.BUILDING	建筑层	矢量底图2D、3D建筑，个性化图层
LAYER_LEVEL.OVERLAY_AA	需抗锯齿的覆盖物层	包括矢量图形中的线、面、体、模型以及通过可视化API创建图层
LAYER_LEVEL.TEXT	文字层	矢量底图（POI文字、道路文字）
LAYER_LEVEL.OVERLAY_NAA	不需抗锯齿的覆盖物层	MultiMarker、MultiLabel

TMap.constants.IMAGE_DISPLAY 常量说明

---

常量	说明
IMAGE_DISPLAY.ORIGIN	保持图片原状态，不改变图片大小
IMAGE_DISPLAY.SCALE	拉伸图片以适应显示区域
IMAGE_DISPLAY.REPEAT	重复图片以铺满显示区域