概览

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
选择平台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;

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;

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;
}

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>
查看示例

试用示例

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

  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>(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,
  });
});

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,
  });
});

脚本标记属性

请注意,在上面的示例中,我们为 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> 的高度。

地图选项

每个地图都有两个必需选项: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 元素)中创建新地图。

问题排查

API 密钥和结算错误

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

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

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

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