一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps JavaScript API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps JavaScript API 及相关服务
  3. 创建相应密钥
继续

将您的 Google Maps JavaScript API 应用从 v2 升级到 v3

Google Maps JavaScript API 版本 2 不再可用。本指南旨在帮助使用 Google Maps JavaScript API v2 的开发者将其代码迁移到版本 3

Google Maps JavaScript API v2 与 v3 版本之间存在很大不同。在您使用新 API 着手开发之前,您很容易就会发现变化并不是版本升级这么简单。好消息是,为了帮助开发者开展工作,我们添加了大量出色的新功能并提升了 API 的整体易用性。如果您计划从 Google Maps JavaScript API v2 升级到 Google Maps JavaScript API v3,本指南将帮助您完成迁移,并向 v2 API 的用户介绍了一些最常见的变更。

概览

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

  1. 获取新密钥。Google Maps JavaScript API 现在使用 Google API Console 管理密钥。在您开始迁移之前,务必确保获取您的新 API 密钥
  2. 更新您的 API Bootstrap。大多数应用都使用以下代码加载 Google Maps JavaScript API v3:
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
    
  3. 更新您的代码。所需的更改量很大程度上取决于您的应用。常见更改包括:
    • 始终引用 google.maps 命名空间。在 v3 中,所有 Google Maps JavaScript API 代码都存储在 google.maps.* 命名空间中,而不是全局命名空间中。在此过程中,大多数对象都已重命名。例如,您现在将加载 google.maps.Map,而不是 GMap2
    • 移除对过时方法的任何引用。大量常用实用程序方法已经移除,例如 GDownloadURLGLog。请将此功能替换为第三方实用程序内容库,或者从您的代码中移除这些引用。
    • (可选)向您的代码添加内容库。许多功能都已外部化到实用程序内容库中,这样一来,每个应用仅需要加载要使用的 API 部分。
    • (可选)将您的项目配置为使用 v3 extern。可以使用 v3 extern 通过 Closure Compiler 验证您的代码,也可以使用 v3 extern 在您的 IDE 中触发自动填充。详细了解高级编译和 Extern
  4. 测试和循环访问。目前,您需要做一些工作,但好消息是,您可以按计划开发新的 v3 地图应用!

Google Maps JavaScript API 版本 3 中的变更

在规划迁移之前,您应花一些时间了解 Google Maps JavaScript API v2 与 Google Maps JavaScript API v3 之间的区别。最新版本的 Google Maps JavaScript API 从头开发,侧重于现代 JavaScript 编程技术并增加了内容库的使用,同时简化了 API。API 已经添加了许多新功能,而多个熟悉的功能已经更改或者移除。本部分将重点介绍两个版本之间的主要区别。

v3 API 中的部分变更包括:

  • 简化的核心内容库。许多补充功能都已移动到内容库中,这样有助于缩短核心 API 的加载和解析时间,让您的地图可以在任何设备上快速加载。
  • 提升了多个功能的性能,例如多边形渲染和标记放置。
  • 采用新的客户端使用限制方式,可以更好地适应移动代理与公司防火墙之间共享的地址。
  • 添加了对多款现代浏览器和移动浏览器的支持。已移除对 Internet Explorer 6 的支持。
  • 移除了许多通用帮助程序类(GLogGDownloadUrl)。现在,许多出色的 JavaScript 内容库可以提供类似功能,例如 ClosurejQuery
  • HTML5 街景实现,可以在任何移动设备上加载。
  • 使用您自己的照片自定义街景全景图,允许您分享滑雪道、待售房屋或其他景点的全景图。
  • 样式化地图自定义,允许您更改元素在基础地图上的显示以匹配您独特的视觉样式。
  • 支持多项新服务,例如 ElevationServiceDistance Matrix
  • 改进的路线服务可以提供备用路线、路线优化(基本解决旅行推销员问题)、骑行路线(通过骑行层)公共交通路线和可拖动路线
  • 更新了地理编码格式,可以比 Google Maps Geocoding API v2 中的 accuracy 提供更准确的类型信息。
  • 支持在单个地图上显示多个信息窗口

升级您的应用

您的新密钥

Google Maps JavaScript API v3 使用新密钥体系。这就是说,您的 v2 密钥将不再适用于您的 v3 应用。在将您的应用部署到生产之前添加 v3 密钥具有以下便利:

加载 Google Maps JavaScript API v3 时将传递密钥。要生成密钥,请执行以下操作:

  1. 访问 Google API Console 并登录您的 Google 帐号。
  2. 点击左侧菜单中的 Services 链接,然后激活 Google Maps JavaScript API v3 服务。
  3. 激活服务后,您的 API 密钥可从 API Access 页面的 Simple API Access 部分获得。Maps API 应用使用的是 Key for browser apps

Maps APIs for Work 许可的客户端 ID

如果您拥有 Google Maps APIs for Work 许可,则需要使用客户端 ID 代替密钥。请注意,两者无法同时使用。客户端 ID 与密钥类似,但具有以下不同:

  • 使用客户端 ID 的 Google Maps APIs 应用可以访问更多功能或限制,例如 Maps Analytics
  • 您的客户端 ID 通过 Google Cloud Support 创建并在 Maps APIs for Work 欢迎信中向您提供。您无法使用 Google API Console 创建或查找您的客户端 ID。
  • 加载 Google Maps JavaScript API 时,您将使用 client 参数,而不是 key 参数。例如:
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>
  • 客户端 ID 始终带有前缀 gme-

加载 API

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

  1. //maps.googleapis.com/maps/api/js 加载 API
  2. 移除 file 参数。
  3. 务必添加必需的 sensor 参数
  4. 使用新的 v3 密钥更新 key 参数。Google Maps APIs for Work 客户应使用 client 参数。
  5. (仅限 Google Maps APIs Premium Plan)确保按照 Google Maps APIs Premium Plan开发者指南中的说明提供 client 参数。
  6. 移除 v 参数以请求最新的发布版本或将其值相应地更改为 v3 版本控制方案。
  7. (可选)hl 参数替换为 language 并保留其值。
  8. (可选)添加一个 libraries 参数以加载可选内容库

在最简单的情况下,v3 bootstrap 将仅指定您的 API 密钥和 sensor 参数:

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=false"></script>

下面的示例将请求最新的(实验性)德语版 Maps JavaScript API v2:

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

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

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

版本控制

v3 中不需要加载特定版本。如果您忽略版本参数,将获得最近的实验性 API 版本。如果您愿意,可以指定特定的版本号、最新的(实验性)版本或者最稳定的冻结版本。

下表是 v2 与 v3 之间的版本模式映射。

v2 v3 用例
2.s 3.0 冻结版本。最旧版本可用。
2 3 发布版本。最新的稳定版本。
2.x 3.exp 实验性版本。

重要说明Google Maps APIs Premium PlanSLA 不适用于实验性版本。Google Maps APIs Premium Plan应用必须使用当前的发布冻结版本才能纳入 SLA。

引入 google.maps 命名空间

Google 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
或者 google.maps.PolylineOptions

移除过时代码

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

以下类在 Google 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&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    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?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    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 的地址已经发生变化。
  • GBrowserIsCompatible()GUnload() 方法在 v3 中不再为必需参数,已从 API 中移除。
  • 作为 API 中的中心对象,GMap2 对象已被替换为 google.maps.Map
  • 属性现在通过 Options 类加载。在上面的示例中,我们通过一个内联的 MapOptions 对象设置了加载地图所需的三个属性 - centerzoommapTypeId
  • 默认情况下,默认 UI 在 v3 中处于开启状态。您可以通过在 MapOptions 对象中将 disableDefaultUI 属性设为 true 来停用此设置。

总结

到这里,您可能已经领会到从 Google Maps JavaScript API v2 迁移到 Google Maps JavaScript API v3 时涉及的一些要点。您还需要了解很多信息,不过,这取决于您的应用。在下面的部分中,我们将介绍具体案例的迁移说明,您可能会遇到这些案例。此外,我们还会提供多种资源,您可能会发现这些资源对升级很有帮助。

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

详细参考

本部分将介绍 Google Maps JavaScript API v2 与 v3 中最常用功能的详细比较。可以单独阅读参考的每个部分。我们建议您不要通篇阅读此参考;您可以根据具体案例的需要使用此材料协助迁移。

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

活动

Google Maps JavaScript API v3 的事件模式与 v2 中使用的相似,但内部也进行了大量变更。

控件

Google Maps JavaScript API 可以显示 UI 控件,这些控件允许用户与您的地图交互。您可以使用 API 自定义这些控件的显示方式。

叠层

叠层反映您“添加”到地图上用来指定点、线、区域或对象集合的对象。

地图类型

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

是地图上由一个或多个叠层组成的对象。它们可以作为一个单元操作,通常反映对象集合。

服务

发送以下问题的反馈:

此网页
Google Maps JavaScript API
Google Maps JavaScript API
需要帮助?请访问我们的支持页面