相同的大幅地图以及针对广告的 SLA、支持和控制
本文档讲述的地图 API 对应的是 2006 年 4 月 3 日投放市场的英文 Maps API 第 2 版。如果您使用的只是中国地图(站点 ditu.google.cn 和 ditu.google.com) API,则不需要担心,因为已经是第 2 版。如果您的 API 使用英文 Maps API 第 1 版(即在 2006 年 4 月 3 日前开发的站点),那么您应该遵照本文档中的说明将您网站的 API 版本升级到最新版。
Maps API 第 2 版对前一版本的 API 有 99% 兼容。第 2 版引入了一个新的地图类 GMap2,包含那些新方法名称的最新接口。旧的地图类 GMap 在第 2 版 API 中将继续存在,并且包含与第 1 版 API 相同的文档接口。不过,第 2 版 API 中引入的大部分新功能只能在新的 GMap2 地图接口中运行。
根据这种设计,您有两种升级方案可供参考:
GMap 接口而不使用第 2 版的新功能。<script> URL 指向“v=2”而不是原先的“v=1”。因为第 2 版保留了旧的 GMap 接口,您的网站应该不用做其他更改就可以正常运行。不过在实际操作中,您还是应该花点时间来调试一下。请参阅不兼容的地方部分来了解已知的 第 1 版和第 2 版 API 之间不兼容用法的列表,并在您遇到其他问题时加入 Google 地图 API 讨论组。GMap2 接口以利用第 2 版的新功能。GMap2代替 GMap。首先,升级您的地图 API <script> URL 指向“v=2”而不是“v=1”,然后根据下面的详细 GMap2 升级指南来更新您的代码。在从 API 第 1 版升级到第 2 版的过程中,我们并没有保留那些不在文档之中的函数。我们认为这应该是网站升级到新版 API 的最大障碍。
每一个使用地图 API 第 1 版的网站都应该升级。第 2 版对地图 API 的底层进行了很多重要的更新,而且第 1 版将会在大部分网站更新完成之后关闭。
无论用户报告的问题多少,第 1 版和第 2 版将会同时运行至少一个月,如果用户在版本转换过程中遇到转换问题很多或者很复杂,我们可能会延长第 1 版的运行时间。之后,第 2 版将成为“默认”的版本,并且所有的网站将自动使用第 2 版。请将您遇到的问题报告到 Google 地图 API 讨论组,在那里有我们的支持人员积极地协助。
第 2 版和第 1 版的文档功能中有少量不兼容的地方,包括:
GXslt 浏览器支持GXslt 现在仅支持具有本地 XSLT 支持的浏览器。由于 Safari 没有本地的 XSLT 支持,因此 GXslt 不再支持 Safari。如果支持 Safari 对您的程序非常重要,您可以通过引入 Google 的开源项目 AJAXSLT 库来重新使 Safari 支持 XSLT。openInfoWindowXslt() 方法 由于 GXslt 的更改,GMap 和 GMarker 随之不再支持 openInfoWindowXslt() 方法。setMapType)centerAndZoom 之前调用 setMapType。2.0 版现在不允许在地图位置初始化之前调用 setMapType。如果您要升级到 GMap2,我们建议您使用新的 GMap2 的 setCenter 方法来一次初始化地图的中心点、缩放等级和地图类型。GMap 升级到 GMap2GLatLng 类地理坐标和屏幕像素坐标现在用不同的类来代表:GLatLng 和 GPoint。setCenter 之类的方法现在使用 GLatLng 的实例作为参数,而不是原来的 GPoint,因此在您升级到使用 GMap2 的时候,您的很多方法调用都应该升级。
第 2 版同时也提供了 GLatLngBounds 类,正确遵守国际日期变更线。
请参阅类参考了解更多信息。
缩放等级索引在 GMap2 中从 0 开始。这样可以更加方便地支持高分辨率的图片。您可以使用以下的公式将旧的缩放等级转换为新的。
newZoom = 17 - oldZoom
普通地图类型在 API 第 2 版中有了新的名字。
G_NORMAL_MAPGMap 接口的很多方法都被替换为使用 GLatLng 类的新方法,而且与新的可扩展的 GMap2 接口保持一致。您可以根据下表内容来升级您的构造函数调用、方法调用和事件句柄。
| 类型 | 第 1 版 |
|---|---|
| 第 2 版 | |
| constructor | GMap(container, mapTypes?, width?, height?) |
| GMap2(container, opts?) | |
| method | GMap.getCenterLatLng() |
| GMap2.getCenter() | |
| method | GMap.getBoundsLatLng() |
| GMap2.getBounds() | |
| method | GMap.getSpanLatLng() |
| GMap2.getBounds() | |
| method | GMap.getZoomLevel() |
| GMap2.getZoom() | |
| method | GMap.centerAtLatLng(center) |
| GMap2.setCenter(center, zoom?, type?) | |
| method | GMap.centerAndZoom(center, zoom) |
| GMap2.setCenter(center, zoom?, type?) | |
| method | GMap.recenterOrPanToLatLng(center) |
| GMap2.panTo(center) | |
| method | GMap.zoomTo(level) |
| GMap2.setZoom(level) | |
| method | GMap.openInfoWindow(point, node, offset?, onopen?, onclose?) |
| GMap2.openInfoWindow(point, node, opts?) | |
| method | GMap.openInfoWindowHtml(point, html, offset?, onopen?, onclose?) |
| GMap2.openInfoWindowHtml(point, html, opts?) | |
| method | GMap.openInfoWindowXslt(point, node, xslturi, offset? , onopen?, onclose?) |
| - | |
| method | GMap.showMapBlowup(point, node, offset?, onopen?, onclose?) |
| GMap2.showMapBlowup(point, opts?) | |
| event | GMap.click(overlay, point) |
| GMap2.click(overlay, point) | |
| event | GMap.zoom(oldLevel, newLevel) |
| GMap2.zoomend(oldLevel, newLevel) | |
| constructor | GMarker(point, icon?) |
| GMarker(point, icon?, inert?) | |
| method | GMarker.openInfoWindow(content) |
| GMarker.openInfoWindow(content, opts?) | |
| method | GMarker.openInfoWindowHtml(content) |
| GMarker.openInfoWindowHtml(content, opts?) | |
| method | GMarker.openInfoWindowXslt(xml, xslt) |
| - | |
| method | GMarker.showMapBlowup(zoom?, type?) |
| GMarker.showMapBlowup(opts?) | |
| constructor | GPolyline(points, color?, weight?, opacity?) |
| GPolyline(points, color?, weight?, opacity?) | |
| constructor | GIcon(copy?) |
| GIcon(copy?, image?) | |
| constructor | GBounds(minx, miny, maxx, maxy) |
| GBounds(points) | |
| constant | G_MAP_TYPE |
| G_NORMAL_MAP | |
| constant | G_SATELLITE_TYPE |
| G_SATELLITE_MAP | |
| constant | G_HYBRID_TYPE |
| G_HYBRID_MAP | |
| static method | GXml.parse(xmltext) |
| GXml.parse(xmltext) | |
| method | GXslt.transformToHtml(xmlnode, htmlnode) |
| GXslt.transformToHtml(xmlnode, htmlnode) |
地图 API 第 2 版提供了非常多新功能,包括:
GOverviewMapControl 控件可以在屏幕的角落显示一个美观的可折叠小地图。GUnload() 方法,您可以通过在页面产生 unload 事件时调用该方法来清除大部分循环引用,包括那些隐藏在事件注册之中的循环引用。在 Google 地图中,这样可以消除几乎所有的 IE 内存泄漏。请参阅文档了解更多信息。alert() 调用替换为 GLog.write()。请参阅类参考了解更多信息。