Introduzione
Questo tutorial mostra come aggiungere una mappa Google con un indicatore a una pagina web utilizzando HTML, CSS e JavaScript. Mostra anche come impostare le opzioni della mappa e come utilizzare l'inserimento di controlli per aggiungere un'etichetta alla mappa.
Di seguito è riportata la mappa che creerai utilizzando questo tutorial. L'indicatore è posizionato a Uluru (noto anche come Ayers Rock) nel Parco nazionale Uluru-Kata Tjuta.
Per iniziare
Per creare una mappa Google con un indicatore sulla tua pagina web, segui questi tre passaggi:
Ti serve un browser web. Scegli un browser noto come Google Chrome (consigliato), Firefox, Safari o Edge, in base alla tua piattaforma dall' elenco dei browser supportati.
Passaggio 1: ottieni una chiave API
Questa sezione spiega come autenticare la tua app nell'API Maps JavaScript utilizzando la tua chiave API.
Per ottenere una chiave API:
Vai alla console Google Cloud.
Crea o seleziona un progetto.
Fai clic su Continua per attivare l'API e tutti i servizi correlati.
Nella pagina Credenziali, ottieni una chiave API (e imposta le limitazioni della chiave API). Nota: se hai una chiave API esistente senza limitazioni o una chiave con limitazioni del browser, puoi utilizzarla.
Per impedire il furto di quote e proteggere la tua chiave API, consulta Utilizzo delle chiavi API.
Attiva la fatturazione. Per ulteriori informazioni, consulta Utilizzo e fatturazione.
Una volta ottenuta una chiave API, aggiungila al seguente snippet facendo clic su "YOUR_API_KEY". Copia e incolla il tag di script del bootloader da utilizzare nella tua pagina web.
<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>
Passaggio 2: crea una pagina HTML
Ecco il codice per una pagina web HTML di base:
<!DOCTYPE html>
<!--
@license
Copyright 2025 Google LLC. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0
-->
<html>
<head>
<title>Add a Map</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
<!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
</head>
<body>
<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>
</body>
</html>Si tratta di una pagina HTML di base molto semplice che utilizza un
gmp-map elemento per
visualizzare una mappa nella pagina. La mappa sarà vuota perché non abbiamo ancora aggiunto codice JavaScript.
Comprendi il codice
In questa fase dell'esempio, abbiamo:
- Dichiarato l'applicazione come HTML5 utilizzando la dichiarazione
!DOCTYPE html. - Caricato l'API Maps JavaScript utilizzando il caricatore di bootstrap.
- Creato un elemento
gmp-mapper contenere la mappa.
Dichiara l'applicazione come HTML5
Ti consigliamo di dichiarare un DOCTYPE vero all'interno della tua applicazione web.
Negli esempi riportati di seguito, abbiamo dichiarato le nostre applicazioni come HTML5 utilizzando il DOCTYPE HTML5 come mostrato di seguito:
<!DOCTYPE html>
La maggior parte dei browser attuali eseguirà il rendering dei contenuti dichiarati con questo DOCTYPE in "modalità standard", il che significa che la tua applicazione dovrebbe essere più conforme ai browser. Il DOCTYPE è anche progettato per degradare in modo graduale; i browser che non lo comprendono lo ignoreranno e utilizzeranno la "modalità non standard" per visualizzare i contenuti.
Tieni presente che alcuni CSS che funzionano in modalità non standard non sono validi in modalità standard. In particolare, tutte le dimensioni basate su percentuale devono ereditare dagli elementi blocco padre e, se uno di questi antenati non specifica una dimensione, si presume che le dimensioni siano 0 x 0 pixel. Per questo motivo, includiamo la seguente dichiarazione style:
<style>
gmp-map {
height: 100%;
}
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>Carica l'API Maps JavaScript
Il caricatore di bootstrap prepara l'API Maps JavaScript per il caricamento (nessuna libreria viene caricata finché non viene chiamata 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>
Per istruzioni su come ottenere la tua chiave API, consulta il passaggio 3: ottieni una chiave API.
In questa fase del tutorial viene visualizzata una finestra vuota che mostra solo il testo dell'etichetta non formattato. Questo perché non abbiamo ancora aggiunto codice JavaScript.
Crea un elemento gmp-map
Affinché la mappa venga visualizzata in una pagina web, dobbiamo riservare uno spazio per essa. In genere, questa operazione viene eseguita creando un elemento gmp-map e ottenendo un riferimento a questo elemento nel modello a oggetti del documento (DOM) del browser. Puoi anche utilizzare un
div elemento per farlo (scopri di più),
ma ti consigliamo di utilizzare l'elemento gmp-map.
Il codice riportato di seguito definisce l'elemento gmp-map e imposta i parametri center, zoom e map-id.
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID"> </gmp-map>
Le opzioni center e zoom sono sempre obbligatorie. Nel codice riportato sopra, la proprietà center indica all'API dove centrare la mappa, mentre la proprietà zoom specifica il livello di zoom della mappa. Zoom: 0 è lo zoom più basso e mostra l'intera Terra. Imposta un valore di zoom più alto per ingrandire la Terra a risoluzioni più elevate.
Livelli di zoom
Offrire una mappa dell'intera Terra come singola immagine richiederebbe una mappa immensa o una mappa piccola con una bassa risoluzione. Di conseguenza, le immagini delle mappe all'interno di Google Maps e dell'API Maps JavaScript sono suddivise in "riquadri" e "livelli di zoom". A livelli di zoom bassi, un piccolo insieme di riquadri della mappa copre un'area ampia; a livelli di zoom più elevati, i riquadri hanno una risoluzione più alta e coprono un'area più piccola. L'elenco seguente mostra il livello approssimativo di dettaglio previsto per ogni livello di zoom:
- 1: mondo
- 5: massa terrestre o continente
- 10: città
- 15: strade
- 20: edifici
Le tre immagini seguenti riflettono la stessa posizione di Tokyo ai livelli di zoom 0, 7 e 18.
Il codice riportato di seguito descrive il CSS che imposta le dimensioni dell'elemento gmp-map.
/* Set the size of the gmp-map element that contains the map */ gmp-map { height: 400px; /* The height is 400 pixels */ width: 100%; /* The width is the width of the web page */ }
Nel codice riportato sopra, l'elemento style imposta le dimensioni di gmp-map. Imposta la larghezza e l'altezza su un valore maggiore di 0 px per rendere visibile la mappa. In questo caso, gmp-map è impostato su un'altezza di 400 pixel e una larghezza del 100% per essere visualizzato su tutta la larghezza della pagina web. Ti consigliamo di impostare sempre in modo esplicito gli stili di altezza e larghezza.
Inserimento di controlli
Puoi utilizzare l'inserimento di controlli per aggiungere controlli dei moduli HTML alla mappa. Uno
slot è una
posizione predefinita sulla mappa; utilizza l'attributo slot per impostare la
posizione necessaria per un elemento e nidifica gli elementi all'interno dell'elemento gmp-map. Lo snippet seguente mostra come aggiungere un'etichetta HTML nell'angolo in alto a sinistra della mappa.