概览

请选择平台: 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;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

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>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
查看示例

试用示例

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

  1. 我们使用 <!DOCTYPE html> 声明,以 HTML5 形式声明应用。
  2. 我们创建一个名为“map”的 div 元素来保存地图。
  3. 我们定义一个在 div 中创建地图的 JavaScript 函数。
  4. 我们使用引导程序加载器来加载 Maps JavaScript API。

下文介绍了这些步骤。

加载 Maps JavaScript API

建议使用引导程序加载器来加载 Maps JavaScript API。我们还提供了 JS API 加载器作为替代方案。建议您同时查看这两种方法,选择最适合您项目中代码结构的方法。

如需了解详情,请参阅加载 Maps JavaScript API

引导程序加载器

将内嵌引导程序加载器添加到应用代码中,即可加载 Maps JavaScript API,如以下代码段所示:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

若要在运行时加载库,请使用 await 运算符从异步函数中调用 importLibrary(),如下所示:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

NPM js-api-loader 软件包

使用 @googlemaps/js-api-loader 通过 NPM 加载 Maps JavaScript API。使用以下命令通过 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

以 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new 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 时,您可以选择使用 await 运算符从异步函数内调用 importLibrary(),从而加载其他。库是指为主要 Maps JavaScript API 提供附加功能的代码模块,但只在您明确请求时才会加载。如需了解详情,请参阅 Maps JavaScript API 中的库

地图 DOM 元素

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

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

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

地图选项

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

map = new 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 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 中。如需了解有关如何发布优质问题的指南,请访问支持页面。