Aggiungere una mappa di Google con un indicatore utilizzando JavaScript

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 lo slotting dei controlli per aggiungere un'etichetta alla mappa.

Di seguito è riportata la mappa che creerai utilizzando questo tutorial. L'indicatore è posizionato su 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, devi seguire tre passaggi:

1. Ottieni una chiave API
2. Crea una pagina HTML
3. Aggiungi una mappa con un indicatore

È necessario un browser web. Scegline uno 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, segui questi passaggi:

1. Vai alla console Google Cloud.

2. Crea o seleziona un progetto.

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

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

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

6. Abilita la fatturazione. Per saperne di più, consulta Utilizzo e fatturazione.

7. Una volta ottenuta una chiave API, aggiungila allo snippet seguente 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

Di seguito è riportato 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 di base 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

In questa fase dell'esempio, abbiamo:

• Dichiarato l'applicazione come HTML5 utilizzando la dichiarazione !DOCTYPE html.
• Caricamento dell'API Maps JavaScript utilizzando il boot loader.
• Creato un elemento gmp-map per contenere la mappa.

Dichiara la tua 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 visualizza i contenuti dichiarati con questo DOCTYPE in "modalità standard", il che significa che la tua applicazione dovrebbe essere più compatibile con i vari browser. DOCTYPE è inoltre progettato per un degrado controllato; 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 percentuali devono ereditare dagli elementi del blocco principale e, se uno di questi predecessori 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 boot loader prepara l'API Maps JavaScript per il caricamento (non viene caricata nessuna libreria 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

Per visualizzare la mappa su una pagina web, dobbiamo riservarle uno spazio. In genere, lo facciamo creando un elemento gmp-map e ottenendo un riferimento a questo elemento nel Document Object Model (DOM) del browser. A questo scopo, puoi anche utilizzare un elemento div (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 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'intero pianeta Terra. Imposta un valore di zoom più alto per aumentare lo zoom sulla Terra a risoluzioni più elevate.

Livelli di zoom

Offrire una mappa dell'intera Terra come singola immagine richiederebbe una mappa enorme o una mappa piccola con una risoluzione molto bassa. Di conseguenza, le immagini delle mappe all'interno di Google Maps e dell'API Maps JavaScript sono suddivise in "tile" e "livelli di zoom". A livelli di zoom bassi, un piccolo insieme di riquadri della mappa copre un'ampia area; a livelli di zoom più elevati, i riquadri hanno una risoluzione più alta e coprono un'area più piccola. Il seguente elenco mostra il livello di dettaglio approssimativo che puoi aspettarti di vedere a ogni livello di zoom:

• 1: Dal mondo
• 5: massa continentale o continente
• 10: Città
• 15: Strade
• 20: Edifici

Le tre immagini seguenti mostrano la stessa località 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 superiore a 0 px per rendere visibile la mappa. In questo caso, l'elemento 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.

Nota: per le mappe raster, il limite per la dimensione massima è 6144 x 6144 pixel.

Slotting dei controlli

Puoi utilizzare l'inserimento dei 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 init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

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

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

Recupera l'oggetto mappa e imposta 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 recuperare l'istanza innerMap dal DOM e poi 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 race condition se vengono effettuate altre richieste al momento dell'inizializzazione (ad esempio, una richiesta di geolocalizzazione o di Place Details). Per assicurarti che il codice venga eseguito solo dopo il caricamento completo della mappa, utilizza un gestore di eventi addListenerOnce inattivo nella funzione di inizializzazione, come mostrato qui:

// 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; il gestore viene attivato una sola volta durante il ciclo di vita dell'app.

Nota sull'ottimizzazione delle prestazioni interne:

Per migliorare la velocità di caricamento delle pagine, l'API Maps JavaScript potrebbe posticipare internamente il caricamento dei contenuti interattivi finché l'elemento o il contenitore non si avvicina all'area visibile. Queste ottimizzazioni interne sono soggette a modifiche in qualsiasi momento, senza preavviso. Sono progettati come un miglioramento delle prestazioni e non devono essere utilizzati come meccanismo per la gestione della fatturazione. Per assicurarti che la fatturazione non venga addebitata finché un elemento non è visibile, rimanda la sua creazione nel codice dell'applicazione.

Codice di esempio completo

Visualizza il codice di esempio completo qui:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
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>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </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

Scopri di più sugli indicatori:

• Rendi accessibile un indicatore
• Indicatori con icone grafiche
• Animazioni degli indicatori

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, consulta le guide sullo stile e sul disegno sulla mappa.
• Utilizza la console 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:
  Comando+Opzione+J (su Mac) o Ctrl+Maiusc+J (su Windows).

• 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 le coordinate di latitudine e longitudine dal menu.

• 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 Geocoding.