百度API开发指南.docx

1、XXAPI开发指南XXAPI开发指南目录隐藏 1简介o 1.1什么是XX地图API？o 1.2面向的读者o 1.3获取APIo 1.4开发移动平台上的地图应用o 1.5异步加载o 1.6兼容性o 1.7版本说明o 1.8问题解答 2基础知识o 2.1XX地图的“Hello, World” 2.1.1准备页面 2.1.2引用XX地图API文件 2.1.3创建地图容器元素 2.1.4命名空间 2.1.5创建地图实例 2.1.6创建点坐标 2.1.7地图初始化o 2.2地图配置与操作 3控件o 3.1地图控件概述o 3.2向地图添加控件o 3.3控制控件位置 3.3.1控件停靠位置 3.3.2控件位

2、置偏移o 3.4修改控件配置o 3.5自定义控件 3.5.1定义构造函数并继承Control 3.5.2初始化自定义控件 3.5.3添加自定义控件 4覆盖物o 4.1地图覆盖物概述o 4.2标注 4.2.1定义标注图标 4.2.2监听标注事件 4.2.3可托拽的标注 4.2.4内存释放o 4.3信息窗口o 4.4折线 4.4.1添加折线o 4.5自定义覆盖物 4.5.1定义构造函数并继承Overlay 4.5.2初始化自定义覆盖物 4.5.3绘制覆盖物 4.5.4移除覆盖物 4.5.5自定义其他方法 4.5.6添加覆盖物 5事件o 5.1地图事件概述o 5.2事件监听o 5.3事件参数和thi

3、so 5.4移除监听事件 6地图图层o 6.1地图图层概念o 6.2添加和移除图层o 6.3自定义图层 6.3.1地图坐标系 6.3.2定义取图规则 6.3.3添加和移除自定义图层 7工具o 7.1地图工具概述o 7.2向地图添加工具o 7.3通过按钮控制工具的开启和关闭o 7.4拉框放大工具 8服务o 8.1地图服务概述o 8.2本地搜索 8.2.1配置搜索 8.2.2结果面板 8.2.3数据接口 8.2.4周边搜索 8.2.5范围搜索o 8.3公交导航 8.3.1结果面板 8.3.2数据接口o 8.4驾车导航 8.4.1结果面板 8.4.2数据接口o 8.5地理编码 8.5.1根据地址描述

4、获得坐标 8.5.2反向地理编码简介什么是XX地图API？XX地图API是一套由JavaScript语言编写的应用程序接口，它能够帮助您在网站中构建功能丰富、交互性强的地图应用。XX地图API包含了构建地图基本功能的各种接口，提供了诸如本地搜索、路线规划等数据服务。面向的读者API是提供给那些具有一定JavaScript编程经验和了解面向对象概念的读者使用。此外，读者还应该对地图产品有一定的了解。您在使用中遇到任何问题，都可以通过API贴吧或交流群反馈给我们。获取API地图API是由JavaScript语言编写的，您在使用之前需要通过标签将API引用到页面中：1. 其中参数v为API当前的版本

5、号，目前最新版本为1.2。在1.2版本之前您还可以设置services参数，以告知API是否加载服务部分，true表示加载，false表示不加载，默认为true。开发移动平台上的地图应用API自1.1版本起开始支持iPhone、Android这样的移动平台。用户通过手机浏览器就可以访问由地图API创建出来的应用。移动平台的屏幕尺寸通常比PC或笔记本要小，操作方式也有所不同。为了更好的在手机浏览器上展示地图，我们有如下建议： 将地图容器高设置为100%，使其充满整个屏幕，或者您也可以计算浏览器窗口的大小并进行设置。 添加下面的meta标签： 这样做是为了让页面以正常比例进行显示并且禁止用户缩放页

6、面的操作。您可以参考Apples Developer documentation和Android documentation获得更多信息。异步加载API 1.1和1.2版本支持异步加载，您可以在引用脚本的时候添加callback参数，当脚本加载完成后callback函数会被立刻调用。请参考下面的使用示例：1. 2. 3. 4. 5. 异步加载6. 7. function initialize() 8. var mp = new BMap.Map(map);9. mp.centerAndZoom(new BMap.Point(121.491, 31.233), 11);10. 11. 12. f

7、unction loadScript() 13. var script = document.createElement(script);14. script.src = 15. document.body.appendChild(script);16. 17. 18. window.onload = loadScript;19. 20. 21. 22. 23. 24. 兼容性浏览器：IE 6.0+、Firefox 3.6+、Opera 9.0+、Safari 3.0+、Chrome操作系统：Windows、Mac、Linux移动平台：iPhone、Android版本说明地址中的参数v表示您加

8、载API的版本，例如当前API的最新版本为1.2，则您可在地址中添加 v=1.2。当API升级后，如果已有接口在使用、命名等方面发生了变化，我们会为其增加一个新的版本号，这不会对您现有的应用造成任何影响。如果升级只是修复一些bug或者在不影响现有功能的前提下增加接口、改善性能，则版本号不会发生变化。您可以在更新日志页面查看版本的变化。问题解答如果您在使用XX地图API中遇到问题，请尝试通过以下途径解决： 确认您使用了正确的地图API地址。 访问XX地图API吧，查找相关问题的帖子，或者将您的问题发布到贴吧中。基础知识XX地图的“Hello, World”开始学习XX地图API最简单的方式是看一

9、个简单的示例。以下代码创建了一个地图并以天安门作为地图的中心：1. 2. 3. 4. 5. 6. Hello, World7. 8. htmlheight:100%9. bodyheight:100%;margin:0px;padding:0px10. #containerheight:100%11. 12. script type=text/javascript src=13. 14. 15. 16. 17. 18. var map = new BMap.Map(container); / 创建地图实例19. var point = new BMap.Point(116.404, 39.91

10、5); / 创建点坐标20. map.centerAndZoom(point, 15); / 初始化地图，设置中心点坐标和地图级别21. 22. 23. 下面我们分步向您介绍：准备页面根据HTML标准，每一份HTML文档都应该声明正确的文档类型，我们建议您使用最新的符合HTML5规范的文档声明： 您也可以根据需要选择其他类型的文档声明，这样浏览器会以标准的方式对页面进行渲染，保证页面最大的兼容性。我们不建议您使用quirks模式进行开发。下面我们添加一个meta标签，以便使您的页面更好的在移动平台上展示。1. 接着我们设置样式，使地图充满整个浏览器窗口：1. 2. htmlheight:100

11、% 3. bodyheight:100%;margin:0px;padding:0px 4. #containerheight:100% 5. 引用XX地图API文件1. script type=text/javascript src=创建地图容器元素地图需要一个HTML元素作为容器，这样才能展现到页面上。这里我们创建了一个div元素。命名空间API使用BMap作为命名空间，所有类均在该命名空间之下，比如：BMap.Map、BMap.Control、BMap.Overlay。创建地图实例1. var map = new BMap.Map(container);位于BMap命名空间下的Map类表

12、示地图，通过new操作符可以创建一个地图实例。其参数可以是元素id也可以是元素对象。注意在调用此构造函数时应确保容器元素已经添加到地图上。创建点坐标1. var point = new BMap.Point(116.404, 39.915);这里我们使用BMap命名空间下的Point类来创建一个坐标点。Point类描述了一个地理坐标点，其中116.404表示经度，39.915表示纬度。地图初始化map.centerAndZoom(point, 15); 在创建地图实例后，我们需要对其进行初始化，BMap.Map.centerAndZoom()方法要求设置中心点坐标和地图级别。 地图必须经过初始

13、化才可以执行其他操作。地图配置与操作地图被实例化并完成初始化以后，就可以与其进行交互了。API中的地图对象的外观与行为与XX地图网站上交互的地图非常相似。它支持鼠标拖拽、滚轮缩放、双击放大等交互功能。您也可以修改配置来改变这些功能。 比如，默认情况下地图不支持鼠标滚轮缩放操作，因为这样可能会影响整个页面的用户体验，但是如果您希望在地图中使用鼠标滚轮控制缩放，则可以调用map.enableScrollWheelZoom方法来开启。配置选项可以在Map类参考的配置方法一节中找到。此外，您还可以通过编程的方式与地图交互。Map类提供了若干修改地图状态的方法。例如：setCenter()、panTo(

14、)、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() 5. map.panTo(new BMap.Point(116.409, 39.918); 6. , 2000);

15、控件地图控件概述XX地图上负责与地图交互的UI元素称为控件。XX地图API中提供了丰富的控件，您还可以通过Control类来实现自定义控件。地图API中提供的控件有：Control：控件的抽象基类，所有控件均继承此类的方法、属性。通过此类您可实现自定义控件。NavigationControl：地图平移缩放控件，默认位于地图左上方，它包含控制地图的平移和缩放的功能。OverviewMapControl：缩略地图控件，默认位于地图右下方，是一个可折叠的缩略地图。ScaleControl：比例尺控件，默认位于地图左下方，显示地图的比例关系。MapTypeControl：地图类型控件，默认位于地图右上

16、方。CopyrightControl：版权控件，默认位于地图左下方。向地图添加控件可以使用Map.addControl()方法向地图添加控件。在此之前地图需要进行初始化。例如，要将标准地图控件添加到地图中，可在代码中添加如下内容：var map = new BMap.Map(container); map.centerAndZoom(new BMap.Point(116.404, 39.915), 11); map.addControl(new BMap.NavigationControl(); 可以向地图添加多个控件。在本例中我们向地图添加一个平移缩放控件、一个比例尺控件和一个缩略图控件。在

17、地图中添加控件后，它们即刻生效。map.addControl(new BMap.NavigationControl(); map.addControl(new BMap.ScaleControl(); map.addControl(new BMap.OverviewMapControl(); map.addControl(new BMap.MapTypeControl(); map.setCurrentCity(北京); / 仅当设置城市信息时，MapTypeControl的切换功能才能可用 控制控件位置初始化控件时，可提供一个可选参数，其中的anchor和offset属性共同控制控件在地图上

18、的位置。控件停靠位置anchor表示控件的停靠位置，即控件停靠在地图的哪个角。当地图尺寸发生变化时，控件会根据停靠位置的不同来调整自己的位置。anchor允许的值为：BMAP_ANCHOR_TOP_LEFT 表示控件定位于地图的左上角。BMAP_ANCHOR_TOP_RIGHT 表示控件定位于地图的右上角。BMAP_ANCHOR_BOTTOM_LEFT 表示控件定位于地图的左下角。BMAP_ANCHOR_BOTTOM_RIGHT 表示控件定位于地图的右下角。控件位置偏移除了指定停靠位置外，还可以通过偏移量来指示控件距离地图边界有多少像素。如果两个控件的停靠位置相同，那么控件可能会重叠在一起，这

19、时就可以通过偏移值使二者分开显示。本示例将比例尺放置在地图的左下角，由于API默认会有版权信息，因此需要添加一些偏移值以防止控件重叠。var opts = offset: new BMap.Size(150, 5) map.addControl(new BMap.ScaleControl(opts); 修改控件配置地图API的控件提供了丰富的配置参数，您可参考API文档来修改它们以便得到符合要求的控件外观。例如，NavigationControl控件就提供了如下类型：BMAP_NAVIGATION_CONTROL_LARGE 表示显示完整的平移缩放控件。BMAP_NAVIGATION_CONT

20、ROL_SMALL 表示显示小型的平移缩放控件。BMAP_NAVIGATION_CONTROL_PAN 表示只显示控件的平移部分功能。BMAP_NAVIGATION_CONTROL_ZOOM 表示只显示控件的缩放部分功能。下图从左向右依次展示了上述不同类型的控件外观：下面的示例将调整平移缩放地图控件的外观。var opts = type: BMAP_NAVIGATION_CONTROL_SMALL map.addControl(new BMap.NavigationControl(opts); 自定义控件XX地图API允许您通过继承Control来创建自定义地图控件。要创建可用的自定义控件，您

21、需要做以下工作：定义一个自定义控件的构造函数。设置自定义控件构造函数的prototype属性为Control的实例，以便继承控件基类。实现initialize()方法并提供defaultAnchor和defaultOffset属性。定义构造函数并继承Control首先您需要定义自定义控件的构造函数，并在构造函数中提供defaultAnchor和defaultOffset两个属性，以便API正确定位控件位置，接着让其继承于Control。在下面的示例中我们定义一个名为ZoomControl的控件，每一次点击将地图放大两个级别。它具有文本标识，而不是平移缩放控件中使用的图形图标。/ 定义一个控件类

22、，即function function ZoomControl() / 设置默认停靠位置和偏移量 this.defaultAnchor = BMAP_ANCHOR_TOP_LEFT; this.defaultOffset = new BMap.Size(10, 10); / 通过JavaScript的prototype属性继承于BMap.Control ZoomControl.prototype = new BMap.Control(); 初始化自定义控件当调用map.addControl()方法添加自定义控件时，API会调用该对象的initialize()方法用来初始化控件，您需要实现此方法

23、并在其中创建控件所需的DOM元素，并添加DOM事件。所有自定义控件中的DOM元素最终都应该添加到地图容器（即地图所在的DOM元素）中去，地图容器可以通过map.getContainer()方法获得。最后initialize()方法需要返回控件容器的DOM元素。/ 自定义控件必须实现initialize方法，并且将控件的DOM元素返回 / 在本方法中创建个div元素作为控件的容器，并将其添加到地图容器中 ZoomControl.prototype.initialize = function(map) / 创建一个DOM元素 var div = document.createElement(div

24、); / 添加文字说明 div.appendChild(document.createTextNode(放大2级); / 设置样式 div.style.cursor = pointer; div.style.border = 1px solid gray; div.style.backgroundColor = white; / 绑定事件，点击一次放大两级 div.onclick = function(e) map.zoomTo(map.getZoom() + 2); / 添加DOM元素到地图中 map.getContainer().appendChild(div); / 将DOM元素返回 r

25、eturn div; 添加自定义控件添加自定义控件与添加其他控件方法一致，调用map.addControl()方法即可。/ 创建控件实例 var myZoomCtrl = new ZoomControl(); / 添加到地图当中 map.addControl(myZoomCtrl);覆盖物地图覆盖物概述所有叠加或覆盖到地图的内容，我们统称为地图覆盖物。如标注、矢量图形元素(包括：折线和多边形和圆)、信息窗口等。覆盖物拥有自己的地理坐标，当您拖动或缩放地图时，它们会相应的移动。地图API提供了如下几种覆盖物：Overlay：覆盖物的抽象基类，所有的覆盖物均继承此类的方法。Marker：标注表示地

26、图上的点，可自定义标注的图标。Label：表示地图上的文本标注，您可以自定义标注的文本内容。Polyline：表示地图上的折线。Polygon：表示地图上的多边形。多边形类似于闭合的折线，另外您也可以为其添加填充颜色。Circle: 表示地图上的圆。InfoWindow：信息窗口也是一种特殊的覆盖物，它可以展示更为丰富的文字和多媒体信息。注意：同一时刻只能有一个信息窗口在地图上打开。可以使用map.addOverlay方法向地图添加覆盖物，使用map.removeOverlay方法移除覆盖物，注意此方法不适用于InfoWindow。标注标注表示地图上的点。API提供了默认图标样式，您也可以通过

27、Icon类来指定自定义图标。Marker的构造函数的参数为Point和MarkerOptions（可选）。注意：当您使用自定义图标时，标注的地理坐标点将位于标注所用图标的中心位置，您可通过Icon的offset属性修改标定位置。下面的示例向地图中心点添加了一个标注，并使用默认的标注样式。var map = new BMap.Map(container); var point = new BMap.Point(116.404, 39.915); map.centerAndZoom(point, 15); var marker = new BMap.Marker(point); / 创建标注 map.addOverlay(marker); / 将标注添加到地图中 定义标注图标通过Icon类可实