Aggiungere una mappa di Google con un indicatore utilizzando JavaScript

Introduzione

Questo tutorial mostra come aggiungere una mappa di 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 dei controlli per aggiungere un'etichetta alla mappa.

Di seguito è riportata la mappa che creerai utilizzando questo tutorial. Il segnaposto si trova a Uluru (noto anche come Ayers Rock) nel Parco nazionale Uluru-Kata Tjuta.

Per iniziare

Per creare una mappa di Google con un indicatore sulla tua pagina web, segui questi tre passaggi:

  1. Recuperare una chiave API
  2. Creare una pagina HTML
  3. Aggiungere una mappa con un indicatore

Hai bisogno di 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:

  1. Vai alla console Google Cloud.

  2. Crea o seleziona un progetto.

  3. Fai clic su Continua per abilitare l'API e tutti i servizi correlati.

  4. Nella pagina Credenziali, ottieni una chiave API (e imposta le limitazioni della chiave API). Nota: se hai una chiave API esistente senza restrizioni o una chiave con limitazioni del browser, puoi utilizzarla.

  5. Per impedire il furto di quota e proteggere la tua chiave API, consulta la sezione Utilizzo delle chiavi API.

  6. Abilita la fatturazione. Per ulteriori informazioni, consulta la sezione Utilizzo e fatturazione.

  7. Una volta ottenuta una chiave API, aggiungila al seguente snippet facendo clic su "YOUR_API_KEY". Copia e incolla il tag dello 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>

Questa è una pagina HTML molto semplice che utilizza un elemento gmp-map per visualizzare una mappa sulla pagina. La mappa sarà vuota perché non abbiamo ancora aggiunto alcun codice JavaScript.

comprendi il codice

A questo punto dell'esempio, abbiamo:

  • Ha dichiarato l'applicazione come HTML5 utilizzando la dichiarazione !DOCTYPE html.
  • Caricata l'API Maps JavaScript utilizzando il caricatore bootstrap.
  • È stato creato un elemento gmp-map per contenere la mappa.

Dichiarare l'applicazione come HTML5

Ti consigliamo di dichiarare un valore DOCTYPE vero all'interno della tua applicazione web. Negli esempi riportati di seguito, abbiamo dichiarato le nostre applicazioni come HTML5 utilizzando HTML5 DOCTYPE:

<!DOCTYPE html>

I browser più recenti eseguono il rendering dei contenuti dichiarati con questo DOCTYPE in "modalità standard", il che significa che la tua applicazione dovrebbe essere più conforme ai vari browser. Il DOCTYPE è anche progettato per degradarsi gradualmente; i browser che non lo comprendono lo ignorano e utilizzano la "modalità Quirks" per visualizzare i contenuti.

Tieni presente che alcuni CSS che funzionano in modalità quirks non sono validi in modalità standard. Nello specifico, tutte le dimensioni basate sulla percentuale devono essere ereditate dagli elementi di blocco principali e, se uno qualsiasi di questi elementi principali non specifica una dimensione, si presume che le dimensioni siano di 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 bootstrap prepara l'API Maps JavaScript per il caricamento (nessuna libreria viene caricata finché non viene chiamato 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>

Consulta il passaggio 3: ottieni una chiave API per istruzioni su come ottenere la tua 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 alcun codice JavaScript.

Crea un elemento gmp-map

Affinché la mappa venga visualizzata in una pagina web, dobbiamo riservarle uno spazio. In genere, lo facciamo creando un elemento gmp-map e ottenendo un riferimento a questo elemento nel DOM (Document Object Model) del browser. Puoi anche utilizzare un elemento div per farlo (scopri di più), ma è consigliabile utilizzare l'elemento gmp-map.

Il codice seguente 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 precedente, 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 risoluzione molto bassa. Di conseguenza, le immagini delle mappe in Google Maps e nell'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ù alti, i riquadri hanno una risoluzione maggiore 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 mostrano la stessa posizione di Tokyo ai livelli di zoom 0, 7 e 18.

Il codice seguente 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 precedente, l'elemento style imposta le dimensioni di gmp-map. Imposta la larghezza e l'altezza su un valore superiore a 0 px affinché la mappa sia visibile. 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.

Controllo dell'inserimento

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 l'aggiunta di un'etichetta HTML nell'angolo in alto a sinistra della mappa.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Passaggio 3: aggiungi il codice JavaScript

Questa sezione mostra come caricare l'API Maps JavaScript in una pagina web e come scrivere il tuo codice JavaScript che utilizza l'API per aggiungere una mappa con un indicatore.

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();
index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();
index.js

Il codice precedente esegue le seguenti operazioni quando viene chiamato initMap():

  • Carica le librerie maps e marker.
  • Recupera l'elemento mappa dal DOM.
  • Imposta opzioni della mappa aggiuntive sulla mappa interna.
  • Aggiunge un indicatore alla mappa.

Recuperare l'oggetto mappa e impostare le opzioni

innerMap rappresenta un'istanza della classe Map. Per impostare le opzioni della mappa, recupera l'istanza innerMap dall'elemento mappa e chiama setOptions. Il seguente snippet mostra come ottenere l'istanza innerMap dal DOM, quindi chiamare setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Attendi il caricamento della mappa.

Quando utilizzi l'elemento gmp-map, la mappa viene caricata in modo asincrono. Ciò può comportare una condizione di competizione se vengono effettuate altre richieste al momento dell'inizializzazione (ad esempio una richiesta di geolocalizzazione o di dettagli di un luogo). Per assicurarti che il codice venga eseguito solo dopo il caricamento completo della mappa, utilizza un gestore di eventi inattivi addListenerOnce nella funzione di inizializzazione, come mostrato di seguito:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

In questo modo, il codice viene eseguito solo dopo il caricamento della mappa e il gestore viene attivato una sola volta durante il ciclo di vita dell'app.

Codice di esempio completo

Vedi il codice di esempio completo qui:

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();
index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", 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">
      <div id="controls" slot="control-inline-start-block-start">
        <h3>My Google Maps Demo</h3>
      </div>
    </gmp-map>
  </body>
</html>
index.html

Prova campione

Scopri di più sui marcatori:

Suggerimenti e risoluzione dei problemi

  • Scopri di più su come ottenere le coordinate di latitudine/longitudine o convertire un indirizzo in coordinate geografiche.
  • Puoi modificare opzioni come lo stile e le proprietà per personalizzare la mappa. Per ulteriori informazioni sulla personalizzazione delle mappe, leggi le guide sullo stile e sul disegno sulla mappa.
  • Utilizza la console degli strumenti per sviluppatori nel browser web per testare ed eseguire il codice, leggere i report sugli errori e risolvere i problemi relativi al codice.
  • Utilizza le seguenti scorciatoie da tastiera per aprire la console in Chrome:
    Cmd+Opzione+J (su Mac) o Ctrl+Maiusc+J (su Windows).

  • Segui questi passaggi per ottenere le coordinate di latitudine e longitudine di una località su Google Maps.

    1. Apri Google Maps in un browser.
    2. Fai clic con il tasto destro del mouse sulla posizione esatta sulla mappa per cui ti servono le coordinate.
    3. Seleziona Che cosa c'è qui? dal menu contestuale visualizzato. La mappa mostra una scheda nella parte inferiore dello schermo. Trova le coordinate di latitudine e longitudine nell'ultima riga della scheda.

  • Puoi convertire un indirizzo in coordinate di latitudine e longitudine utilizzando il servizio di geocodifica. Le guide per gli sviluppatori forniscono informazioni dettagliate su come iniziare a utilizzare il servizio di geocodifica.