Panoramica

Seleziona la piattaforma: Android iOS JavaScript

L'API Maps JavaScript consente di personalizzare le mappe con contenuti e immagini personali da visualizzare sulle pagine web e sui dispositivi mobili. L'API Maps JavaScript presenta quattro tipi di mappe di base (mappa stradale, satellite, ibrida e rilievo) che puoi modificare utilizzando livelli e stili, controlli ed eventi, nonché vari servizi e librerie.

Pubblico

Questa documentazione è rivolta alle persone che hanno dimestichezza con la programmazione JavaScript e con i concetti di programmazione orientati agli oggetti. Dovresti anche prendere familiarità con Maps dal punto di vista dell'utente. Sul Web sono disponibili numerosi tutorial su JavaScript.

Questa documentazione concettuale è progettata per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni con l'API Maps JavaScript. Inoltre, pubblichiamo il riferimento API Maps di JavaScript.

Ciao a tutti

Il modo più semplice per iniziare a conoscere l'API Maps JavaScript è un semplice esempio. L'esempio seguente mostra una mappa centrata su Sydney, New South Wales, 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();
index.ts

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();
index.js

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

style.css

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>
index.html
Visualizza esempio

Prova di esempio

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 denominato "map" per contenere la mappa.
  3. Definiamo una funzione JavaScript che crea una mappa in div.
  4. L'API Maps JavaScript viene caricata utilizzando il bootstrap.

Questi passaggi sono spiegati di seguito.

Carica l'API Maps JavaScript

Il bootstrap è il metodo consigliato per caricare l'API Maps JavaScript. In alternativa, viene fornito anche il caricatore dell'API JS. Ti consigliamo di esaminare entrambi gli approcci e scegliere quello più appropriato per il modo in cui è strutturato il codice nel tuo progetto.

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

Loader Bootstrap

Carica l'API Maps JavaScript aggiungendo un bootloader in linea al codice dell'applicazione, come mostrato nel seguente snippet:

<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_HERE",
    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 esecuzione, utilizza l'operatore await per chiamare importLibrary() dall'interno di una funzione asincrona, come mostrato di seguito:

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();
index.ts

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();
index.js

Pacchetto NPM js-api-loader

Utilizza @googlemaps/js-api-loader per utilizzare NPM per caricare l'API Maps JavaScript. Installalo tramite NPM 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 espone 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,
  });
});
index.ts

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

index.js

Dichiarare la tua applicazione come HTML5

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

<!DOCTYPE html>

Nella maggior parte dei browser attualmente visualizzati, i contenuti dichiarati con questo DOCTYPE in "modalità standard" richiedono che la tua applicazione sia più conforme a più browser. L'elemento DOCTYPE è inoltre progettato per eseguire una riduzione controllata; i browser che non lo comprendono ignorano l'impostazione e utilizzano la "modalità scherzi" 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 gli elementi del blocco principale e, se uno di questi antenati non specifica una dimensione, si presume che abbiano dimensioni 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 di mappa <div> (con ID map) deve occupare il 100% dell'altezza del corpo HTML. Tieni presente che dobbiamo dichiarare in modo specifico anche queste percentuali per <body> e <html>.

Caricamento dell'API Maps JavaScript in corso...

L'API Maps JavaScript viene caricata utilizzando un tag script, che può essere aggiunto in linea nel file HTML o dinamicamente utilizzando un file JavaScript separato. Ti consigliamo di esaminare entrambi gli approcci e scegliere quello più appropriato per il modo in cui è strutturato il 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&callback=initMap">
</script>

Caricamento dinamico

Per caricare in modo dinamico l'API Maps JavaScript in linea utilizzando un file JavaScript separato, consulta l'esempio riportato di seguito. Questo approccio ti consente di gestire tutto il codice per lavorare con l'API da un file .js separato ed è l'equivalente dell'aggiunta del 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

Il pacchetto @googlemaps/js-api-loader è disponibile per rendere l'esperienza di caricamento dinamica più fluida. Può essere installato tramite NPM 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 espone 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,
  });
});
index.ts

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

index.js

Attributi dei tag di script

Negli esempi riportati sopra, si noti che sono impostati diversi attributi nel tag script, il che è consigliato. Di seguito è riportata la spiegazione di ciascun attributo.

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

Librerie

Quando carichi l'API Maps JavaScript tramite l'URL, puoi facoltativamente caricare librerie aggiuntive utilizzando l'operatore await per chiamare importLibrary() dall'interno di una funzione asincrona. Le librerie sono moduli di codice che forniscono funzionalità aggiuntive per l'API Maps JavaScript principale, ma non vengono caricate, a meno che tu non le richieda specificatamente. Per ulteriori informazioni, consulta la sezione Librerie nell'API Maps JavaScript.

Mappare gli elementi DOM

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

Per visualizzare la mappa in una pagina web, dobbiamo riservare un posto. Generalmente, per farlo, creiamo un elemento denominato div e otteniamo 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%". Si espanderà in modo da adattarsi alle dimensioni dei dispositivi mobili. Potresti dover 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 che li contiene e quelli vuoti di solito hanno un'altezza pari a 0. Per questo motivo, devi sempre impostare un'altezza sul <div> in modo esplicito.

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 è impostata dalla proprietà zoom, dove lo zoom 0 corrisponde a una mappa della Terra con lo zoom diminuito e i livelli di zoom più grandi aumentano a una risoluzione più elevata.

zoom: 8

Per offrire una mappa dell'intera Terra come singola immagine sarebbe necessaria 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" della mappa. A livelli di zoom più bassi, un piccolo insieme di riquadri di mappa copre un'area ampia; 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 approssimativo di dettaglio previsto per ogni livello di zoom:

  • 1: mondo
  • 5: Terra di massa/continente
  • 10: città
  • 15: Strade
  • 20: Edifici

Le tre immagini seguenti riflettono la stessa località di Tokyo ai 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 coppie di mappa e riquadri.

L'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 sulla pagina). Creiamo una nuova istanza di questa classe utilizzando l'operatore JavaScript new.

Quando crei una nuova istanza di mappa, specifichi un elemento HTML <div> nella pagina come contenitore per la 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 la assegna a un nuovo oggetto Map. La funzione Map() è nota come costruttore e la sua definizione è mostrata 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 eventuali parametri (facoltativi) trasmessi.

Risoluzione dei problemi

Chiave API ed errori di fatturazione

In alcuni casi, potrebbe essere visualizzata una mappa scura o un'immagine di Street View "esclusa", 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, è necessario attivare la fatturazione nel tuo account e tutte le richieste devono includere una chiave API valida. Per risolvere il problema, procedi nel seguente modo:

Se il codice non funziona:

Per aiutarvi a configurare il codice di Maps, Brendan Kenny e Mano Marks indicano alcuni errori comuni e come correggerli in questo video.

  • Cerca gli errori di battitura. Ricorda che JavaScript è un linguaggio sensibile alle maiuscole.
  • Rivedi 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.
    • Assicurati di aver dichiarato un elemento div in cui verrà visualizzata la mappa sullo schermo.
    • Assicurati che l'elemento div della mappa abbia un'altezza. Per impostazione predefinita, gli elementi div vengono creati con un'altezza pari a 0 e, pertanto, sono invisibili.
    Consulta i nostri esempi per informazioni sull'implementazione dei riferimenti.
  • Utilizza un debugger JavaScript per identificare i problemi, come quello disponibile in Chrome Developer Tools. Inizia cercando gli errori nella console JavaScript.
  • Pubblica domande su Stack Overflow. Le linee guida su come pubblicare domande eccezionali sono disponibili nella pagina dell'assistenza.