Maps JavaScript API 中的 Web 组件(预览版)

Web 组件是一种常见的 W3C 标准,它将 HTML、CSS 和 JS 封装在可重复使用的自定义 HTML 元素中。这些可重复使用的组件广泛多样,可以是基本的功能模块(如显示地点的星级),也可以是更复杂的业务逻辑。本指南介绍了 Maps JavaScript API 中可用的 Web 组件。

如需详细了解标准本身,请参阅 Web 组件

受众群体

本文档旨在帮助您快速着手了解 Web 组件并利用它开发应用。您需要熟悉 HTML 和 CSS 编程概念。

显示地图

若要开始了解 Web 组件,最简单的方法就是查看示例。以下示例显示了圣何塞地区的地图。

圣何塞地区的地图

HTML

<html>
  <head>
    <title>Simple Map</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="37.4220656,-122.0840897" zoom="10" map-id="DEMO_MAP_ID"></gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

在本示例中,请注意以下事项:

  1. Maps JavaScript API 是异步调用的。回调函数用于了解 API 是何时加载完成的。
  2. 地图的外观风格通过 <gmp-map> 自定义元素进行定义。
  3. 您可以通过在 <gmp-map> 自定义元素中指定属性来定义地图属性。
  4. 样式可内嵌到自定义元素中,也可在单独的 CSS 文件中声明。

设置基本地图的样式

地图 ID 是与特定地图样式或地图项相关联的标识符。若要使用可选的云配置功能,请将云端地图样式设置 DEMO_MAP_ID 替换为您自己的地图 ID。如需了解如何创建地图 ID 和配置自定义样式,请访问云端地图样式设置

向地图添加标记

就像可以通过嵌套内置 HTML 标记来创建复杂的内容层次结构一样,您也可以在元素内部嵌套 <gmp-advanced-marker> 来显示一个或多个地图标记。

包含标记的地图

HTML

<html>
  <head>
    <title>Simple Map with Markers</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
      <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA"></gmp-advanced-marker>
      <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA"></gmp-advanced-marker>
    </gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

在本例中,我们在 <gmp-map> 自定义元素内添加了 2 个 <gmp-advanced-marker> 元素。title 的文本会为指定元素提供额外的悬停文本和无障碍功能标签。

JavaScript 事件

Web 组件的一大优势在于易用性。即使对 JavaScript 或高级编程的了解有限,您也可以通过几行代码显示地图。实施后,代码将遵循其他 HTML 元素的常见模式。例如,您可以使用原生浏览器事件系统来响应地图或高级标记操作,例如标记点击。

标记点击事件

HTML

<html>
<head>
  <title>Google Maps - Marker Click Example</title>
  <link rel="stylesheet" href="style.css" type="text/css">

  <script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
  </script>

  <script>
    function initMap() {
      console.log('Maps JavaScript API loaded.');

      const advancedMarkers = document.querySelectorAll("#marker-click-event-example gmp-advanced-marker");
      for (const advancedMarker of advancedMarkers) {
        customElements.whenDefined(advancedMarker.localName).then(async () => {
          advancedMarker.addEventListener('gmp-click', async () => {
            const {InfoWindow} = await google.maps.importLibrary("maps");
            const infoWindow = new InfoWindow({
              content: advancedMarker.title
            });
            infoWindow.open({
              anchor: advancedMarker
            });
          });
        });
      }
    }
  </script>
</head>
<body>

<gmp-map id="marker-click-event-example" center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
  <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA"></gmp-advanced-marker>
  <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA"></gmp-advanced-marker>
</gmp-map>

</body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

在此示例中,initMap 表示 Maps JavaScript API 加载完成后所需的回调函数。此函数为每个标记设置了监听器,并在用户点击每个标记时显示一个信息窗口。

后续内容

  • 在 Maps JavaScript API 问题跟踪器中请求功能和报告 bug。
  • 探索扩展组件库,查找更高层级的 Web 组件(如地点概览)。