Google 地图 API 第 2 版升级指南

本文档讲述的地图 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 版的新功能。
  最快的升级方法是将您的 Maps API <script> URL 指向“v=2”而不是原先的“v=1”。因为第 2 版保留了旧的 GMap 接口，您的网站应该不用做其他更改就可以正常运行。不过在实际操作中，您还是应该花点时间来调试一下。请参阅不兼容的地方部分来了解已知的 第 1 版和第 2 版 API 之间不兼容用法的列表，并在您遇到其他问题时加入 Google 地图 API 讨论组。
• 升级到 GMap2 接口以利用第 2 版的新功能。
  要使用第 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 版不兼容的地方

第 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 的核心，因此几乎所有原先不在文档之中的方法都不再受支持了。

从 GMap 升级到 GMap2

GLatLng 类

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

第 2 版同时也提供了 GLatLngBounds 类，正确遵守国际日期变更线。

请参阅类参考了解更多信息。

缩放等级顺序

缩放等级索引在 GMap2 中从 0 开始。这样可以更加方便地支持高分辨率的图片。您可以使用以下的公式将旧的缩放等级转换为新的。

newZoom = 17 - oldZoom

地图类型名称的变动

普通地图类型在 API 第 2 版中有了新的名字。

• G_NORMAL_MAP

方法名称的变动

GMap 接口的很多方法都被替换为使用 GLatLng 类的新方法，而且与新的可扩展的 GMap2 接口保持一致。您可以根据下表内容来升级您的构造函数调用、方法调用和事件句柄。

版本 2 的新功能

地图 API 第 2 版提供了非常多新功能，包括：

• JavaScript 下载更小
  新的地图 API JavaScript 文件大小只是旧的 JavaScript 文件的一半左右，这样可以改善您网站的用户体验。
• 缩略图控件
  我们新的 GOverviewMapControl 控件可以在屏幕的角落显示一个美观的可折叠小地图。
• 定制地图控件
  除了像 GSmallMapControl 这样的内置控件外，您可以通过继承 GControl 来定义定制地图控件。请参阅示例或类参考来了解更多信息。
• 定制地图叠加层
  除了内置 GMarker 和 GPolyline 类，您还可以通过继承 GOverlay 来定义定制地图叠加层。请参阅示例或类参考来了解更多信息。
• 更少的内存泄漏
  API 现在包含一个 GUnload() 方法，您可以通过在页面产生 unload 事件时调用该方法来清除大部分循环引用，包括那些隐藏在事件注册之中的循环引用。在 Google 地图中，这样可以消除几乎所有的 IE 内存泄漏。请参阅文档了解更多信息。
• 调试记录
  一个简单的浮动窗口，原先只是 Google 地图工程小组内部测试使用，现在开放出来让您能够轻松地打印调试信息，而不需要终止程序运行或干扰 UI 。只需要将您的 alert() 调用替换为 GLog.write()。请参阅类参考了解更多信息。