使用 JavaScript 添加带标记的 Google 地图

简介

本教程介绍了如何向网页添加带标记的简单 Google 地图，适用于掌握了 HTML 和 CSS 的初级或中级知识并对 JavaScript 略有了解的人士。

下面便是您将在本教程的指导下创建的地图。标记位于乌鲁鲁卡塔丘塔国家公园中的乌鲁鲁（也称为“艾尔斯岩”）。

入门指南

在网页上创建带标记的 Google 地图需要执行以下三个步骤：

  1. 获取 API 密钥
  2. 创建 HTML 网页
  3. 添加带标记的地图

您需要一个网络浏览器。请根据所用平台从受支持的浏览器列表中选择一个常见的浏览器，例如 Google Chrome（推荐）、Firefox、Safari 或 Edge。

第 1 步：获取 API 密钥

本部分介绍如何使用您的 API 密钥对应用进行身份验证，以便使用 Maps JavaScript API。

请按照下列步骤获取 API 密钥：

  1. 前往 Google Cloud 控制台。

  2. 创建或选择一个项目。

  3. 点击继续，启用 API 和任何相关服务。

  4. 在凭据页面上，获取 API 密钥（并设置 API 密钥限制）。注意：如果您已有不受限的 API 密钥或存在浏览器限制的密钥，可以使用相应密钥。

  5. 如需防止配额盗用并保护 API 密钥，请参阅使用 API 密钥。

  6. 启用结算功能。如需了解详情，请参阅用量和结算。

  7. 获得 API 密钥后，点击“YOUR_API_KEY”将密钥添加到以下代码段中。复制并粘贴引导程序脚本标记，以便在自己的网页上使用。

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

第 2 步：创建 HTML 网页

下方代码可创建一个基本的 HTML 网页：

<!doctype html>
<!--
 @license
 Copyright 2019 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->
<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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>

index.html

请注意，这是一个非常基本的网页，包含一个三级标题 (h3) 和单个 div 元素。您可以随意向该网页添加任何内容。

了解代码

在此示例的此阶段，我们有：

  • 使用 !DOCTYPE html 声明以 HTML5 形式声明应用。
  • 创建了一个名为“map”的 div 元素来存放地图。
  • 使用引导加载程序加载器加载了 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>

创建 div 元素

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

以下代码可为 Google 地图定义一个页面区域。

<!--The div element for the map -->
<div id="map"></div>

在教程的这一阶段，由于您尚未添加地图，因此 div 仅显示为一个灰色块。以下代码描述了用于设置 div 大小和颜色的 CSS。

/* Set the size of the div element that contains the map */
#map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

在以上代码中，style 元素用于设置地图的 div 大小。将 div 的宽度和高度设置为大于 0px 的值，才能让地图显示出来。在本例中，div 的高度设置为 400 像素，宽度设置为 100%，以与网页同宽显示。请注意，div 通常会从其所含元素中获取宽度值，并且空 div 的高度通常为 0。因此，您必须始终明确设置 div 的高度。

加载 Maps JavaScript API

引导程序加载器会准备 Maps JavaScript API 以进行加载（在调用 importLibrary() 之前不会加载任何库）。

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

如需了解如何获取自己的 API 密钥，请参阅第 3 步：获取 API 密钥。

第 3 步：添加带标记的地图

本部分介绍如何将 Maps JavaScript API 加载到您的网页中，以及如何自行编写 JavaScript，以利用 API 添加带标记的地图。

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

在以上代码中，调用 initMap() 函数时会加载 Map 和 AdvancedMarkerElement 库。

了解代码

在本教程的这一阶段，我们有：

  • 定义了一个在 div 中创建地图的 JavaScript 函数。
  • 创建了 AdvancedMarkerElement 以向地图添加标记。

添加地图

以下代码会构造一个新的 Google 地图对象，并向该地图添加中心和缩放级别等属性。请参阅相关文档，了解其他属性选项。

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);
index.ts

JavaScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});

index.js

每个地图都有两个必需选项：center 和 zoom。在以上代码中，new Map() 会创建一个新的 Google 地图对象。center 属性用于向 API 指示地图的中心位置。

zoom 属性用于指定地图的缩放级别。0 是最低缩放级别，会显示整个地球。调高缩放级别值，就能以更高的分辨率放大地球。

以单幅图像形式提供整个地球的地图需要巨幅尺寸的地图，或者分辨率极低的小幅地图。因此，Google 地图和 Maps JavaScript API 中的地图图片被分解成了地图“图块”和“缩放级别”。在较低的缩放级别，一小部分地图图块便可涵盖大片区域；在较高的缩放级别，图块分辨率更高，涵盖的区域较小。下面的列表显示了您在每个缩放级别看到的地图的大致详细程度：

  • 1：世界
  • 5：大陆或洲
  • 10：城市
  • 15：街道
  • 20：建筑物

以下三幅图像反映了东京同一位置在缩放级别为 0、7 和 18 时的情况。

添加标记

以下代码会在地图上放置标记。position 属性用于设置标记的位置。

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});
index.ts

JavaScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});
index.js

完整示例代码

在此处查看完整的示例代码：

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

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>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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>
index.html

试用示例

详细了解标记：

提示和问题排查

  • 详细了解如何获取纬度/经度坐标，或将地址转换为地理坐标。
  • 您可以通过调整样式和属性等选项来自定义地图。如需详细了解如何自定义地图，请参阅有关样式设置和在地图上绘制的指南。
  • 在网络浏览器中使用开发者工具控制台来测试和运行代码、阅读错误报告并解决代码存在的问题。
  • 使用以下键盘快捷键在 Chrome 中打开控制台：
    Command+Option+J（在 Mac 上）或 Ctrl+Shift+J（在 Windows 上）。

  • 按照以下步骤操作，获取 Google 地图上某个位置的纬度和经度坐标。

    1. 在浏览器中打开 Google 地图。
    2. 在地图上右键点击需要坐标的确切位置。
    3. 从显示的上下文菜单中选择这儿有什么？。地图会在屏幕底部显示一张卡片。在卡片的最后一行找到纬度和经度坐标。

  • 您可以使用地理编码服务将地址转换为纬度和经度坐标。开发者指南详细介绍了如何开始使用地理编码服务。