Upgrade dell'applicazione API Maps JavaScript da V2 a V3

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

La versione 2 dell'API Maps JavaScript non è più disponibile dal 26 maggio 2021. Di conseguenza, le mappe v2 del tuo sito smetteranno di funzionare e restituiranno errori JavaScript. Per continuare a utilizzare Maps sul tuo sito, esegui la migrazione all'API Maps JavaScript v3. Questa guida ti aiuterà durante la procedura.

Panoramica

Ogni applicazione avrà un processo di migrazione leggermente diverso; tuttavia, esistono alcuni passaggi comuni a tutti i progetti:

  1. Procurati una nuova chiave. L'API Maps JavaScript ora utilizza Google Cloud Console per gestire le chiavi. Se continui a utilizzare una chiave v2, assicurati di recuperare la nuova chiave API prima di iniziare la migrazione.
  2. Aggiorna il bootstrap dell'API. La maggior parte delle applicazioni caricherà l'API Maps JavaScript v3 con il seguente codice:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. Aggiorna il codice. La quantità di modifica richiesta dipenderà molto dalla tua applicazione. Le modifiche più comuni includono:
    • Fai sempre riferimento allo spazio dei nomi google.maps. Nella versione v3, tutto il codice dell'API Maps JavaScript viene archiviato nello spazio dei nomi google.maps.* anziché nello spazio dei nomi globale. La maggior parte degli oggetti è stata rinominata nell'ambito di questo processo. Ad esempio, invece di GMap2, caricherai google.maps.Map.
    • Rimuovi eventuali riferimenti a metodi obsoleti. Sono stati rimossi numerosi metodi di utilità per uso generico, come GDownloadURL e GLog. Sostituisci questa funzionalità con librerie di utilità di terze parti o rimuovi questi riferimenti dal codice.
    • (Facoltativo) Aggiungi le librerie al codice. Molte funzionalità sono state esterne alle librerie di utilità in modo che ogni app debba caricare solo le parti dell'API che verranno utilizzate.
    • (Facoltativo) Configura il progetto per l'utilizzo delle estensioni v3. Le risorse esterne in v3 possono essere utilizzate per convalidare il codice con il compilatore di chiusura o per attivare il completamento automatico nell'IDE. Scopri di più sulla compilazione avanzata ed esterni.
  4. Esegui test ed esegui l'iterazione. A questo punto avrai ancora del lavoro da fare, ma la buona notizia è che sarai sulla buona strada per passare alla tua nuova applicazione di mappe v3.

Modifiche nella V3 dell'API Maps JavaScript

Prima di pianificare la migrazione, è necessario comprendere le differenze tra l'API Maps JavaScript v2 e l'API Maps JavaScript v3. La versione più recente dell'API Maps JavaScript è stata scritta da zero, con particolare attenzione alle moderne tecniche di programmazione JavaScript, al maggiore utilizzo delle librerie e a un'API semplificata. Sono state aggiunte molte nuove funzionalità all'API e molte funzionalità note sono state modificate o addirittura rimosse. Questa sezione evidenzia alcune delle principali differenze tra le due release.

Di seguito sono riportate alcune delle modifiche apportate all'API v3:

  • Una libreria di base semplificata. Molte funzioni supplementari sono state spostate nelle librerie, contribuendo a ridurre il carico e i tempi di analisi per l'API di base, il che consente di caricare rapidamente la mappa su qualsiasi dispositivo.
  • Sono state migliorate le prestazioni di diverse funzionalità, come il rendering poligonale e il posizionamento dell'indicatore.
  • Un nuovo approccio ai limiti di utilizzo lato client per adattarsi meglio agli indirizzi condivisi utilizzati da proxy per dispositivi mobili e firewall aziendali.
  • Aggiunto il supporto per diversi browser moderni e browser per dispositivi mobili. Il supporto per Internet Explorer 6 è stato rimosso.
  • Abbiamo rimosso molte delle classi helper per uso generico ( GLog o GDownloadUrl). Oggi esistono molte eccellenti librerie JavaScript che offrono funzionalità simili, come Closure o jQuery.
  • Un'implementazione HTML5 di Street View che verrà caricata su qualsiasi dispositivo mobile.
  • Panorami personalizzati di Street View con le tue foto, che ti consentono di condividere panorami di piste da sci, case in vendita o altri luoghi interessanti.
  • Le personalizzazioni di Mappe con stile che ti consentono di modificare la visualizzazione degli elementi sulla mappa di base in base al tuo stile visivo unico.
  • Supporto di diversi nuovi servizi, come ElevationService e Distanza Matrix.
  • Un servizio migliorato di indicazioni stradali offre percorsi alternativi, ottimizzazione dei percorsi (soluzioni approssimative al problema del venditore in viaggio), indicazioni in bicicletta (con livello di bicicletta), indicazioni di trasporto pubblico e indicazioni trascinabili.
  • Un formato di geocodifica aggiornato che fornisce informazioni sul tipo più accurate rispetto al valore accuracy dalla versione 2 dell'API Geocoding.
  • Supporto per più Windows delle informazioni su una singola mappa

Upgrade dell'applicazione

La tua nuova chiave

L'API Maps JavaScript v3 utilizza un nuovo sistema di chiavi della versione 2. Forse stai già utilizzando una chiave v3 con la tua applicazione, nel qual caso non è necessaria alcuna modifica. Per verificare, controlla l'URL da cui carichi l'API Maps JavaScript per il relativo parametro key. Se il valore della chiave inizia con 'ABQIAA', stai utilizzando una chiave v2. Se hai una chiave v2, devi eseguire l'upgrade a una chiave v3 nell'ambito della migrazione, operazione che:

La chiave viene trasmessa durante il caricamento dell'API Maps JavaScript v3. Scopri di più sulla generazione di chiavi API.

Tieni presente che se sei un cliente delle API di Google Maps for Work, potresti utilizzare un ID client con il parametro client anziché il parametro key. Gli ID client sono ancora supportati nell'API Maps JavaScript v3 e non devono essere sottoposti al processo di upgrade della chiave.

Caricamento dell'API in corso

La prima modifica che dovrai apportare al codice riguarda la modalità di caricamento dell'API. Nella versione v2, carichi l'API Maps JavaScript tramite una richiesta a http://maps.google.com/maps. Se carichi l'API Maps JavaScript v3, dovrai apportare le seguenti modifiche:

  1. Carica l'API da //maps.googleapis.com/maps/api/js
  2. Rimuovi il parametro file.
  3. Aggiorna il parametro key con la nuova chiave v3. I clienti delle API di Google Maps for Work devono utilizzare un parametro client.
  4. (Solo piano Premium di Google Maps Platform) Assicurati che il parametro client sia fornito, come spiegato nella Guida per gli sviluppatori di piani premium di Google Maps.
  5. Rimuovi il parametro v per richiedere la versione più recente rilasciata o modificane il valore in base allo schema di controllo delle versioni v3.
  6. (Facoltativo) Sostituisci il parametro hl con language e conservane il valore.
  7. (Facoltativo) Aggiungi un parametro libraries per caricare le librerie facoltative.

Nel caso più semplice, il bootstrap v3 specificherà solo il parametro della tua chiave API:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

L'esempio seguente richiede la versione più recente dell'API Maps JavaScript v2 in tedesco:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

L'esempio seguente è una richiesta equivalente per la v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Introduzione allo spazio dei nomi google.maps

Probabilmente, la modifica più evidente nell'API Maps JavaScript v3 è l'introduzione dello spazio dei nomi google.maps. Per impostazione predefinita, l'API v2 posiziona tutti gli oggetti nello spazio dei nomi globale, con possibili conflitti di denominazione. All'interno della v3, tutti gli oggetti si trovano all'interno dello spazio dei nomi google.maps.

Quando esegui la migrazione dell'applicazione alla versione 3, dovrai modificare il codice per utilizzare il nuovo spazio dei nomi. Purtroppo, la ricerca di "G" e la sostituzione con "google.maps". Non funzionerà perfettamente, ma è una buona regola generale da applicare quando si esamina il codice. Di seguito sono riportati alcuni esempi delle classi equivalenti in v2 e v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Rimozione del codice obsoleto

L'API Maps JavaScript v3 ha paralleli per la maggior parte delle funzionalità nella versione v2; tuttavia, alcune classi non sono più supportate. Nell'ambito della migrazione, devi sostituire queste classi con librerie di utilità di terze parti oppure rimuovere questi riferimenti dal codice. Esistono molte librerie JavaScript eccellenti che offrono funzionalità simili, come Closure o jQuery.

Le seguenti classi non hanno paralleli nell'API Maps JavaScript v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Codice di confronto

Confrontiamo due, piuttosto semplici, applicazioni scritte con le API v2 e v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

Come potete vedere, ci sono diverse differenze tra le due applicazioni. Le modifiche importanti includono:

  • L'indirizzo da cui viene caricata l'API è cambiato.
  • I metodi GBrowserIsCompatible() e GUnload() non sono più obbligatori nella versione v3 e sono stati rimossi dall'API.
  • L'oggetto GMap2 è sostituito da google.maps.Map come oggetto centrale nell'API.
  • Le proprietà vengono ora caricate tramite le classi Opzioni. Nell'esempio riportato di seguito, abbiamo impostato le tre proprietà necessarie per caricare una mappa (center, zoom e mapTypeId) tramite un oggetto MapOptions in linea.
  • L'interfaccia utente predefinita è attiva per impostazione predefinita nella versione 3. Puoi disattivare questa funzionalità impostando la proprietà disableDefaultUI su true nell'oggetto MapOptions.

Riepilogo

A questo punto avrai un assaggio di alcuni dei punti chiave coinvolti nella migrazione dalla versione v2 alla v3 dell'API Maps JavaScript. Potresti avere bisogno di altre informazioni, ma dipenderanno dalla tua applicazione. Nelle sezioni seguenti abbiamo incluso le istruzioni per la migrazione per casi specifici che potresti riscontrare. Inoltre, durante l'upgrade sono disponibili diverse risorse utili.

In caso di problemi o domande su questo articolo, usa il link INVIA FEEDBACK nella parte superiore di questa pagina.

Riferimento dettagliato

Questa sezione fornisce un confronto dettagliato delle funzionalità più popolari sia per la versione v2 che per la v3 dell'API Maps JavaScript. Ogni sezione del riferimento è progettata per essere letta singolarmente. Ti consigliamo di non leggere completamente questo riferimento; utilizza invece questo materiale per aiutarti nella migrazione caso per caso.

  • Eventi: registrazione ed elaborazione degli eventi.
  • Controlli: manipola i controlli di navigazione visualizzati sulla mappa.
  • Overlay: aggiunge e modifica oggetti sulla mappa;
  • Tipi di mappa: i riquadri che compongono la mappa di base.
  • Livelli: aggiunta e modifica di contenuti come gruppo, ad esempio livelli KML o di traffico.
  • Servizi: utilizzo della geocodifica di Google, indicazioni stradali o servizi di Street View.

Eventi

Il modello di evento per l'API Maps JavaScript v3 è simile a quello utilizzato nella versione 2, anche se molto è cambiato.

Impostazioni

L'API Maps JavaScript mostra i controlli dell'interfaccia utente che consentono agli utenti di interagire con la tua mappa. Puoi utilizzare l'API per personalizzare la modalità di visualizzazione di questi controlli.

Overlay

Gli overlay riflettono gli oggetti che "aggiungi" alla mappa per designare punti, linee, aree o raccolte di oggetti.

Tipi di mappa

I tipi di mappe disponibili in v2 e v3 sono leggermente diversi, ma tutti i tipi di mappa di base sono disponibili in entrambe le versioni dell'API. Per impostazione predefinita, la versione v2 utilizza i riquadri standard "verniciati" della mappa stradale. Tuttavia, v3 richiede che venga fornito un tipo di mappa specifico quando si crea un oggetto google.maps.Map.

Base

I livelli sono oggetti sulla mappa costituiti da uno o più overlay. Possono essere manipolati come una singola unità e generalmente riflettono raccolte di oggetti.

Servizi