概览

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
选择平台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)应占据 HTML 正文的 100% 高度。请注意,我们还必须明确声明 <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> 上明确设置高度。

地图选项

每个地图都有两个必需选项: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 上。有关如何发布优质问题的指南,请参阅支持页面。