My favorites | 中文(简体) | Sign in

Google 地图 API 专业版

除了同样具有功能强大的地图外,还包含 SLA、支持和广告控制。

Google 地图 API 第 2 版升级指南

该文档描述了怎样从 Google 地图 API 第 1 版升级到 2006 年 4 月3 日发布的第 2 版。如果您的网站是在 2006 年 4 月 3 日之前开发的,那么您应该遵照本文档中的说明将您网站的 API 版本升级到最新版。

目录

简介

升级概述

地图 API 第 2 版对前一版本的 API 有 99% 兼容。第 2 版引入了一个新的地图类 GMap2,包含那些新方法名称的最新接口。旧的地图类 GMap 在第 2 版 API 中将继续存在,并且包含与第 1 版 API 相同的文档界面。不过,第 2 版 API 中引入的大部分新功能只能在新的 GMap2 地图接口中运行。

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

  • 继续使用相同的 GMap 接口而不使用第 2 版的新功能。
    最快捷的升级方式是更新您的地图 API <script>网址以引用“v=2”而非“v=1”。由于第 2 版保留了旧的 GMap 接口,因此您的网站应在理论上可无需进一步更改继续工作。不过在实际操作中,您还是应该花点时间来调试一下。请参见不兼容的地方部分来了解已知的 第 1 版和第 2 版 API 之间不兼容用法的列表,并在您遇到其他问题时加入 地图 API 讨论组
  • 升级到 GMap2 接口以利用第 2 版的新功能。
    要使用第 2 版的新功能,如带标签的信息窗口和自定义地图控件,应该使用 GMap2 而非 GMap。首先,更新您的地图 API <script>网址以引用“v=2”而非“v=1”。然后,根据下面的详细 GMap2升级指南更新您的代码。

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

哪些人需要升级?

每一个地图 API 网站都应该升级。第 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 更改,GMapGMarker 不再支持 openInfoWindowXslt() 方法。
  • 地图初始化顺序 (setMapType)
    版本 1.0 使您可以在 centerAndZoom 之前调用 setMapType。2.0 版现在不允许在地图位置初始化之前调用 setMapType。如果您要升级到 GMap2,我们建议您使用新的 GMap2 中的 setCenter 方法来一次初始化中心点、缩放等级和地图类型。
  • 不在文档之中的方法
    地图 API 第 2 版更新了整个 API 的核心,因此几乎所有原先不在文档之中的方法都不再受支持了。

GMap 升级到 GMap2

GLatLng

地理坐标和屏幕像素坐标现在用不同的类来代表:GLatLngGPointsetCenter 之类的方法现在使用 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 版的新功能

地图 API 第 2 版提供了非常多的新功能,包括:

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