概览

请选择平台： Android iOS JavaScript

借助 Maps JavaScript API，您可以使用自己的内容和图像打造自定义地图，以显示在网页和移动设备上。Maps JavaScript API 提供了四种基本地图类型（路线图地图、卫星地图、混合地图和地形地图），您可以使用图层和样式、控件和事件及各种服务和库对其进行修改。

受众群体

本文档适用于熟悉 JavaScript 编程和面向对象编程概念的人员。此外，您还应该从用户的角度熟悉 Google 地图。您可以在网上找到许多 JavaScript 教程。

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

Hello, World

若要开始了解 Maps JavaScript API，最简单的方法就是查看简单示例。以下示例显示了以澳大利亚新南威尔士州悉尼市为中心的地图。

TypeScript

let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

let map;

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

window.initMap = initMap;index.js

CSS

/*
 * 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.css

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

查看示例

试用示例

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

即便是在这个简单示例中，仍需注意以下一些事项：

我们使用 <!DOCTYPE html> 声明，以 HTML5 形式声明应用。
我们创建一个名为“map”的 div 元素来保存地图。
我们定义一个在 div 中创建地图的 JavaScript 函数。
我们使用 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>（ID 为 map）应占据 100% 的 HTML 正文高度。请注意，我们同样必须为 <body> 和 <html> 明确声明这些百分比。

加载 Maps JavaScript API

Maps JavaScript API 可使用 script 标记（该标记可以内嵌方式添加到 HTML 文件中）进行加载，也可使用单独的 JavaScript 文件动态加载。建议您同时查看这两种方法，选择最适合您项目中代码结构的方法。

以内嵌方式加载

若要在 HTML 文件中以内嵌方式加载 Maps JavaScript API，请添加 script 标记，如下所示。

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

动态加载

若要使用单独的 JavaScript 文件以内嵌方式动态加载 Maps JavaScript API，请参阅以下示例。这种方法可让您通过单独的 .js 文件处理要用于 API 的所有代码，相当于以内嵌方式添加脚本标记。

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

动态加载

您可以使用 @googlemaps/js-api-loader 软件包打造更顺畅的动态加载体验。该软件包可通过 NPM 使用以下代码进行安装：

npm install @googlemaps/js-api-loader

该软件包可使用以下代码导入到应用中：

import { Loader } from "@googlemaps/js-api-loader"

该加载器公开了 promise 和回调接口。以下代码演示了如何使用默认的 promise 方法 load()。

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.js

脚本标记属性

请注意，在上面的示例中，我们为 script 标记设置了几个属性（推荐）。以下是每个属性的说明。

src：Maps JavaScript API 的加载网址，包括使用 Maps JavaScript API 所需的所有符号和定义。此示例中的网址包含两个参数：key（您可以在其中提供 API 密钥）和 callback（您可以在其中指定 Maps JavaScript API 完全加载后要调用的全局函数的名称）。详细了解网址参数。
async：要求浏览器异步下载并执行脚本。执行完毕后，脚本会调用使用 callback 参数指定的函数。

库

通过网址加载 Maps JavaScript API 时，您可以选择使用 libraries 网址参数加载其他库。库是指为主要 Maps JavaScript API 提供附加功能的代码模块，但只在您明确请求时才会加载。如需了解详情，请参阅 Maps JavaScript API 中的库。

同步加载 API

在用于加载 Maps JavaScript API 的 script 标记中，可以省略 defer 属性和 callback 参数。这会阻止 API 加载，直到 API 下载完成为止。

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

地图 DOM 元素

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

为了地图能够显示在网页上，我们必须为其预留位置。为此，我们通常会创建一个已命名的 div 元素，然后在浏览器的文档对象模型 (DOM) 中获取对该元素的引用。

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

地图选项

每个地图都有两个必需选项：center 和 zoom。

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 元素）中创建新地图。

问题排查

API 密钥和结算错误

在某些情况下，可能会显示暗色地图或“负”街景图像，并带有“仅用于开发目的”的文字水印。如果出现此行为，通常说明存在 API 密钥或结算方面的问题。为了使用 Google Maps Platform 产品，必须为帐号启用结算功能，并且所有请求都必须包含有效的 API 密钥。以下流程有助于排查此问题：

您有使用 API 密钥吗？

不确定。如何确认我是否使用了 API 密钥？

API 密钥以 key 参数的形式在网址中传递，用于加载 Maps JavaScript API。您可以通过以下几种方法检查您是否使用了 API 密钥：

使用 Google Maps Platform API Checker Chrome 扩展程序。通过这种方法，您可以确定自己的网站是否正确实现了获得许可的 Google Maps API。
如果您使用某个库或插件加载 Maps JavaScript API，请检查该库的设置并查找 API 密钥选项。
检查浏览器中的错误。如果您看到以下消息，则说明您未正确使用 API 密钥：

Google Maps JavaScript API 警告：NoApiKeys
Google Maps JavaScript API 错误：MissingKeyMapError

对于 Web 开发者：

如果您有权访问应用的源代码，请查找用于加载 Maps JavaScript API 的 <script> 代码。加载 Maps JavaScript API 时，请将以下代码中的 YOUR_API_KEY 替换为您的 API 密钥。
```
  <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
  </script>
```
在浏览器中检查您的网站生成的网络流量。在 Chrome 中，可使用开发者工具的网络标签页进行查看。在该标签页中，您会看到您的网站发出的网络请求。使用 Maps JavaScript API 发出的请求将位于路径 maps/api/js 下。在这里，您可以确认请求是否使用了 key 参数。查看网络标签页时，按 maps/api/js 过滤网络流量可能会很有帮助。

不，我没有使用 API 密钥。

如需获取 API 密钥，请点击下面的按钮。如果您没有看到引导式设置，请按照 Google Maps Platform 使用入门中的完整说明操作。
开始使用

是的，我使用了 API 密钥。

太棒了！接下来请确认您的项目是否关联了结算帐号。

您的项目是否关联了结算帐号？

不确定。如何确认我的项目是否关联了结算帐号？

前往 Google Cloud 控制台的“结算”页面，然后选择创建 API 密钥时所用的项目。如要确认密钥是否与该项目相关联，请执行以下操作：

通过点击 Google Maps Platform > 凭据下的左侧边栏，转到凭据部分。
检查您的网站上当前使用的 API 密钥是否列出。如果未列出，请切换为其他项目，然后查看凭据。
如果您找不到与 API 密钥相关联的项目，则可能已无法访问相应项目。请向组织中的其他人寻求帮助。如果找不到原始项目，您应该：
1. 创建新项目。可以通过以下方法完成此操作：从项目列表中选择新建项目，或者在 Resource Manager 页面中选择创建项目。
2. 创建新的 API 密钥。您可以在凭据页面上执行此操作。转到此页面后，点击创建凭据，然后选择 API 密钥。

在 Cloud 控制台中找到您的项目后，转到左侧菜单中的结算部分，查看是否已有关联的结算帐号。

不，我的项目没有关联结算帐号。

前往 Cloud 控制台的“启用结算功能”页面，然后将结算帐号添加到您的项目。如需了解详情，请参阅 Google Maps Platform 使用入门。

是的，我的项目关联了结算帐号。

太棒了！请确保提供的结算方式有效。

提供的结算方式是否已经失效（例如过期的信用卡）？

您可以在 Cloud 控制台中添加、移除或更新付款方式。

API 用量是否超出了您自行设定的每日上限？

如果您为任何 API 设置了每日上限（防止用量意外增加的常见做法），可以通过提高每日上限来解决此问题。

您可以前往 Cloud 控制台的“API 和服务”信息中心，查看每日上限。然后：

根据系统提示选择一个项目。
从列表中选择一个 API，然后点击配额标签页。

您的 API 密钥有 IP 地址限制吗？

具有 IP 地址限制的 API 密钥只能用于适合从服务器端使用的网络服务（例如 Geocoding API 和其他网络服务 API）。大部分此类网络服务在 Maps JavaScript API 中都有等效服务（有关示例，请参阅地理编码服务）。如需使用 Maps JavaScript API 客户端服务，您需要单独创建一个可使用 HTTP 引荐来源网址限制进行保护的 API 密钥（请参阅获取、添加和限制 API 密钥）。

如果您的代码不能正常运行：

为帮助您让地图代码正常运行，Brendan Kenny 和 Mano Marks 在此视频中介绍了一些常见错误及相应解决方法。

查找拼写错误。请注意，JavaScript 语言区分大小写。
检查基础环节 - 一些最常见的问题发生在地图创建的初始阶段。例如：
- 确认您已在地图选项中指定 zoom 和 center 属性。
- 确保您已声明用于容纳出现在屏幕上的地图的 div 元素。
- 确保地图的 div 元素已设置高度。默认情况下，div 元素创建时的高度为 0，因此不可见。
如需了解参考实现，请参阅我们的示例。
使用 JavaScript 调试程序（例如 Chrome 开发者工具中的调试程序）发现问题。首先查看 JavaScript 控制台中是否存在错误。
将问题发布到 Stack Overflow 中。如需了解有关如何发布优质问题的指南，请访问支持页面。