阅读导引

阅读本文之前，您需要具备JavaScript编程知识及面向对象编程的概念。需要对腾讯地图产品有一定的了解。对于不同类型的开发者，以下是推荐重点阅读的内容：

所有开发者，都需要阅读Key鉴权部分；

地图开发初学者，本文将从地图基础知识、快速入门、事件、控件、覆盖物、服务、街景等方面帮助您迅速掌握地图基本开发知识，为进一步探索高级功能开发提供指引；

有地图开发经验者，建议直接查询参考手册获取信息；

其他地图API开发者，请阅读坐标转换、注意事项部分，会介绍一些API平台切换的常见问题；

移动应用、Wap应用开发者，请阅读兼容性、手机Web应用开发部分，将介绍对移动终端的兼容情况及开发注意事项。

Key鉴权

Key用途

Key用于识别开发者身份、验证权限，并在某些情况下方便联系到您。不使用Key会导致部分功能无法正常使用。

Key使用限制

目前Key申请完全免费，基础功能使用免费，且没有调用次数限制。

Key使用方法

在加载API服务时通过key参数传入您申请的Key。

Key如何申请

使用QQ账号登录，点击控制台—密钥管理—申请创建密钥，填写应用名及应用描述即可申请。一个账号最多可以申请5个Key

API服务加载

需要在页面的前端使用script标签加载API服务，格式如下：

其中，v参数是引用的版本号，目前腾讯地图提供两个版本，分别是v=1，v=2.exp，推荐使用2.exp，可以获得最新最快的支持。Key参数YOUR_KEY是Key鉴权中申请的key。

如果您要使用 https 服务，可以直接将协议替换成 https 即 url 为：https://map.qq.com/api/js?v=2.exp&key=YOUR_KEY

JavaScript API除了提供基本的功能库外，还提供了一些有用的附加库。加载方法是将script标签的src设置为：

其中libraries参数用来指明加载的附加库，可以指定多个附加库名称，名称之间用英文半角字符逗号","分隔。支持的附加库种类：

  • drawing 绘图工具库，用于在地图上方绘制折线、多边形、圆等几何图形；
  • geometry 几何运算库，用于计算地球表面的距离、面积等；
  • place 文本输入提示库，用于快速帮助用户完成检索关键词输入；
  • convertor 坐标转换库，将标准经纬度或其它地图API经纬度转换为腾讯经纬度坐标系；
  • visualization 可视化组件库，将位置数据转化为可视图像的工具，比如热力图、散点图等。

关于附加库的详细接口，请参见参考手册。

加载API之后，就可以在Web页面中引用相关的接口。另外，加载方式除以上介绍的，还支持异步加载，完整的示例请参考快速入门 。

坐标转换

如果原始数据是使用的标准经纬度，或者其它地图，比如Google、Baidu等地图坐标系，那在使用腾讯地图显示前，需要进行坐标转换，否则显示位置将会和实际位置有偏差。

目前支持转换的坐标类型有：

  1. GPS经纬度
  2. 搜狗经纬度
  3. 百度经纬度
  4. Mapbar经纬度
  5. Google经纬度
  6. 搜狗墨卡托

若使用转换接口，需加载附加库convertor，加载方法参考API服务加载。

兼容性

PC浏览器：Chrome、IE6+、Firefox、Opera、Safari

移动设备：iPhone、iPad、Android

手机Web应用开发

腾讯地图JavaScript API针对iOS、Android等手机设备进行了优化，能够稳定地在这些设备的浏览器中运行。不过，由于手机设备屏幕小、且支持特定手势操作。所以，如果想让自己的应用在移动设备上正常运行，建议执行以下操作：

  • 将包含您地图的 <div> 的宽度属性和高度属性都设为 100%。不过请注意，在一些旧版的桌面浏览器上使用这些值无法获得良好的显示效果。
  • Android 和 iOS 设备会应用以下 <meta> 标记：

此设置表示地图以全屏模式显示，不允许用户调整地图的大小。请注意，您需要在网页的 <head> 元素中添加此 <meta> 标记，在 iPhone 的 Safari 浏览器中才能起作用。

其它注意事项

坐标格式：

JavaScript API使用的坐标格式是{纬度, 经度}，即纬度在前，经度在后，如果在使用API过程中，发现地图无法显示，请先查看坐标格式是否正确。从其它几家API切换过来的用户尤其要注意这个区别。

地图级别范围：

JavaScript API使用的二维地图和卫星影像图，级别范围都是[1,18]。

地图基础介绍

腾讯地图开放API应用程序中的基础元素都是地图本身。本文档讨论腾讯地图开放API基础对象的配置和状态属性的修改。本概念性文档分为以下几部分：

地图属性

地图有很多属性，通过更改这些属性可以更改地图实例的状态。我们来看下面两个示例：

修改缩放

查看示例

通过 getZoom( )方法可以得到当前地图的缩放级别，通过 zoomTo( )方法可以修改地图的缩放级别。示例中定时每隔 2 秒钟将地图的缩放级别加 1，腾讯地图API的地图缩放级别为 4-17。

修改中心

查看示例

通过 panTo 方法来设置地图的中心点，每次刷新后 2 秒钟，地图的中心将由 [39.914850, 116.403765] 移动至 [39.9, 116.4]。

更多地图的属性请查看 参考手册。

纬度和经度

用来表示地图位置的方法。在 腾讯 Maps API qq.maps.LatLng 对象提供了此类机制，来实现一个地理坐标位置。您可以构建一个 LatLng 对象，以 {纬度, 经度} 的顺序传递其参数：

如果不知道一个地点（如“天安门”）的地理坐标，可以通过地址解析来得到。请注意：将“地址”转变为地理坐标的过程叫做“地址解析”。有关详细信息，请参见服务部分中的地址解析。也可以通过 《参考手册》 来具体了解这个接口如何去使用。

地图配置

使用腾讯地图 API 默认初始化的地图实例，用户可以对其进行鼠标拖拉、鼠标滚轮进行放大缩小以及鼠标双击放大等操作。我们通过修改地图的配置信息来决定是否希望用户能够通过鼠标操作修改地图状态。腾讯地图API提供了修改地图配置的接口：

查看示例