Web 组件是一种常见的 W3C 标准,它将 HTML、CSS 和 JS 封装在可重复使用的自定义 HTML 元素中。这些可重复使用的组件广泛多样,可以是基本的功能模块(如显示地点的星级),也可以是更复杂的业务逻辑。本指南介绍了 Maps JavaScript API 中可用的 Web 组件。
如需详细了解标准本身,请参阅 Web 组件。
受众群体
本文档旨在帮助您快速着手了解 Web 组件并利用它开发应用。您需要熟悉 HTML 和 CSS 编程概念。
显示地图
若要开始了解 Web 组件,最简单的方法就是查看示例。以下示例显示了圣何塞地区的地图。
TypeScript
// This example adds a map using web components. function initMap(): void { console.log('Maps JavaScript API loaded.'); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a map using web components. function initMap() { console.log("Maps JavaScript API loaded."); } 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; } gmp-map { height: 400px; }
HTML
<html> <head> <title>Add a Map Web Component</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> <gmp-map center="37.4220656,-122.0840897" zoom="10" map-id="DEMO_MAP_ID" ></gmp-map> <!-- 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. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=beta" defer ></script> </body> </html>
试用示例
在本示例中,请注意以下事项:
- Maps JavaScript API 是异步调用的。回调函数用于了解 API 是何时加载完成的。
- 地图的外观风格通过
<gmp-map>
自定义元素进行定义。 - 您可以通过在
<gmp-map>
自定义元素中指定属性来定义地图属性。 - 样式可内嵌到自定义元素中,也可在单独的 CSS 文件中声明。
设置基本地图的样式
地图 ID 是与特定地图样式或地图项相关联的标识符。若要使用可选的云配置功能,请将云端地图样式设置 DEMO_MAP_ID
替换为您自己的地图 ID。如需了解如何创建地图 ID 和配置自定义样式,请访问云端地图样式设置。
向地图添加标记
就像可以通过嵌套内置 HTML 标记来创建复杂的内容层次结构一样,您也可以在元素内部嵌套 <gmp-advanced-marker>
来显示一个或多个地图标记。
TypeScript
// This example adds a map with markers, using web components. function initMap(): void { console.log('Maps JavaScript API loaded.'); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a map with markers, using web components. function initMap() { console.log("Maps JavaScript API loaded."); } 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; } gmp-map { height: 400px; }
HTML
<html> <head> <title>Add a Map with Markers using Web Components</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> <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> <!-- 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. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta" defer ></script> </body> </html>
试用示例
在本例中,我们在 <gmp-map>
自定义元素内添加了 2 个 <gmp-advanced-marker>
元素。title
的文本会为指定元素提供额外的悬停文本和无障碍功能标签。
JavaScript 事件
Web 组件的一大优势在于易用性。即使对 JavaScript 或高级编程的了解有限,您也可以通过几行代码显示地图。实施后,代码将遵循其他 HTML 元素的常见模式。例如,您可以使用原生浏览器事件系统来响应地图或高级标记操作,例如标记点击。
TypeScript
// This example adds a map using web components. function initMap(): void { 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 = new google.maps.InfoWindow({ //@ts-ignore content: advancedMarker.title, }); infoWindow.open({ //@ts-ignore anchor: advancedMarker }); }); }); } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a map using web components. 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 = new google.maps.InfoWindow({ //@ts-ignore content: advancedMarker.title, }); infoWindow.open({ //@ts-ignore anchor: advancedMarker, }); }); }); } } 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; } gmp-map { height: 400px; }
HTML
<html> <head> <title>Add a Map Web Component with Events</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> <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> <!-- 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. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta" defer ></script> </body> </html>
试用示例
在此示例中,initMap
表示 Maps JavaScript API 加载完成后所需的回调函数。此函数为每个标记设置了监听器,并在用户点击每个标记时显示一个信息窗口。