将您的 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 外部函数可用于帮助您使用 Closure 编译器验证代码，或在 IDE 中触发自动补全。 详细了解 高级编译和外部函数。
  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 和 Distance Matrix。
  • 改进后的路线服务提供备选路线、路线优化（对 旅行推销员问题的近似解）、骑车路线（带有 骑车图层）、公交路线和 可拖动路线。
  • 更新后的地理编码格式，提供比 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 默认会将所有对象放入“Global”命名空间，这可能会导致命名冲突。在 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 中的大多数功能类似；不过，有些类已不再受支持。在迁移过程中，您应将这些类替换为第三方实用程序库，或从代码中移除这些引用。有很多出色的 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 API 和 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 使用标准的“绘制”道路地图图块。不过，在 v3 中，创建 google.maps.Map 对象时需要提供特定的映射类型。

图层

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

服务