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

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

概览

每个应用的迁移过程略有不同；不过，有些步骤是所有项目都通用的：

  1. 获取新密钥。Maps JavaScript API 现在使用 Google Cloud 控制台来管理密钥。如果您仍在使用 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。
    • 移除对过时方法的任何引用。移除了一些通用实用程序方法，例如 GDownloadURL 和 GLog。请将此功能替换为第三方实用程序库，或从您的代码中移除这些引用。
    • （可选）将库添加到您的代码中。许多功能已外部化到实用程序库中，因此每个应用只需加载要使用的 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 的支持。
  • 移除了许多通用帮助程序类（ GLog 或 GDownloadUrl）。目前，许多优秀的 JavaScript 库可以提供类似功能，例如 Closure 或 jQuery。
  • 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 客户，您可能要搭配使用客户端 ID 和 client 参数，而不使用 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 专业版方案）确保按照 Google Maps Platform 专业版方案开发者指南中的说明提供 client 参数。
  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

移除过时代码

Maps JavaScript API v3 中的大多数功能在 v2 中都有对应功能；不过，v2 中的一些类不再受支持。在迁移过程中，您应将这些类替换为第三方实用程序库，或从代码中移除这些引用。市面上有许多提供类似功能的优秀 JavaScript 库，例如 Closure 或 jQuery。

以下类在 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 对象设置了加载地图所需的三个属性：center、zoom 和 mapTypeId。
  • 默认情况下，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 要求提供特定的地图类型。

层

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

服务