JavaScript API极速版

地图覆盖物概述

所有叠加或覆盖到地图的内容，我们统称为地图覆盖物。如标注、折线、信息窗口等。覆盖物拥有自己的地理坐标，当您拖动或缩放地图时，它们会相应的移动。地图API提供了如下几种覆盖物：

Overlay：覆盖物的抽象基类，所有的覆盖物均继承此类的方法。

Marker：标注表示地图上的点，可自定义标注的图标。

Polyline：表示地图上的折线。

InfoWindow：信息窗口也是一种特殊的覆盖物，它可以展示更为丰富的文字和多媒体信息。注意：同一时刻只能有一个信息窗口在地图上打开。

可以使用map.addOverlay方法向地图添加覆盖物，使用map.removeOverlay 方法移除覆盖物，注意此方法不适用于InfoWindow。

标注

标注表示地图上的点。API提供了默认图标样式，您也可以通过Icon类来指定自定义图标。Marker的构造函数的参数为Point和MarkerOptions（可选）。注意：当您使用自定义图标时，标注的地理坐标点将位于标注所用图标的中心位置，您可通过Icon的offset属性修改标定位置。

下面的示例向地图中心点添加了一个标注，并使用默认的标注样式。

var map = new BMap.Map("l-map");  
map.centerAndZoom(new BMap.Point(116.404, 39.915), 14);  
var marker = new BMap.Marker(new BMap.Point(116.404, 39.915));        // 创建标注      
map.addOverlay(marker);

定义标注图标

通过Icon类可实现自定义标注的图标，下面示例通过参数MarkerOptions的icon属性进行设置，您也可以使用marker.setIcon()方法。

var map = new BMap.Map("container");      
var point = new BMap.Point(116.404, 39.915);      
map.centerAndZoom(point, 15);  // 编写自定义函数，创建标注     
function addMarker(point, index){  // 创建图标对象     
  var myIcon = new BMap.Icon("http://api.map.baidu.com/mapCard/img/location.gif",   
      new BMap.Size(14, 23), {      
       // 指定定位位置。     
       // 当标注显示在地图上时，其所指向的地理位置距离图标左上      
       // 角各偏移7像素和25像素。您可以看到在本例中该位置即是     
       // 图标中央下端的尖角位置。      
       anchor: new BMap.Size(7, 25),        
      });        
 // 创建标注对象并添加到地图     
  var marker = new BMap.Marker(point, {icon: myIcon});      
  map.addOverlay(marker);      
 }      
 // 随机向地图添加10个标注      
 var bounds = map.getBounds();      
 var lngSpan = bounds.getNorthEast().lng - bounds.getSouthWest().lng;      
 var latSpan = bounds.getNorthEast().lat- bounds.getSouthWest().lat;      
 for (var i = 0; i < 10; i++) {  
     var point = new BMap.Point(bounds.getSouthWest().lng + lngSpan * (Math.random() * 0.7 + 0.15), bounds.getSouthWest().lat + latSpan * (Math.random() * 0.7 + 0.15));  
     addMarker(point, i);  
}

监听标注事件 事件方法与Map事件机制相同。可参考事件部分。

marker.addEventListener("click", function(){      
  alert("您点击了标注");      
});

信息窗口

信息窗口在地图上方的浮动显示HTML内容。信息窗口可直接在地图上的任意位置打开，也可以在标注对象上打开（此时信息窗口的坐标与标注的坐标一致）。您可以使用InfoWindow来创建一个信息窗实例，注意同一时刻地图上只能有一个信息窗口处于打开状态。

var opts = {      
    width : 100,     // 信息窗口宽度      
    height: 50,     // 信息窗口高度      
    title : "Hello"  // 信息窗口标题     
}      
var infoWindow = new BMap.InfoWindow("World", opts);  // 创建信息窗口对象      
map.openInfoWindow(infoWindow, marker.getPosition());      // 打开信息窗口

折线

Polyline表示地图上的折线覆盖物。它包含一组点，并将这些点连接起来形成折线。

添加折线 折线在地图上绘制为一系列直线段。可以自定义这些线段的颜色、粗细和透明度。颜色可以是十六进制数字形式（比如：#ff0000）或者是颜色关键字（比如：red）。以下代码段会在两点之间创建6像素宽的蓝色折线：

var polyline = new BMap.Polyline([new BMap.Point(116.399, 39.910),      
                                  new BMap.Point(116.405, 39.920)],      
                                {strokeColor:"blue", strokeWeight:6, strokeOpacity:0.5});      
map.addOverlay(polyline);

自定义覆盖物

要创建自定义覆盖物，您需要做以下工作：

定义一个自定义覆盖物的构造函数，通过构造函数参数可以传递一些自由的变量。

设置自定义覆盖物对象的prototype属性为Overlay的实例，以便继承覆盖物基类。

实现initialize方法，当调用map.addOverlay方法时，API会调用此方法。

实现draw方法。

定义构造函数并继承Overlay

首先您需要定义自定义覆盖物的构造函数，在下面的示例中我们定义一个名为SquareOverlay的构造函数，它包含中心点和边长两个参数，用来在地图上创建一个方形覆盖物。

// 定义自定义覆盖物的构造函数    
  function SquareOverlay(center, length, color){      
    this._center = center;      
    this._length = length;      
    this._color = color;      
  }      
// 继承API的BMap.Overlay      
  SquareOverlay.prototype = new BMap.Overlay();

初始化自定义覆盖物

当调用map.addOverlay方法添加自定义覆盖物时，API会调用该对象的initialize方法用来初始化覆盖物，在初始化过程中需要创建覆盖物所需要的DOM元素，并添加到地图相应的容器中。地图提供了若干容器供覆盖物展示，通过map.getPanes方法可以得到这些容器元素，它们包括：

floatPane。

markerMouseTarget

floatShadow

markerPane

mapPane

这些对象代表了不同的覆盖物容器元素，它们之间存在着覆盖关系，最上一层为floatPane，用于显示信息窗口内容，下面依次为标注点击区域层、信息窗口阴影层、文本标注层、标注层和矢量图形层。我们自定义的方形覆盖物可以添加到任意图层上，这里我们选择添加到markerPane上，作为其一个子结点。

// 实现初始化方法    
SquareOverlay.prototype.initialize = function(map){      
// 保存map对象实例     
    this._map = map;          
// 创建div元素，作为自定义覆盖物的容器     
    var div = document.createElement("div");      
    div.style.position = "absolute";          
// 可以根据参数设置元素外观     
    div.style.width = this._length + "px";      
    div.style.height = this._length + "px";      
    div.style.background = this._color;        
// 将div添加到覆盖物容器中     
    map.getPanes().markerPane.appendChild(div);        
// 保存div实例     
    this._div = div;        
// 需要将div元素作为方法的返回值，当调用该覆盖物的show、     
// hide方法，或者对覆盖物进行移除时，API都将操作此元素。     
    return div;      
}

绘制覆盖物

到目前为止，我们仅仅把覆盖物添加到了地图上，但是并没有将它放置在正确的位置上。您需要在draw方法中设置覆盖物的位置，每当地图状态发生变化（比如：位置移动、级别变化）时，API都会调用覆盖物的draw方法，用于重新计算覆盖物的位置。通过map.pointToOverlayPixel方法可以将地理坐标转换到覆盖物的所需要的像素坐标。

// 实现绘制方法     
SquareOverlay.prototype.draw = function(){      
// 根据地理坐标转换为像素坐标，并设置给容器      
   var position = this._map.pointToOverlayPixel(this._center);      
   this._div.style.left = position.x - this._length / 2 + "px";      
   this._div.style.top = position.y - this._length / 2 + "px";      
}

移除覆盖物

当调用map.removeOverlay或者map.clearOverlays方法时，API会自动将initialize方法返回的DOM元素进行移除。

显示和隐藏覆盖物

自定义覆盖物会自动继承Overlay的show和hide方法，方法会修改由initialize方法返回的DOM元素的style.display属性。如果自定义覆盖物元素较为复杂，您也可以自己实现show和hide方法。

// 实现显示方法      
SquareOverlay.prototype.show = function(){      
    if (this._div){      
        this._div.style.display = "";      
    }      
}        
// 实现隐藏方法    
SquareOverlay.prototype.hide = function(){      
    if (this._div){      
        this._div.style.display = "none";      
    }      
}

自定义其他方法

通过构造函数的prototype属性，您可以添加任何自定义的方法，比如下面这个方法每调用一次就能改变覆盖物的显示状态：

// 添加自定义方法     
SquareOverlay.prototype.toggle = function(){      
    if (this._div){      
       if (this._div.style.display == ""){      
           this.hide();      
        }      
       else {      
           this.show();      
        }      
    }      
}

添加覆盖物

您现在已经完成了一个完整的自定义覆盖物的编写，可以添加到地图上了。

// 添加自定义覆盖物     
 var mySquare = new SquareOverlay(map.getCenter(), 100, "red");      
 map.addOverlay(mySquare);

文档全面上新

目录

地图覆盖物概述

标注

信息窗口

折线

自定义覆盖物