借助 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> { 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, }); } initMap();
JavaScript
let map; async function initMap() { 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> <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>
试用示例
即便是在这个简单示例中,仍需注意以下一些事项:
- 我们使用
<!DOCTYPE html>
声明,以 HTML5 形式声明应用。 - 我们创建一个名为“map”的
div
元素来保存地图。 - 我们定义一个在
div
中创建地图的 JavaScript 函数。 - 我们使用引导程序加载器来加载 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", v: "weekly", // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.). // Add other bootstrap parameters as needed, using camel case. }); </script>
若要在运行时加载库,请使用 await
运算符从异步函数中调用 importLibrary()
,如下所示:
TypeScript
let map: google.maps.Map; async function initMap(): Promise<void> { 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, }); } initMap();
JavaScript
let map; async function initMap() { 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&loading=async&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>
的高度。
地图选项
每个地图都有两个必需选项:center
和 zoom
。
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 语言区分大小写。
- 检查基础环节,因为一些最常见的问题往往发生在地图创建的初始阶段。例如:
- 确认您已在地图选项中指定
zoom
和center
属性。 - 确保您已声明用于容纳出现在屏幕上的地图的 div 元素。
- 确保地图的 div 元素已设置高度。默认情况下,div 元素创建时的高度为 0,因此不可见。
- 确认您已在地图选项中指定
- 使用 JavaScript 调试程序(例如 Chrome 开发者工具中的调试程序)发现问题。首先查看 JavaScript 控制台中是否存在错误。
- 将问题发布到 Stack Overflow 中。如需了解有关如何发布优质问题的指南,请访问支持页面。