Google Maps API第二版升级指南

本文档介绍了怎样将您的代码Google Maps API 从第一版升级到2006-04-03推出的第二版.如果您的网站是在该时间之前开发的，您应该按照本文下面的说明来将您的网站API版本升级到最新版.

介绍

升级概要

Maps API第2版能对前一版本有99%的兼容，第2版提供了一个新的类GMap2,包含那些新方法名称的接口.旧的类GMap在第2版之中继续存在,而且和第1版的文档之中的接口一样没有变化.不过大部分的新功能只能在GMap2接口之中运行.

根据设计，您有两种升级方案可供参考:

继续使用GMap接口而不使用第2版的新功能.

最快的升级方法是将您的Maps API <script> URL指向到"v=2"而不是原先的"v=1."因为第2版保留了GMap接口,您的网站应该不做其他更改就可以正常运行.不过为了保险起见,您还是应该花点时间来测试一下.请参看不兼容的地方来了解已知的不兼容用法的列表,并在您遇到其他问题之后加入到Maps API讨论组参与讨论.
升级到GMap2接口以使用第2版的新功能.

要使用第2版的新功能例如分标签的信息浮窗和自定义控件,应该使用GMap2代替GMap. 首先,升级您的Maps API <script> URL从"v=1."变为"v=2",然后根据下面的GMap2升级向导来更新您的代码.

在从API第1版升级到第2版的过程之中，我们并没有保留那些不在文档之中的函数. 我们认为这应该是API升级到新版的最大的障碍.

谁需要升级?

每一个Maps API网站都应该升级.第2版对Maps API的底层进行了很多重要的更新, 而且第1版将会在大部分网站更新完成之后关闭.

第1版和第2版将会同时运行至少一个月,如果用户在版本转换过程之中遇到因为第2版的Bug引起的问题，不管问题的大小，我们都将延长第1版的运行时间，之后，第2版将成为默认的版本并且所有的网站自动使用第2版，讲讲您遇到的问题报告到Google Maps API讨论组.

第二版和第一版不兼容的地方

第2版和第1版有少量不兼容的地方，包括:

GXslt浏览器支持

GXslt现在仅仅支持本地的XSLT转换.因为Safari没有本地的XSLT支持, 因此GXslt不再支持Safari.如果支持Safari对您的程序非常重要，您可以通过引入Google的开源项目AJAXSLT库来重新使Safari支持XSLT.
openInfoWindowXslt()方法

因为GXslt不再被支持，因此GMap和GMarker随之不再支持openInfoWindowXslt()方法.
Map初始化顺序(setMapType)

1.0版允许您在centerAndZoom之前调用setMapType.2.0版现在不允许在地图初始化之前调用setMapType.如果您正升级到GMap2,我们建议您使用新的GMap2的setCenter方法来一次初始化地图的中心点、缩放等级和地图类型.
不在文档之中的方法

Maps API第2版更新了整个API的核心，因此几乎所有原先不在文档之中的方法都不再支持了(这个对我的打击最大了，其实我相信Google没有变动太多，就是那个代码混淆更强了21).

从`GMap`升级到`GMap2`

`GLatLng`类

地理坐标和屏幕像素坐标现在分离为用不同的类来代表, GLatLng和GPoint.setCenter之类的方法现在使用GLatLng的实例作为参数，而不是原来的GPoint,因此在您升级到使用GMap2的时候您的很多函数调用都应该进行升级.

第2版同时也提供了GLatLngBounds类,用来代表一个经纬度区域.

查看类参考了解更多.

缩放等级顺序

缩放等级在GMap2之中从0(最小的世界全图)开始.这样可以更加方便的支持高分辨率的图片.您可以使用以下的公式来将旧的经纬度转化为新的:

newZoom = 17 - oldZoom

地图类型名称的变动

地图类型(地图,卫星图,混合图)在API第2版之中有了新的名字:

G_NORMAL_MAP
G_SATELLITE_MAP
G_HYBRID_MAP

方法名称的变动

GMap接口的很多方法都被替换成使用GLatLng类的新方法，而且和GMap2接口的可扩展性保持一致.您能够根据下表内容来升级您的函输调用，方法调用和事件句柄:

类型	第1版
类型	第2版
构造函数	GMap(container, mapTypes?, width?, height?)
构造函数	GMap2(container, opts?)
方法	GMap.getCenterLatLng()
方法	GMap2.getCenter()
方法	GMap.getBoundsLatLng()
方法	GMap2.getBounds()
方法	GMap.getSpanLatLng()
方法	GMap2.getBounds()
方法	GMap.getZoomLevel()
方法	GMap2.getZoom()
方法	GMap.centerAtLatLng(center)
方法	GMap2.setCenter(center, zoom?, type?)
方法	GMap.centerAndZoom(center, zoom)
方法	GMap2.setCenter(center, zoom?, type?)
方法	GMap.recenterOrPanToLatLng(center)
方法	GMap2.panTo(center)
方法	GMap.zoomTo(level)
方法	GMap2.setZoom(level)
方法	GMap.openInfoWindow(point, node, offset?, onopen?, onclose?)
方法	GMap2.openInfoWindow(point, node, opts?)
方法	GMap.openInfoWindowHtml(point, html, offset?, onopen?, onclose?)
方法	GMap2.openInfoWindowHtml(point, html, opts?)
方法	GMap.openInfoWindowXslt(point, node, xslturi, offset? , onopen?, onclose?)
方法	-
方法	GMap.showMapBlowup(point, node, offset?, onopen?, onclose?)
方法	GMap2.showMapBlowup(point, opts?)
事件	GMap.click(overlay, point)
事件	GMap2.click(overlay, point)
事件	GMap.zoom(oldLevel, newLevel)
事件	GMap2.zoomend(oldLevel, newLevel)
构造函数	GMarker(point, icon?)
构造函数	GMarker(point, icon?, inert?)
方法	GMarker.openInfoWindow(content)
方法	GMarker.openInfoWindow(content, opts?)
方法	GMarker.openInfoWindowHtml(content)
方法	GMarker.openInfoWindowHtml(content, opts?)
方法	GMarker.openInfoWindowXslt(xml, xslt)
方法	-
方法	GMarker.showMapBlowup(zoom?, type?)
方法	GMarker.showMapBlowup(opts?)
构造函数	GPolyline(points, color?, weight?, opacity?)
构造函数	GPolyline(points, color?, weight?, opacity?)
构造函数	GIcon(copy?)
构造函数	GIcon(copy?, image?)
构造函数	GBounds(minx, miny, maxx, maxy)
构造函数	GBounds(points)
常量	G_MAP_TYPE
常量	G_NORMAL_MAP
常量	G_SATELLITE_TYPE
常量	G_SATELLITE_MAP
常量	G_HYBRID_TYPE
常量	G_HYBRID_MAP
静态方法	GXml.parse(xmltext)
静态方法	GXml.parse(xmltext)
方法	GXslt.transformToHtml(xmlnode, htmlnode)
方法	GXslt.transformToHtml(xmlnode, htmlnode)

版本2的新功能

Maps API第2版提供了非常多的新功能,包含:

JavaScript文件更小

新的Maps API JavaScript文件大小只是过去的一半左右,这样应该对您网站带来更好的用户体验.
添加了2个卫星图缩放等级

在美国、加拿大、英国、日本、欧洲和几乎世界上所有的城市添加了更加清晰的卫星图片.
鹰眼地图控件

我们的新的GOverviewMapControl控件可以在地图的角落显示一个美观的可折叠的地图.
自定义地图控件

您能够通过继承GControl来自定义地图控件，类似GSmallMapControl.查看范例或类参考了解更多信息.
自定义地图标注

您能够通过继承GOverlay来自定义地图标注，类似GMarker和GPolyline.查看范例或类参考了解更多信息.
更少内存溢出

API现在包含一个GUnload()方法，您可以通过在页面产生unload事件时调用该方法来清除几乎所有的循环引用,包括那些隐藏在事件注册的之中的循环引用.在Google Maps之中,这样可以消除几乎所有的IE内存溢出.查看文档了解更多.
调试记录

一个简单的浮动窗口，原先只是在Google Maps小组内部测试使用，现在开放出来让您能够轻松的输出调试信息，而不需要终止程序运行或被用户UI所影响.住需要替换您的alert()代码为GLog.write().查看类参考了解更多.