L'API Maps JavaScript consente di personalizzare le mappe con contenuti e immagini personalizzati per la visualizzazione su pagine web e 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 è progettata per coloro che hanno familiarità con la programmazione di JavaScript e i concetti di programmazione orientati agli oggetti. Dovresti anche conoscere Maps dal punto di vista dell'utente. Esistono molti tutorial su JavaScript disponibili sul Web.
Questa documentazione concettuale è progettata per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni con l'API Maps JavaScript. Inoltre, pubblichiamo il riferimento dell'API Maps JavaScript.
Un saluto da Google
Il modo più semplice per iniziare a conoscere l'API Maps JavaScript è un semplice esempio. L'esempio riportato di seguito mostra una mappa centrata su Sydney, New South Wales, Australia.TypeScript
let map: google.maps.Map;
async function initMap(): Promise<void> {
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
map = new Map(document.getElementById("map") as HTMLElement, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
}
initMap();
JavaScript
let map;
async function initMap() {
//@ts-ignore
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>
Prova anteprima
Anche in questo semplice esempio ci sono alcuni aspetti da considerare:
- Dichiariamo l'applicazione come HTML5 utilizzando la dichiarazione
<!DOCTYPE html>. - Creiamo un elemento
divdenominato "map" per mantenere la mappa. - Definiamo una funzione JavaScript che crea una mappa in
div. - 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.
Caricatore 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",
// Add other bootstrap parameters as needed, using camel case.
// Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
});
</script>
Per caricare le librerie in esecuzione, usa 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> {
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
map = new Map(document.getElementById("map") as HTMLElement, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
}
initMap();
JavaScript
let map;
async function initMap() {
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
map = new Map(document.getElementById("map"), {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
}
initMap();
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
Il 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,
});
});
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,
});
});
Dichiarare l'applicazione come HTML5
Ti consigliamo di dichiarare un valore DOCTYPE reale all'interno della tua applicazione web. Negli esempi qui riportati, abbiamo dichiarato le nostre applicazioni come HTML5 utilizzando il semplice codice HTML5 DOCTYPE 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 al browser. DOCTYPE è anche progettato per eseguire la riduzione controllata; i browser che non lo capiscono lo ignorano e utilizzano la "modalità non standard" per visualizzare i loro contenuti.
Tieni presente che alcuni CSS supportati in modalità non standard non sono validi in modalità standard. In particolare, tutte le dimensioni basate sulla percentuale devono ereditare dagli elementi a blocchi principali 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 container
<div>
(con ID map) deve occupare il 100% dell'altezza del corpo
HTML. Tieni presente che dobbiamo dichiarare espressamente queste percentuali anche per
<body> e <html>.
Caricamento dell'API Maps JavaScript in corso...
L'API Maps JavaScript viene caricata utilizzando un tagscript, 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 e 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
Il pacchetto @googlemaps/js-api-loader è disponibile per rendere più fluida l'esperienza di caricamento dinamico. Può essere installato tramite NPM con i seguenti elementi:
npm install @googlemaps/js-api-loader
Il 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,
});
});
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 tag script
Negli esempi precedenti, diversi attributi sono impostati nel tag script, il che è consigliato. 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 utilizzare l'API Maps JavaScript. L'URL in questo esempio ha due parametri:key, in cui fornisci la chiave API, ecallback, in cui specifichi il nome di una funzione globale da chiamare una volta caricata l'API Maps JavaScript. Scopri di più sui parametri URL.async: chiede al browser di scaricare ed eseguire lo script in modo asincrono. Quando lo script viene eseguito, chiama la funzione specificata utilizzando il parametrocallback.
Librerie
Quando carichi l'API Maps JavaScript tramite l'URL, puoi facoltativamente
caricare librerie aggiuntive utilizzando l'operatore await per chiamare importLibrary()
da una funzione asincrona. Le librerie sono moduli di codice che
forniscono funzionalità aggiuntive per l'API Maps JavaScript principale, ma che non vengono
caricati a meno che non sia espressamente richiesto. Per saperne di più, consulta
Librerie nell'API Maps JavaScript.
Elementi DOM mappa
<div id="map"></div>
Per visualizzare la mappa in una pagina web, dobbiamo prenotare un posto.
A questo scopo, in genere creiamo un elemento div denominato 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 mappa su "100%". che si espanderà in modo da adattarsi alle dimensioni dei 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 dal loro elemento contenitore, mentre i div vuoti in genere hanno un'altezza pari a 0. Per questo motivo, devi sempre impostare un'altezza in modo esplicito per <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 con cui visualizzare la mappa è impostata dalla proprietà zoom, dove lo zoom 0 corrisponde a una mappa della Terra completamente rimpicciolita e i livelli di zoom più grandi aumentano a una risoluzione maggiore.
zoom: 8
L'offerta di una mappa dell'intera Terra come immagine singola richiede 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 " piastrelle" e "livelli di zoom" della mappa. A livelli di zoom bassi, un piccolo insieme di riquadri di mappa copre un'area ampia; a livelli di zoom più alti, i riquadri hanno una risoluzione maggiore e coprono un'area più piccola. Il seguente elenco mostra il livello approssimativo di dettaglio previsto per ogni livello di zoom:
- 1: Mondo
- 5: massa continentale/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.
Per informazioni sul modo in cui l'API Maps JavaScript carica i riquadri in base al livello di zoom corrente, consulta la mappatura delle coordinate e dei 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 in 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 di mappa, devi specificare 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 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 container HTML specificato, che in genere è un elemento DIV, utilizzando i parametri (facoltativi) trasmessi. |
Risoluzione dei problemi
Errori di fatturazione di chiavi API e fatturazione
In alcuni casi potrebbe essere visualizzata una mappa scura o un'immagine di Street View "negativa", filigranata con il testo "solo a scopo di sviluppo". Questo comportamento in genere indica i problemi relativi a una chiave API o alla fatturazione. Per utilizzare i prodotti Google Maps Platform, la fatturazione deve essere abilitata 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:
Per aiutarvi a iniziare con il codice delle mappe, Brendan Kenny e Mano Marks sottolineano alcuni errori comuni e come risolverli in questo video.
- Cerca gli errori di battitura. Ricorda che JavaScript è un linguaggio sensibile alle maiuscole.
- Controlla le nozioni di base: alcuni dei problemi più comuni si verificano con la
creazione iniziale della mappa. Ad esempio:
- Verifica di aver specificato le proprietà
zoomecenternelle opzioni della mappa. - Assicurati di aver dichiarato un elemento div in cui la mappa verrà visualizzata 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.
- Verifica di aver specificato le proprietà
- 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 Assistenza.