一切就绪!

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

激活 Google Maps JavaScript API

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

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

入门指南

受众

本文档专为熟悉 JavaScript 编程及对象导向型编程概念的人员而设计。此外,您还应从用户角度熟悉 Google 地图。Web 上提供了许多 JavaScript 教程

本概念性文档旨在帮助您快速着手了解 Google Maps JavaScript API 并利用它开发应用。我们还发布了 Google Maps JavaScript API 参考

Hello, World

着手了解 Google Maps JavaScript API 最简单的方法是查看一个简单示例。以下网页显示的地图以澳大利亚新南威尔士州悉尼为中心:

var map;
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>
<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0">
    <meta charset="utf-8">
    <style>
      /* Always set the map height explicitly to define the size of the div
       * element that contains the map. */
      #map {
        height: 100%;
      }
      /* Optional: Makes the sample page fill the window. */
      html, body {
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map;
      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: {lat: -34.397, lng: 150.644},
          zoom: 8
        });
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

查看示例 (map-simple.html)

即便是在这个简单示例中,仍有几点需要注意:

  1. 我们利用 <!DOCTYPE html> 声明以 HTML5 形式声明应用。
  2. 我们创建了一个名为“map”的 div 元素来存放地图。
  3. 我们定义了一个在 div 中创建地图的 JavaScript 函数。
  4. 我们使用 script 标记加载 Maps JavaScript API。

下文对这些步骤做了说明。

以 HTML5 形式声明您的应用

我们建议您在 Web 应用内声明真正的 DOCTYPE。在此处的示例内,我们已使用如下所示的简单 HTML5 DOCTYPE 以 HTML5 形式声明了我们的应用:

<!DOCTYPE html>

大多数最新浏览器都会在“标准模式”下渲染通过此 DOCTYPE 声明的内容,这意味着您的应用应具有更高的跨浏览器兼容性。此外,DOCTYPE 还设计为可以适当方式降级;无法识别它的浏览器会将其忽略,并使用“兼容模式”来显示其内容。

请注意,某些在兼容模式下有效的 CSS 在标准模式下无效。具体地讲,所有基于百分比的尺寸必须从父块元素继承,并且如果任一父项未能指定尺寸,则假定其尺寸为 0 x 0 像素。因此,我们加入了以下 <style> 声明:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

此 CSS 声明表示地图容器 <div>(具有 map ID)应占据 100% 的 HTML 正文高度。请注意,我们同样必须为 <body><html> 明确声明这些百分比。

加载 Google Maps JavaScript API

要加载 Google Maps JavaScript API,请使用类似于下列示例中的 script 标记:
    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>

script 标记中包含的网址是一个 JavaScript 文件的位置,该文件用于加载使用 Maps JavaScript API 所需的所有符号和定义。此 script 标记为必需。

async 属性允许浏览器在 Maps JavaScript API 加载的同时渲染网站的其余内容。当 API 就绪时,它将调用使用 callback 参数指定的函数。

key 参数包含应用的 API 密钥。如需了解详细信息,请参阅获取密钥

注:Google Maps APIs Premium Plan客户可以在加载 API 时使用 API 密钥或有效的客户端 ID。获取有关 Premium Plan 客户身份验证参数的更多信息。

HTTPS 或 HTTP

我们认为 Web 安全性相当重要,因此建议尽可能使用 HTTPS。作为提高网络安全性工作的一部分,我们已实现所有 Maps JavaScript API 都通过 HTTPS 提供。使用 HTTPS 加密可提高您的网站的安全性及其抵御窥探或篡改的能力。

我们建议使用上文提供的 <script> 标记通过 HTTPS 加载 Maps JavaScript API。

必要时,您可以通过请求 http://maps.googleapis.com/(对于中国用户,则是 http://maps.google.cn)通过 HTTP 加载 Maps JavaScript API。

通过网址加载 Maps JavaScript API 时,作为可选步骤,您可以利用 libraries 网址参数加载更多内容库。内容库是一些代码模块,可为主 Maps JavaScript API 提供附加功能,但只在您明确请求时加载。如需了解详细信息,请参阅 Maps JavaScript API 中的内容库

同步加载 API

在加载 Maps JavaScript API 的 script 标记中,可以省略 async 属性和 callback 参数。这会冻结 API 的加载,在 API 下载完成时再继续执行。

这样做很可能会减缓页面加载速度,但意味着您可以在编写后续脚本标记时假定 API 已经加载。

地图 DOM 元素

<div id="map"></div>

要想在网页上显示地图,我们必须为其预留一个位置。我们通常的实现方式是:创建一个命名的 div 元素,然后在浏览器的文档对象模型 (DOM) 中获取对该元素的引用。

在上例中,我们利用 CSS 将地图 div 的高度设置为“100%”。这会扩展 div,使其适应移动设备的尺寸。您可能需要根据浏览器的屏幕尺寸和内边距调整宽度值和高度值。请注意,div 通常从其包含元素获取宽度值,空 div 的高度通常为 0。因此,您必须始终显式地在 <div> 上设置高度。

地图选项

每个地图都有两个必需选项:centerzoom

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

缩放比例

显示地图时使用的初始分辨率由 zoom 属性设置,缩放比例 0 表示最大缩小比例下的地球地图,更大缩放比例会以更高分辨率放大地图。将缩放比例指定为整数。

zoom: 8

以单幅图像形式提供整个地球的地图需要巨幅尺寸的地图,或者分辨率很低的小地图。因此,Google 地图和 Maps JavaScript API 内的地图图像才会被分解成地图“图块”和“缩放比例”。缩放比例较低时,一小组地图图块便可覆盖大片区域;缩放比例较高时,图块分辨率较高,只能覆盖较小区域。下面的列表显示了您在每个缩放比例下会看到的大致细节级别:

  • 1:世界
  • 5:大陆/洲
  • 10:城市
  • 15:街道
  • 20:建筑物

以下三幅图像反映的是东京同一位置在 0、7 和 18 缩放比例下的情况。

如需了解有关 Maps JavaScript API 如何根据当前缩放比例加载图块的信息,请参阅“地图类型”文档中的图块坐标

地图对象

map = new google.maps.Map(document.getElementById("map"), {...});

表示地图的 JavaScript 类是 Map 类。该类的对象定义页面上的单个地图。(您可以创建该类的多个实例–每个对象都将定义页面上的一个不同地图。)我们利用 JavaScript new 运算符来新建该类的实例。

当您新建地图实例时,您需要在页面中以地图容器形式指定一个 <div> HTML 元素。HTML 节点是 JavaScript document 对象的子项,我们通过 document.getElementById() 方法获取对该元素的引用。

此代码定义一个变量(名为 map)并将该变量赋值给一个新的 Map 对象。函数 Map() 称为构造函数,其定义如下所示:

构造函数 说明
Map(mapDiv:Node, opts?:MapOptions ) 利用传递的任何(可选)参数在给定 HTML 容器(通常是一个 DIV 元素)内新建一个地图。

故障排除

为帮助您让地图代码正常运行,Brendan KennyMano Marks 在这段视频中指出了一些常见错误及其修正方法。

如果您的代码不能正常工作:

  • 寻找打字错误。切记 JavaScript 是一种区分大小写的语言。
  • 检查基础环节–一些最常见的问题发生在地图创建的初始阶段。例如:
    • 确认您已在地图选项中指定了 zoom 属性和 center 属性。
    • 确保您已声明用于容纳出现在屏幕上的地图的 div 元素。
    • 确保地图的 div 元素具有高度。默认情况下,创建的 div 元素高度为 0,因此不可见。
    请参阅我们的示例,了解参考实现
  • 利用 JavaScript 调试器(如 Chrome Developer Tools 中提供的调试器)来帮助发现问题。首先查看 JavaScript 控制台中有无错误。
  • Stack Overflow 发布问题。支持页面上提供了有关如何发布理想问题的指南。

发送以下问题的反馈:

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