将 Maps JavaScript API 应用从 V2 升级到 V3

自 2021 年 5 月 26 日起,Maps JavaScript API v2 不再可用。因此,您网站的 v2 地图将停止运行,并返回 JavaScript 错误。若要继续在您的网站上使用地图,请改用 Maps JavaScript API v3。本指南将帮助您完成此流程。

概览

每个应用的迁移过程略有不同;不过,有一些步骤是所有项目通用的:

  1. 获取新密钥。Maps JavaScript API 现在使用 Google Cloud Console 来管理密钥。如果您仍在使用 v2 密钥,请务必先获取新的 API 密钥,然后再开始迁移。
  2. 更新 API 引导加载程序。大多数应用都会使用以下代码加载 Maps JavaScript API v3:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. 更新您的代码。所需的更改量在很大程度上取决于您的应用。常见变更包括:
    • 始终引用 google.maps 命名空间。在 v3 中,所有 Maps JavaScript API 代码都存储在 google.maps.* 命名空间(而非全局命名空间)中。在此过程中,大多数对象都已重命名。例如,您现在将加载 google.maps.Map,而不是 GMap2
    • 移除对过时方法的所有引用。移除了许多通用实用程序方法,例如 GDownloadURLGLog。 请将此功能替换为第三方实用程序库,或从代码中移除这些引用。
    • (可选)将库添加到您的代码中。许多功能都已外部化到实用程序库中,因此每个应用只需加载要使用的 API 部分。
    • (可选)将您的项目配置为使用 v3 extern。 v3 extern 可用于通过 Closure 编译器验证您的代码,或在 IDE 中触发自动补全功能。 详细了解高级编译和 Extern
  4. 测试并迭代。此时,您仍然有很多工作要做,但好消息是,您已经可以顺利开始使用自己的新 v3 地图应用了!

Maps JavaScript API V3 中的变更

在规划迁移之前,您应该花些时间了解 Maps JavaScript API v2 与 Maps JavaScript API v3 之间的区别。最新版本的 Maps JavaScript API 从头专门编写,侧重于现代 JavaScript 编程技术,增加了库的使用并简化了 API。该 API 中增加了许多新功能,一些熟悉的功能也发生了变化,甚至被移除。本部分重点介绍了这两个版本之间的一些主要区别。

v3 API 中的部分变更包括:

  • 简化的核心库。许多补充功能已移至中,有助于减少 Core API 的加载和解析时间,从而缩短地图在任意设备上的加载速度。
  • 改进了多项功能(例如多边形渲染和标记放置)的性能。
  • 一种新的客户端使用限制,可以更好地适应移动代理和公司防火墙使用的共享地址。
  • 添加了对多种新型浏览器和移动浏览器的支持。移除了对 Internet Explorer 6 的支持。
  • 移除了许多通用辅助类(GLogGDownloadUrl)。目前,有许多出色的 JavaScript 库可以提供类似的功能,例如 ClosurejQuery
  • HTML5 街景实现,可以在任何移动设备上加载。
  • 使用您自己的照片自定义街景全景图片,并可以分享滑雪场、待售房屋或其他有趣地点的全景图片。
  • 样式化地图自定义设置,可让您更改基本地图上的元素显示方式,从而匹配您独特的视觉样式。
  • 支持多种新服务,例如 ElevationService距离矩阵
  • 改进的路线服务提供了备选路线、路线优化(旅行推销员问题的近似解决方案)、骑车路线(使用骑行图层)、公交路线和可拖动路线
  • 更新了地理编码格式,可提供比 Geocoding API v2 中的 accuracy 值更准确的类型信息。
  • 支持在单个地图上显示多个信息窗口

升级您的应用

您的新密钥

Maps JavaScript API v3 使用了 v2 中的新密钥系统。您可能已经在自己的应用中使用 v3 密钥,在这种情况下无需进行任何更改。如需进行验证,请检查从中加载 Maps JavaScript API 的网址以获取其 key 参数。如果键值以 'ABQIAA' 开头,则表示您使用的是 v2 密钥。如果您使用的是 v2 密钥,则必须在迁移过程中升级到 v3 密钥,这将:

系统会在加载 Maps JavaScript API v3 时传递该密钥。详细了解如何生成 API 密钥

请注意,如果您是 Google Maps API for Work 客户,可能使用的是包含 client 参数的客户端 ID,而不是使用 key 参数。Maps JavaScript API v3 仍支持客户端 ID,因此无需完成密钥升级流程。

加载 API

您需要对代码进行的第一项修改涉及 API 的加载方式。在 v2 中,您通过向 http://maps.google.com/maps 发出的请求加载 Maps JavaScript API。如果要加载 Maps JavaScript API v3,您需要进行以下更改:

  1. //maps.googleapis.com/maps/api/js 加载 API
  2. 移除 file 参数。
  3. 使用新的 v3 密钥更新 key 参数。Google Maps API for Work 客户应使用 client 参数。
  4. (仅限 Google Maps Platform 高级计划)确保提供 client 参数(如 Google Maps Platform 高级计划开发者指南中所述)。
  5. 移除 v 参数以请求最新发布的版本,或者根据 v3 版本控制方案更改其值。
  6. (可选)hl 参数替换为 language 并保留其值。
  7. (可选)添加 libraries 参数以加载可选库

在最简单的情况下,v3 引导加载程序将仅指定您的 API 密钥参数:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

以下示例请求德语版 Maps JavaScript API v2 的最新版本:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

下面的示例是 v3 中对应的请求。

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

引入 google.maps 命名空间

Maps JavaScript API v3 中最明显的变化可能就是引入了 google.maps 命名空间。v2 API 默认会将所有对象置于全局命名空间中,这可能会导致命名冲突。在 v3 中,所有对象都位于 google.maps 命名空间内。

将应用迁移到 v3 时,您必须更改代码以利用新的命名空间。遗憾的是,搜索“G”并替换为“google.maps.”无法完全起作用;不过,在检查代码时,最好遵循这一经验法则。以下是 v2 和 v3 中的等效类的一些示例。

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

移除过时代码

对于 v2 中的大多数功能,Maps JavaScript API v3 都有对应的功能;但也有一些类不再受支持。在迁移过程中,您应将这些类替换为第三方实用程序库,或从代码中移除这些引用。许多出色的 JavaScript 库可以提供类似的功能,例如 ClosurejQuery

Maps JavaScript API v3 中没有以下类:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

比较代码

我们来比较一下两个使用 v2 和 v3 API 编写的比较简单的应用。

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

如您所见,这两个应用之间存在一些差异。显著变更包括:

  • 加载 API 的地址已经发生变化。
  • v3 中不再需要 GBrowserIsCompatible()GUnload() 方法,它们已从 API 中移除。
  • GMap2 对象已替换为 google.maps.Map 作为 API 中的中心对象。
  • 系统现在通过选项类加载属性。在上面的示例中,我们通过内嵌 MapOptions 对象设置了加载地图所需的三个属性:centerzoommapTypeId
  • 默认情况下,v3 中的默认用户界面处于启用状态。您可以通过在 MapOptions 对象中将 disableDefaultUI 属性设置为 true 来停用此功能。

总结

现在,您已经了解了从 Maps JavaScript API v2 迁移到 v3 所涉及的一些关键点。 您可能需要了解更多信息,但这取决于您的应用。以下部分针对您可能遇到的具体情况提供了迁移说明。此外,在升级过程中,您可能会找到一些有用的资源。

如果您对本文有任何问题或疑问,请使用此页面顶部的发送反馈链接。

详细参考

本部分对 Maps JavaScript API v2 和 v3 最受欢迎的功能进行了详细比较。本参考资料的各个部分旨在单独阅读。我们建议您不要阅读其完整内容,而应根据具体具体情况使用该材料。

  • 事件 - 注册和处理事件。
  • 控件 - 操作地图上显示的导航控件。
  • 叠加层 - 在地图上添加和编辑对象。
  • 地图类型 - 构成基本地图的图块。
  • 图层 - 以组的形式添加和修改内容,例如 KML 图层或路况图层。
  • 服务 - 使用 Google 的地理编码、路线或街景服务。

事件

Maps JavaScript API v3 的事件模型与 v2 中使用的事件模型类似,但会在后台进行大量更改。

控件

Maps JavaScript API 会显示界面控件,以便用户与您的地图互动。您可以使用 API 自定义这些控件的显示方式。

叠加层

叠加层反映的是您“添加”到地图上的对象,用以表示点、线、区域或对象集合。

地图类型

v2 和 v3 中提供的地图类型略有不同,但所有基本地图类型在两个版本的 API 中都可用。默认情况下,v2 使用标准的“绘制”道路地图图块。不过,在创建 google.maps.Map 对象时,v3 需要指定特定的地图类型。

图层是地图上的对象,包含一个或多个叠加层。它们可以作为一个单元进行操作,通常反映对象集合。

服务