百度地图 API 开发指南

百度地图 API开发指南 1 / 26 百度地图 API开发指南 目录 简介 ...................................................................................................................... 3 什么使百度地图 API .................................................................................................... 3 面向的读者 .................................................................................................................. 3 获取 API ....................................................................................................................... 3 开发移动平台上的地图应用 ........................................................................................ 3 兼容性 ......................................................................................................................... 4 版本说明 ..................................................................................................................... 4 问题解答 ..................................................................................................................... 4 基础知识 ............................................................................................................... 4 百度地图的“Hello, World” ....................................................................................... 4 准备页面 .......................................................................................................................................... 5 引用百度地图 API文件 .................................................................................................................. 5 创建地图容器元素 .......................................................................................................................... 5 命名空间 .......................................................................................................................................... 6 创建地图实例 .................................................................................................................................. 6 创建点坐标 ...................................................................................................................................... 6 地图初始化 ...................................................................................................................................... 6 地图操作 ..................................................................................................................... 6 控件 ...................................................................................................................... 7 地图控件概述 .............................................................................................................. 7 向地图添加控件 .......................................................................................................... 7 控制控件位置 .............................................................................................................. 7 修改控件配置 .............................................................................................................. 8 自定义控件 .................................................................................................................. 8 覆盖物 ................................................................................................................... 9 地图覆盖物概述 .......................................................................................................... 9 标注 ........................................................................................................................... 10 定义标注图标 ................................................................................................................................ 10 监听标注事件 ................................................................................................................................ 11 可托拽的标注 ................................................................................................................................ 11 内存释放 ........................................................................................................................................ 11 信息窗口 ................................................................................................................... 11 百度地图 API开发指南 2 / 26 折线 ........................................................................................................................... 12 自定义覆盖物 ............................................................................................................ 12 定义构造函数并继承 Overlay ....................................................................................................... 12 初始化自定义覆盖物 .................................................................................................................... 13 绘制覆盖物 .................................................................................................................................... 14 移除覆盖物 .................................................................................................................................... 14 显示和隐藏覆盖物 ........................................................................................................................ 14 自定义其他方法 ............................................................................................................................ 15 添加覆盖物 .................................................................................................................................... 15 事件 .................................................................................................................... 15 地图事件概述 ............................................................................................................ 15 事件监听 ................................................................................................................... 16 事件参数和 this ......................................................................................................... 16 移除事件监听 ............................................................................................................ 17 地图图层 ............................................................................................................. 17 地图图层概念 ............................................................................................................ 17 自定义图层 ................................................................................................................ 17 工具 .................................................................................................................... 18 地图工具概述 ............................................................................................................ 18 向地图添加工具 ........................................................................................................ 18 通过按钮控制工具的开启和关闭 .............................................................................. 18 拉框放大工具 ............................................................................................................ 19 服务 .................................................................................................................... 19 地图服务概述 ............................................................................................................ 19 本地搜索 ................................................................................................................... 19 配置搜索 ........................................................................................................................................ 20 结果面板 ........................................................................................................................................ 20 数据接口 ........................................................................................................................................ 20 周边搜索 ........................................................................................................................................ 21 范围搜索 ........................................................................................................................................ 21 公交导航 ................................................................................................................... 22 结果面板 ........................................................................................................................................ 22 数据接口 ........................................................................................................................................ 22 驾车导航 ................................................................................................................... 23 结果面板 ........................................................................................................................................ 24 数据接口 ........................................................................................................................................ 24 百度地图 API开发指南 3 / 26 地址解析 ................................................................................................................... 25 根据地址描述获得坐标 ................................................................................................................ 25 反向地址解析 ................................................................................................................................ 25 简介 什么使百度地图 API 百度地图 API是一套由 JavaScript语言编写的应用程序接口，它能够帮助您在网站中构 建功能丰富、交互性强的地图应用。百度地图 API包含了构建地图基本功能的各种接口，提 供了诸如本地搜索、路线规划等数据服务。 面向的读者 API是提供给那些具有一定 JavaScript编程经验和了解面向对象概念的读者使用。此外， 读者还应该对地图产品有一定的了解。 您在使用中遇到任何问题，都可以通过 API贴吧或交流群反馈给我们。 获取 API 地图 API是由 JavaScript语言编写的，您在使用之前需要通过 其中参数 v为 API当前的版本号，目前最新版本为 1.2。在 1.2版本之前您还可以设置 services参数，以告知 API是否加载服务部分，true表示加载，false表示不加载，默认为 true。 开发移动平台上的地图应用 API自 1.1版本起开始支持 iPhone、Android这样的移动平台。用户通过手机浏览器就可 以访问由地图 API创建出来的应用。移动平台的屏幕尺寸通常比 PC或笔记本要小，操作方 式也有所不同。为了更好的在手机浏览器上展示地图，我们有如下建议： 将地图容器高设置为 100%，使其充满整个屏幕，或者您也可以计算浏览器窗口的大小 并进行设置。 添加下面的 meta标签： 这样做是为了让页面以正常比例进行显示并且禁止用户缩放页面的操作。 百度地图 API开发指南 4 / 26 您可以参考 Apple's Developer documentation 和 Android documentation 获得更多信 息。 兼容性 浏览器：IE 6.0+、Firefox 3.0+、Opera 9.0+、Safari 3.0+、Chrome 操作系统：Windows、Mac、Linux 移动平台: iPhone、Android 操作系统：Windows、Mac、Linux 版本说明 地址 http://api.map.baidu.com/api?v=1.2 中的参数 v表示您加载 API的版本，例如 当前 API的最新版本为 1.2，则您可在地址中添加 v=1.2。当 API升级后，如果已有接口 在使用、命名等方面发生了变化，我们会为其增加一个新的版本号，这不会对您现有的 应用造成任何影响。如果升级只是修复一些 bug或者在不影响现有功能的前提下增加接 口、改善性能，则版本号不会发生变化。您可以在更新日志页面查看版本的变化。 问题解答 如果您在使用百度地图 API中遇到问题，请尝试通过以下途径解决： 确认您使用了正确的地图 API地址。 访问百度地图 API吧，查找相关问题的帖子，或者将您的问题发布到贴吧中。 基础知识 百度地图的“Hello, World” 开始学习百度地图 API 最简单的方式是看一个简单的示例。以下代码创建了一个地图 并以天安门作为地图的中心： 1. 2. 3. 4. 5. 6. 7. 12. 13. 14. 15. 16. 17. 22. 23. 下面我们分步向您介绍： 准备页面 根据 HTML标准，每一份 HTML文档都应该声明正确的文档类型，我们建议您使用 最新的符合 HTML5规范的文档声明： 1. 您也可以根据需要选择其他类型的文档声明，这样浏览器会以标准的方式对页面进行渲 染，保证页面最大的兼容性。我们不建议您使用 quirks 模式进行开发。下面我们添加一个 meta标签，以便使您的页面更好的在移动平台上展示。 1. 接着我们设置样式，使地图充满整个浏览器窗口： 1. 引用百度地图 API文件 当您引用地图 API文件时，需要使用自己申请的 API密钥。 1. 创建地图容器元素 地图需要一个 HTML 元素作为容器，这样才能展现到页面上。这里我们创建了一个 div 百度地图 API开发指南 6 / 26 元素。 1. 命名空间 API 使用 BMap 作为命名空间，所有类均在该命名空间之下，比如：BMap.Map、 BMap.Control、BMap.Overlay 创建地图实例 位于 BMap命名空间下的Map类表示地图，通过 new操作符可以创建一个地图实例。 其参数可以是元素 id也可以是元素对象。 注意在调用此构造函数时应确保容器元素已经添加到地图上。 1. var map = new BMap.Map("container"); 创建点坐标 这里我们使用 BMap命名空间下的 Point类来创建一个坐标点。Point类描述了一个地理 坐标点，其中 116.404表示经度，39.915表示纬度。 1. var point = new BMap.Point(116.404, 39.915); 地图初始化 在创建地图实例后，我们需要对其进行初始化，BMap.Map.centerAndZoom()方法要求设 置中心点坐标和地图级别。 地图必须经过初始化才可以执行其他操作。 1. map.centerAndZoom(point,15); 地图操作 地图被实例化并完成初始化以后，就可以与其进行交互了。API中的地图对象的外观与 行为与百度地图网站上交互的地图非常相似。它支持鼠标拖拽、滚轮缩放、双击放大等交互 功能。您也可以修改配置来改变这些功能。 您还可以通过编程的方式与地图交互。Map类提供了若干修改地图状态的方法。例如： setCenter()、panTo()、zoomTo()等等。 下面示例显示一个地图，等待两秒钟后，它会移动到新中心点。panTo()方法将让地图平 滑移动至新中心点，如果移动距离超过了当前地图区域大小，则地图会直跳到该点。 1. var map = new BMap.Map("container"); 2. var point = new BMap.Point(116.404, 39.915); 3. map.centerAndZoom(point, 15); 4. window.setTimeout(function(){ 百度地图 API开发指南 7 / 26 5. map.panTo(new BMap.Point(116.409, 39.918)); 6. }, 2000); 控件 地图控件概述 百度地图上负责与地图交互的 UI 元素称为控件。百度地图 API 中提供了丰富的控件， 您还可以通过 BMap.Control来实现自定义控件。 地图 API中提供的控件有： Control：控件的抽象基类，所有控件均继承此类的方法、属性。通过此类您可实现 自定义控件。 NavigationControl：地图平移缩放控件，默认位于地图左上方，它包含控制地图的 平移和缩放的功能。 OverviewMapControl：缩略地图控件，默认位于地图右下方，是一个可折叠的缩略 地图。 ScaleControl：比例尺控件，默认位于地图左下方，显示地图的比例关系。 CopyrightControl：版权控件，默认位于地图左下方。 所有这些控件都基于 BMap.Control类。 向地图添加控件 可以使用 BMap.Map.addControl()方法向地图添加控件。在此之前地图需要进行初始化。 例如，要将标准地图控件添加到地图中，可在代码中添加如下内容： 1. var map = new BMap.Map("container"); 2. map.centerAndZoom(new BMap.Point(116.404, 39.915), 11); 3. map.addControl(new BMap.NavigationControl()); 4. 可以向地图添加多个控件。在本例中我们向地图添加一个平移缩放控件、一个比例尺控 件和一个缩略图控件。在地图中添加控件后，它们即刻生效。 1. map.addControl(new BMap.NavigationControl()); 2. map.addControl(new BMap.ScaleControl()); 3. map.addControl(new BMap.OverviewMapControl()); 控制控件位置 初始化控件时，可提供一个可选参数，参数类型为一个 JavaScript对象。其中 anchor和 offsetX、offsetY共同控制控件在地图上的位置。anchor表示控件停靠在地图的哪个角，允许 的值为： BMAP_ANCHOR_TOP_LEFT 百度地图 API开发指南 8 / 26 BMAP_ANCHOR_TOP_RIGHT BMAP_ANCHOR_BOTTOM_LEFT BMAP_ANCHOR_BOTTOM_RIGHT 除了指定停靠位置外，还可以提供偏移量，用来指示控件距离地图边界相隔多少像素。 本示例将标准地图控件放置在地图的右上角，间隔 10个像素。 1. var opts = {anchor: BMAP_ANCHOR_TOP_RIGHT, offset: new BMap.Size(10, 10)} 2. map.addControl(new BMap.NavigationControl(opts)); 修改控件配置 地图 API的控件提供了丰富的配置参数，您可参考 API文档来修改它们以便得到符合要 求的控件外观。 本示例将调整平移缩放地图控件的外观。 1. var opts = {type: BMAP_NAVIGATION_CONTROL_SMALL} 2. map.addControl(new BMap.NavigationControl(opts)); 自定义控件 百度地图 API 允许您通过继承 BMap.Control 来创建自定义地图控件。（注意 JavaScript 是通过 prototype属性进行继承的） 要创建可用的自定义控件，您需要实现类定义中的一个抽象方法并给两个属性赋值，它 们是：initialize()和 defaultAnchor、defaultOffset。initialize()方法必须返回控件容器的 DOM元 素，defaultAnchor为控件默认的停靠位置，defaultOffset为控件默认的间隔距离。 所有自定义的地图控件中的 DOM元素最终都应该添加到地图容器（即地图所在的 DOM 元素）中去，这个地图容器可以通过 BMap.Map.getContainer()方法获得。 在此示例中，我们创建一个简单的放大控件，每一次点击将地图放大两个级别。它具有 文本标识，而不是平移缩放控件中使用的图形图标。 1. // 定义一个控件类，即 function 2. function ZoomControl(){ 3. // 设置默认停靠位置和偏移量 4. this.defaultAnchor = BMAP_ANCHOR_TOP_LEFT; 5. this.defaultOffset = new BMap.Size(10, 10); 6. } 7. 8. // 通过 JavaScript的 prototype属性继承于 BMap.Control 9. ZoomControl.prototype = new BMap.Control(); 10. 11. // 自定义控件必须实现自己的 initialize方法，并且将控件的 DOM元素返回 12. // 在本方法中创建个 div元素作为控件的容器，并将其添加到地图容器中 13. ZoomControl.prototype.initialize = function(map){ 14. // 创建一个 DOM元素 15. var div = document.createElement("div"); 16. // 添加文字说明 百度地图 API开发指南 9 / 26 17. div.appendChild(document.createTextNode("放大 2级")); 18. // 设置样式 19. div.style.cursor = "pointer"; 20. div.style.border = "1px solid gray"; 21. div.style.backgroundColor = "white"; 22. // 绑定事件，点击一次放大两级 23. div.onclick = function(e){ 24. map.zoomTo(map.getZoom() + 2); 25. } 26. // 添加 DOM元素到地图中 27. map.getContainer().appendChild(div); 28. // 将 DOM元素返回 29. return div; 30. } 31. 32. // 创建控件 33. var myZoomCtrl = new ZoomControl(); 34. // 添加到地图当中 35. map.addControl(myZoomCtrl); 覆盖物 地图覆盖物概述 所有叠加或覆盖到地图的内容，我们统称为地图覆盖物。如标注、矢量图形元素(包括： 折线和多边形和圆)、信息窗口等。覆盖物拥有自己的地理坐标，当您拖动或缩放地图时， 它们会相应的移动。 地图 API提供了如下几种覆盖物： Overlay：覆盖物的抽象基类，所有的覆盖物均继承此类的方法。 Marker：标注表示地图上的点，可自定义标注的图标。 Label：表示地图上的文本标注，您可以自定义标注的文本内容。 Polyline：表示地图上的折线。 Polygon：表示地图上的多边形。多边形类似于闭合的折线，另外您也可以为其添 加填充颜色。 Circle: 表示地图上的圆。 InfoWindow：信息窗口也是一种特殊的覆盖物，它可以展示更为丰富的文字和多媒 体信息。注意：同一时刻只能有一个信息窗口在地图上打开。 可以使用 map.addOverlay方法向地图添加覆盖物，使用 map.removeOverlay方法移除覆 盖物，注意此方法不适用于 InfoWindow。 百度地图 API开发指南 10 / 26 标注 标注表示地图上的点。API提供了默认图标样式，您也可以通过 Icon类来指定自定义图 标。Marker的构造函数的参数为 Point和MarkerOptions（可选）。注意：当您使用自定义图 标时，标注的地理坐标点将位于标注所用图标的中心位置，您可通过 Icon的 offset属性修改 标定位置。下面的示例向地图中心点添加了一个标注，并使用默认的标注样式。 1. var map = new BMap.Map("container"); 2. var point = new BMap.Point(116.404, 39.915); 3. map.centerAndZoom(point, 15); 4. var marker = new BMap.Marker(point); // 创建标注 5. map.addOverlay(marker); // 将标注添加到地图中 定义标注图标 通过 Icon类可实现自定义标注的图标，下面示例通过参数MarkerOptions的 icon属性进 行设置，您也可以使用 marker.setIcon()方法。 1. var map = new BMap.Map("container"); 2. var point = new BMap.Point(116.404, 39.915); 3. map.centerAndZoom(point, 15); 4. 5. // 编写自定义函数，创建标注 6. function addMarker(point, index){ 7. 8. // 创建图标对象 9. var myIcon = new BMap.Icon("http://api.map.baidu.com/img/markers.png", new BMap.Size(23, 25), { 10. // 指定定位位置。 11. // 当标注显示在地图上时，其所指向的地理位置距离图标左上 12. // 角各偏移 10像素和 25像素。您可以看到在本例中该位置即是 13. // 图标中央下端的尖角位置。 14. offset: new BMap.Size(10, 25), 15. // 设置图片偏移。 16. // 当您需要从一幅较大的图片中截取某部分作为标注图标时，您 17. // 需要指定大图的偏移位置，此做法与 css sprites技术类似。 18. imageOffset: new BMap.Size(0, 0 - index * 25) // 设置图片偏移 19. }); 20. 21. // 创建标注对象并添加到地图 22. var marker = new BMap.Marker(point, {icon: myIcon}); 23. map.addOverlay(marker); 24. } 25. 26. // 随机向地图添加 10个标注 百度地图 API开发指南 11 / 26 27. var bounds = map.getBounds(); 28. var lngSpan = bounds.maxX - bounds.minX; 29. var latSpan = bounds.maxY - bounds.minY; 30. for (var i = 0; i < 10; i ++) { 31. var point = new BMap.Point(bounds.minX + lngSpan * (Math.random() * 0.7 + 0.15), 32. bounds.minY + latSpan * (Math.random() * 0.7 + 0.15)); 33. addMarker(point, i); 34. } 监听标注事件 事件方法与Map事件机制相同。可参考事件部分。 1. marker.addEventListener("click", function(){ 2. alert("您点击了标注"); 3. }); 可托拽的标注 marker的 enableDragging和 disableDragging方法可用来开启和关闭标注的拖拽功能。默 认情况下标注不支持拖拽，您需要调用 marker.enableDragging()方法来开启拖拽功能。在标 注开启拖拽功能后，您可以监听标注的 dragend事件来捕获拖拽后标注的最新位置。 1. marker.enableDragging(); 2. marker.addEventListener("dragend", function(e){ 3. alert("当前位置：" + e.point.lng + ", " + e.point.lat); 4. }) 内存释放 如果您在地图中需要反复添加大量的标注，这可能会占用较多的内存资源。如果您的标 注在被移除后不再使用，可调用 Overlay.dispose()方法来释放内存。注意在 1.1版本之前调用 此方法后标注将不能再次添加到地图上。关于 Overlay.dispose()的详细信息可参考 API文档部 分内容。例如，您可以在标注被移除后调用此方法： 1. map.removeOverlay(marker); 2. marker.dispose(); 信息窗口 信息窗口在地图上方的浮动显示 HTML 内容。信息窗口可直接在地图上的任意位置打 开，也可以在标注对象上打开（此时信息窗口的坐标与标注的坐标一致）。 您可以使用 InfoWindow 来创建一个信息窗实例，注意同一时刻地图上只能有一个信息窗口处于打开状 百度地图 API开发指南 12 / 26 态。