Panoramica

Seleziona la piattaforma: Android iOS JavaScript

L'API Maps JavaScript ti consente di personalizzare le mappe con i tuoi contenuti e immagini per la visualizzazione su pagine web e dispositivi mobili. L'API Maps JavaScript presenta quattro tipi di mappe di base (mappa stradale, satellitare, ibrida e del rilievo) che puoi modificare utilizzando livelli e stili, controlli ed eventi e vari servizi e librerie.

Pubblico

Questa documentazione è destinata a persone che hanno familiarità con la programmazione JavaScript e i concetti di programmazione orientata agli oggetti. Dovresti anche acquisire familiarità con Maps dal punto di vista dell'utente. Sul web sono disponibili molti tutorial JavaScript.

Questa documentazione concettuale è progettata per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni con l'API Maps JavaScript. Pubblichiamo inoltre la documentazione di riferimento sull'API JavaScript di Google Maps.

Ciao mondo

Il modo più semplice per iniziare a conoscere l'API Maps JavaScript è visualizzare un semplice esempio. L'esempio seguente mostra una mappa centrata su Sydney, Nuovo Galles del Sud, Australia.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

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;
}

HTML

<html>
  <head>
    <title>Simple Map</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>
    <div id="map"></div>

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
Visualizza esempio

Prova Samples

Anche in questo semplice esempio, ci sono alcuni aspetti da considerare:

  1. Dichiariamo l'applicazione come HTML5 utilizzando la dichiarazione <!DOCTYPE html>.
  2. Creiamo un elemento div chiamato "map" per contenere la mappa.
  3. Definiamo una funzione JavaScript che crea una mappa in div.
  4. Carichiamo l'API Maps JavaScript utilizzando il bootstraploader.

Questi passaggi sono spiegati di seguito.

Carica l'API Maps JavaScript

Il metodo consigliato per caricare l'API Maps JavaScript è il bootloader. In alternativa, viene fornito anche il caricatore API JS. Ti consigliamo di esaminare entrambi gli approcci e di scegliere quello più appropriato per la struttura del codice nel tuo progetto.

Per maggiori dettagli, consulta Caricare l'API Maps JavaScript.

Bootstrap

Carica l'API Maps JavaScript aggiungendo un bootstrap incorporato al codice dell'applicazione, come mostrato nello snippet seguente:

<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 caricare le librerie in fase di runtime, utilizza l'operatore await per chiamare importLibrary() dall'interno di una funzione asincrona, come mostrato qui:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

Pacchetto js-api-loader di NPM

Utilizza @googlemaps/js-api-loader per utilizzare Gestione dei partner di rete al fine di caricare l'API Maps JavaScript. Installalo tramite Gestione dei partner di rete utilizzando il seguente comando:

npm install @googlemaps/js-api-loader

Questo pacchetto può essere importato nell'applicazione con:

import { Loader } from "@googlemaps/js-api-loader"

Il caricatore mostra un'interfaccia Promise e callback. Di seguito viene illustrato l'utilizzo del metodo Promise predefinito load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

Dichiara la tua applicazione come HTML5

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

<!DOCTYPE html>

La maggior parte dei browser attuali mostrerà i contenuti dichiarati con questo DOCTYPE in "modalità standard", il che significa che la tua applicazione dovrebbe essere più conforme a più browser. DOCTYPE è inoltre progettato per ridurre le prestazioni in modo controllato; i browser che non lo comprendono lo ignorano e utilizzano la "modalità non standard" per visualizzare i relativi contenuti.

Tieni presente che alcuni CSS che funzionano all'interno della modalità non standard non sono validi in modalità standard. In particolare, tutte le dimensioni basate sulla percentuale devono ereditare dagli elementi di blocco padre e, se uno qualsiasi di questi predecessori non specifica una dimensione, si presume che le sue dimensioni siano pari a 0 x 0 pixel. Per questo motivo, includiamo la seguente dichiarazione <style>:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Questa dichiarazione CSS indica che il contenitore della mappa <div> (con ID map) deve occupare il 100% dell'altezza del corpo HTML. Tieni presente che dobbiamo dichiarare specificamente queste percentuali anche per <body> e <html>.

Caricamento dell'API Maps JavaScript

L'API Maps JavaScript viene caricata utilizzando un tag script, che può essere aggiunto incorporato nel file HTML oppure dinamicamente utilizzando un file JavaScript separato. Ti consigliamo di esaminare entrambi gli approcci e di scegliere quello più appropriato per la struttura del codice nel tuo progetto.

Caricamento in linea

Per caricare l'API Maps JavaScript in linea in un file HTML, aggiungi un tag script come mostrato di seguito.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Caricamento dinamico

Per caricare dinamicamente l'API Maps JavaScript in linea utilizzando un file JavaScript separato, vedi l'esempio riportato di seguito. Questo approccio consente di gestire tutto il codice per lavorare con l'API da un file .js separato ed equivale ad aggiungere il tag script in linea.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

Caricamento dinamico

Per semplificare l'esperienza di caricamento dinamico, è disponibile il pacchetto @googlemaps/js-api-loader. Può essere installata tramite Gestione dei partner di rete con quanto segue:

npm install @googlemaps/js-api-loader

Questo pacchetto può essere importato nell'applicazione con:

import { Loader } from "@googlemaps/js-api-loader"

Il caricatore mostra un'interfaccia Promise e callback. Di seguito viene illustrato l'utilizzo del metodo Promise predefinito load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

Attributi del tag script

Negli esempi riportati sopra, puoi notare che nel tag script sono impostati diversi attributi (opzione consigliata). Di seguito è riportata una spiegazione di ciascun attributo.

  • src: l'URL da cui viene caricata l'API Maps JavaScript, inclusi tutti i simboli e le definizioni necessari per l'utilizzo dell'API Maps JavaScript. L'URL in questo esempio ha due parametri: key, dove fornisci la tua chiave API, e callback, dove specifichi il nome di una funzione globale da chiamare dopo il caricamento completo dell'API Maps JavaScript. Scopri di più sui parametri URL.
  • async: chiede al browser di scaricare ed eseguire lo script in modo asincrono. Quando viene eseguito, lo script chiama la funzione specificata utilizzando il parametro callback.

Librerie

Durante il caricamento dell'API Maps JavaScript tramite l'URL, puoi facoltativamente caricare ulteriori librerie utilizzando l'operatore await per chiamare importLibrary() dall'interno di una funzione asincrona. Le librerie sono moduli di codice che forniscono funzionalità aggiuntive all'API Maps JavaScript principale, ma non vengono caricati a meno che non vengano richiesti specificamente. Per ulteriori informazioni, consulta la pagina Librerie nell'API Maps JavaScript.

Mappa elementi DOM

<div id="map"></div>

Affinché la mappa venga visualizzata su una pagina web, dobbiamo prenotare un posto. In genere, ciò avviene creando un elemento div denominato e ottenendo un riferimento a questo elemento nel DOM (Document Object Model) del browser.

Nell'esempio precedente, abbiamo utilizzato CSS per impostare l'altezza del div della mappa su "100%". L'annuncio si espanderà per adattarsi alle dimensioni sui dispositivi mobili. Potrebbe essere necessario regolare i valori di larghezza e altezza in base alle dimensioni dello schermo e alla spaziatura interna del browser. Tieni presente che in genere i div prendono la larghezza dall'elemento contenitore, mentre i div vuoti di solito hanno un'altezza pari a 0. Per questo motivo, devi sempre impostare esplicitamente un'altezza sul <div>.

Opzioni mappa

Esistono due opzioni obbligatorie per ogni mappa: center e zoom.

map = new Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

Livelli di zoom

La risoluzione iniziale alla quale visualizzare la mappa viene impostata dalla proprietà zoom, dove lo zoom 0 corrisponde a una mappa della Terra completamente ridotta, mentre livelli di zoom più grandi aumentano lo zoom a una risoluzione maggiore.

zoom: 8

Per offrire una mappa dell'intera Terra come singola immagine sarebbe necessaria una mappa immensa o una mappa di piccole dimensioni con risoluzione molto bassa. Di conseguenza, le immagini delle mappe in Google Maps e nell'API Maps JavaScript vengono suddivise in "riquadri" e "livelli di zoom" delle mappe. 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 maggiore e coprono un'area più piccola. Il seguente elenco mostra il livello approssimativo di dettaglio che puoi aspettarti di vedere a ogni livello di zoom:

  • 1: Mondo
  • 5: massa continentale/continente
  • 10: Città
  • 15: strade
  • 20: edifici

Le tre immagini seguenti riflettono la stessa località di Tokyo a livelli di zoom 0, 7 e 18.

Per informazioni su come l'API Maps JavaScript carica i riquadri in base al livello di zoom corrente, consulta la guida alle coordinate di mappe e riquadri.

Oggetto mappa

map = new Map(document.getElementById("map"), {...});

La classe JavaScript che rappresenta una mappa è la classe Map. Gli oggetti di questa classe definiscono una singola mappa su una pagina. Puoi creare più di un'istanza di questa classe, ogni oggetto definisce una mappa separata nella pagina. Creiamo una nuova istanza di questa classe utilizzando l'operatore JavaScript new.

Quando crei una nuova istanza della mappa, specifichi un elemento HTML <div> nella pagina come contenitore della mappa. I nodi HTML sono elementi secondari dell'oggetto JavaScript document e otteniamo un riferimento a questo elemento tramite il metodo document.getElementById().

Questo codice definisce una variabile (denominata map) e assegna questa variabile a un nuovo oggetto Map. La funzione Map() è nota come costruttore e la sua definizione è riportata di seguito:

Costruttore Descrizione
Map(mapDiv:Node, opts?:MapOptions ) Crea una nuova mappa all'interno del contenitore HTML specificato, che in genere è un elemento DIV, utilizzando i parametri (facoltativi) trasmessi.

Risolvere i problemi

Errori di fatturazione e chiave API

In alcuni casi, potrebbe essere visualizzata una mappa scura o un'immagine di Street View "negativa", a cui è stata applicata la filigrana con il testo "solo a scopo di sviluppo". Questo comportamento indica in genere problemi con una chiave API o con la fatturazione. Per utilizzare i prodotti Google Maps Platform, la fatturazione deve essere attivata nel tuo account e tutte le richieste devono includere una chiave API valida. Per risolvere il problema, segui la procedura riportata di seguito:

Se il codice non funziona:

In questo video, Brendan Kenny e Mano Marks indicano alcuni errori comuni e come correggerli.

  • Controlla che non ci siano errori di battitura. Ricorda che JavaScript è un linguaggio che fa distinzione tra maiuscole e minuscole.
  • Controlla le informazioni di base: alcuni dei problemi più comuni si verificano con la creazione iniziale della mappa. Ad esempio:
    • Conferma di aver specificato le proprietà zoom e center nelle opzioni della mappa.
    • Verifica di aver dichiarato un elemento div in cui verrà visualizzata la mappa sullo schermo.
    • Verifica che l'elemento div per la mappa abbia un'altezza. Per impostazione predefinita, gli elementi div vengono creati con un'altezza pari a 0 e, pertanto, sono invisibili.
    Fai riferimento ai nostri esempi per l'implementazione di riferimento.
  • Utilizza un debugger JavaScript per identificare i problemi, come quello disponibile negli Strumenti per sviluppatori di Chrome. Inizia cercando di individuare eventuali errori nella console JavaScript.
  • Pubblica domande su Stack Overflow. Le linee guida su come pubblicare domande efficaci sono disponibili nella pagina Assistenza.