I componenti web sono uno standard W3C molto diffuso che incapsula HTML, CSS e JS in elementi HTML personalizzati e riutilizzabili. Questi componenti riutilizzabili possono variare da componenti atomici di funzionalità, come la visualizzazione della valutazione a stelle di un luogo, a logiche di business più complesse. Questa guida descrive i componenti web disponibili nell'API Maps JavaScript.
Per ulteriori informazioni sullo standard, consulta la pagina relativa ai componenti web.
Pubblico
Questa documentazione è progettata per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni con i componenti web. Dovresti conoscere i concetti di programmazione HTML e CSS.
Visualizzazione di una mappa
Il modo più semplice per iniziare a conoscere i componenti web è guardare un esempio. L'esempio seguente mostra una mappa dell'area di San Jose.
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>
Prova Sample
In questo esempio occorre tenere presente quanto segue:
- L'API Maps JavaScript viene chiamata in modo asincrono. La funzione callback è utilizzata per sapere quando l'API è stata caricata.
- La presentazione della mappa è definita con l'elemento personalizzato
<gmp-map>
. - Le proprietà della mappa vengono definite specificando gli attributi nell'elemento personalizzato
<gmp-map>
. - Gli stili possono essere applicati in linea a elementi personalizzati o dichiarati in un file CSS separato.
Applicare uno stile alla mappa base
Un ID mappa è un identificatore associato a uno stile o a una funzionalità specifica. Per sfruttare le funzionalità facoltative di configurazione cloud, sostituisci la definizione delle mappe basata su cloud DEMO_MAP_ID
con il tuo ID mappa.
Per scoprire come creare un ID mappa e configurare uno stile personalizzato, consulta la pagina Personalizzazione delle mappe basata su cloud.
Aggiungi indicatori alla mappa
Così come è possibile nidificare i tag HTML integrati per creare gerarchie di contenuti complesse, è possibile anche nidificare <gmp-advanced-marker>
all'interno di un elemento per visualizzare uno o più indicatori della mappa.
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>
Prova Sample
Qui abbiamo aggiunto due elementi <gmp-advanced-marker>
all'interno dell'elemento personalizzato <gmp-map>
. Il testo per title
fornisce un testo aggiuntivo al passaggio del mouse e un'etichetta di accessibilità per l'elemento specificato.
Eventi JavaScript
Uno dei principali vantaggi di Web components è la facilità d'uso. Con poche righe di codice, è possibile visualizzare una mappa con una conoscenza limitata di JavaScript o della programmazione avanzata. Una volta implementato, il codice segue i pattern familiari di altri elementi HTML. Ad esempio, puoi usare il sistema di eventi nativo del browser per reagire alle azioni sulla mappa o sull'indicatore avanzato, come il clic su un indicatore.
Nel codice HTML, imposta l'attributo gmp-clickable
nell'elemento gmp-advanced-marker
per rendere cliccabile un indicatore. Utilizza advancedMarker.addEventListener
per
gestire gli eventi di clic.
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-clickable ></gmp-advanced-marker> <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA" gmp-clickable ></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>
Prova Sample
In questo esempio, initMap
rappresenta la
funzione di callback obbligatoria
una volta caricata completamente l'API Maps JavaScript. Il codice stabilisce listener per ciascun indicatore e presenta una finestra informativa quando viene fatto clic su ciascun indicatore.
Passaggi successivi
- Richiedi funzionalità e segnala bug nell'Issue Tracker dell'API Maps JavaScript.
- Esplora la libreria dei componenti estesa per componenti web di livello superiore, ad esempio una panoramica dei luoghi.