Panoramica

Seleziona piattaforma: Android iOS JavaScript

L'API Maps JavaScript ti consente di personalizzare le mappe con contenuti e immagini personalizzati per la visualizzazione su pagine web e dispositivi mobili. L'API Maps JavaScript offre quattro tipi di mappe di base (roadmap, satellitari, ibride e con rilievi) che puoi modificare utilizzando livelli e stili, controlli ed eventi, oltre a vari servizi e librerie.

Pubblico

Questa documentazione è progettata per le persone che hanno dimestichezza con la programmazione JavaScript e i concetti di programmazione orientati agli oggetti. Dovresti anche conoscere Google Maps dal punto di vista dell'utente. Sul Web sono disponibili molti tutorial su JavaScript.

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

Un saluto da Google, World

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

TypeScript

let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

let map;

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

window.initMap = 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>

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
Visualizza l'esempio

Prova Esempio

Anche in questo semplice esempio, ci sono alcune cose da tenere presenti:

  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 tramite un tag script.

Questi passaggi sono spiegati di seguito.

Dichiarazione dell'applicazione come HTML5

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

<!DOCTYPE html>

La maggior parte dei browser correnti visualizzerà i contenuti dichiarati con questa modalità DOCTYPE in modalità standard; ciò significa che l'applicazione deve essere più compatibile con più browser. Il DOCTYPE è inoltre progettato per ridursi con grazia; i browser che non capiscono lo ignorano e utilizzano la modalità di ricerca per visualizzare i loro contenuti.

Tieni presente che alcuni CSS che funzionano in modalità non valida non sono validi in modalità standard. In particolare, tutte le dimensioni basate sulla percentuale devono ereditare dagli elementi di blocco padre; 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 mappa <div> (con ID map) dovrebbe occupare il 100% dell'altezza del corpo HTML. Tieni presente che dobbiamo dichiarare espressamente queste percentuali per <body> e <html>.

Caricamento dell'API Maps JavaScript

L'API Maps JavaScript viene caricata tramite 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 di 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, vedi 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 equivale a aggiungere il tag dello script incorporato.

// 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 offrire un'esperienza di caricamento dinamica più fluida. Può essere installato tramite NPM con i seguenti vantaggi:

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 di promessa e callback. Di seguito è riportato l'utilizzo del metodo predefinito Promise load().

TypeScript

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

loader.load().then(() => {
  map = new google.maps.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(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

Attributi tag script

Negli esempi riportati sopra, il tag script è consigliato per diversi attributi, che sono consigliati. Di seguito viene fornita una spiegazione di ogni 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 una volta che 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. Quando lo script viene eseguito, chiama la funzione specificata utilizzando il parametro callback.

Librerie

Se carichi l'API Maps JavaScript tramite l'URL, puoi eventualmente caricare altre librerie tramite il parametro URL libraries. Le librerie sono moduli di codice che forniscono funzionalità aggiuntive all'API Maps JavaScript principale, ma non vengono caricati, a meno che tu non li richieda specificamente. Per scoprire di più, consulta le librerie nell'API Maps JavaScript.

Caricamento sincrono dell'API

Nel tag script che carica l'API Maps JavaScript, è possibile omettere l'attributo defer e il parametro callback. Il caricamento dell'API verrà bloccato fino al download dell'API stessa.

Questo potrebbe rallentare il caricamento della pagina. Ciò significa, tuttavia, che puoi scrivere tag script successivi supponendo che l'API sia già stata caricata.

Elementi DOM della mappa

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

Per visualizzare la mappa in una pagina web, dobbiamo prenotare un posto. In genere, questa operazione viene creata creando un elemento div denominato e ottenendo un riferimento a questo elemento nel modello dell'oggetto documento (DOM) del browser.

Nell'esempio precedente, abbiamo utilizzato CSS per impostare l'altezza del div mappa su "100%". che si espanderà per adattarsi alle dimensioni sui 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 di solito i div prendono la larghezza dall'elemento che li contiene e che i div vuoti di solito hanno un'altezza pari a 0. Per questo motivo, devi sempre impostare un'altezza su <div> in modo esplicito.

Opzioni mappa

Per ogni mappa sono disponibili due opzioni obbligatorie: center e zoom.

map = new google.maps.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 completamente ridotta. I livelli di zoom più grandi vengono aumentati a una risoluzione maggiore.

zoom: 8

Per offrire una mappa dell'intera Terra come singola immagine, è necessaria una mappa immensa oppure 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 livelli di piastrelle e livelli di zoom. A livelli di zoom bassi, un piccolo set di riquadri di mappa copre un'ampia area; ai 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 terrestre/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 su come l'API Maps JavaScript carica i riquadri in base al livello di zoom corrente, consulta la guida alla mappatura delle coordinate del riquadro.

L'oggetto mappa

map = new google.maps.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 di mappa, devi specificare un elemento HTML <div> nella pagina come contenitore della mappa. I nodi HTML sono figli 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 relativa 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 i parametri (facoltativi) trasmessi.

Risoluzione dei problemi

Chiave API ed errori di fatturazione

In determinate circostanze potrebbe essere visualizzata una mappa scura o 'nega' di un'immagine di Street View, filigrata dal testo "solo a scopo di sviluppo". Questo comportamento in genere indica problemi con una chiave API o con la fatturazione. Per utilizzare i prodotti Google Maps Platform, la fatturazione deve essere abilitata sul tuo account e tutte le richieste devono includere una chiave API valida. La seguente procedura consente di risolvere il problema:

Se il tuo codice non funziona:

Per aiutarvi a implementare il codice di Maps, Brendan Kenny e Mano Marks evidenziano alcuni errori comuni e come risolverli in questo video.

  • Cerca gli errori ortografici. Ricorda che JavaScript è un linguaggio sensibile alle maiuscole.
  • Verifica le nozioni 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 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.
    Fai riferimento ai nostri esempi per un'implementazione di riferimento.
  • Utilizza un debugger JavaScript per identificare i problemi, come quello disponibile negli strumenti per sviluppatori di Chrome. Per iniziare, cerca gli errori nella console JavaScript.
  • Pubblica domande su Stack Overflow. Le linee guida su come pubblicare domande eccezionali sono disponibili nella pagina Assistenza.