Aggiornamento dell'applicazione API Maps JavaScript dalla V2 alla V3

L'API Maps JavaScript v2 non è più disponibile a partire dal 26 maggio 2021. Di conseguenza, le mappe v2 del tuo sito smetteranno di funzionare e restituiranno errori JavaScript. Per continuare a utilizzare le mappe sul tuo sito, esegui la migrazione all'API Maps JavaScript v3. Questa guida ti aiuterà a svolgere 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 la console Google Cloud per gestire le chiavi. Se utilizzi ancora una chiave v2, assicurati di ottenere 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 modifiche necessarie 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. Nell'ambito di questo processo, anche la maggior parte degli oggetti è stata rinominata. Ad esempio, anziché GMap2, ora caricherai google.maps.Map.
    • Rimuovi qualsiasi riferimento a metodi obsoleti. È stato rimosso un certo numero di 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 librerie al codice. Molte funzionalità sono state esternalizzate in 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 della versione v3 esterna. Le estensioni v3 extern possono essere utilizzate per aiutarti a convalidare il codice con il Closure Compiler o per attivare il completamento automatico nel tuo IDE. Scopri di più sulle compilation ed esterne avanzate.
  4. Testa e ottimizza. A questo punto avrai ancora del lavoro da fare, ma la buona notizia è che sarai a buon punto nella tua nuova applicazione per le mappe v3.

Modifiche nella V3 dell'API Maps JavaScript

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

Ecco alcune delle modifiche apportate all'API v3:

  • Una libreria di base semplificata. Molte funzioni supplementari sono state spostate in librerie, contribuendo a ridurre i tempi di caricamento e analisi dell'API Core, che consente il caricamento rapido della mappa su qualsiasi dispositivo.
  • Sono state migliorate le prestazioni di diverse funzionalità, come il rendering dei poligoni e il posizionamento degli indicatori.
  • Un nuovo approccio ai limiti di utilizzo lato client per supportare meglio gli indirizzi condivisi utilizzati dai proxy mobili e dai firewall aziendali.
  • Aggiunto il supporto per diversi browser moderni e per dispositivi mobili. Internet Explorer 6 è stato rimosso.
  • Sono state rimosse molte delle classi helper per uso generico ( GLog o GDownloadUrl). Attualmente esistono molte librerie JavaScript eccellenti che forniscono funzionalità simili, ad esempio Closure o jQuery.
  • Un'implementazione Street View HTML5 che può essere caricata su qualsiasi dispositivo mobile.
  • Panoramiche Street View personalizzate con le tue foto, per condividere panoramiche di piste da sci, case in vendita o altri luoghi interessanti.
  • Personalizzazioni di Mappe con stili che ti consentono di modificare la visualizzazione degli elementi sulla mappa base per adattarla al tuo stile visivo unico.
  • Supporto per diversi nuovi servizi, come ElevationService e Distance Matrix.
  • I servizi di indicazioni stradali migliorati forniscono percorsi alternativi, ottimizzazione dei percorsi (soluzioni approssimative al problema con i venditori in viaggio), indicazioni per biciclette (con livello per le biciclette), indicazioni con il trasporto pubblico e indicazioni trascinabili.
  • Un formato Geocoding aggiornato che fornisce informazioni sul tipo più accurate rispetto al valore accuracy dell'API Geocoding v2.
  • Supporto di più finestre informative su una singola mappa

Upgrade dell'applicazione

La tua nuova chiave

La versione 3 dell'API Maps JavaScript utilizza un nuovo sistema di chiavi a partire dalla versione 2. È possibile che tu stia già utilizzando una chiave v3 con la tua applicazione, nel qual caso non sono necessarie modifiche. Per verificare, controlla l'URL da cui carichi l'API Maps JavaScript per individuare il 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, che:

La chiave viene passata 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 delle chiavi.

Caricamento dell'API in corso

La prima modifica da apportare al codice riguarda il modo in cui carichi l'API. Nella versione 2, l'API Maps JavaScript viene caricata tramite una richiesta a http://maps.google.com/maps. Se stai caricando 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 venga fornito come spiegato nella Guida per gli sviluppatori del piano premium di Google Maps Platform.
  5. Rimuovi il parametro v per richiedere la versione più recente rilasciata o modificane il valore in base allo schema controllo delle versioni v3.
  6. (Facoltativo) Sostituisci il parametro hl con language e conserva il valore.
  7. (Facoltativo) Aggiungi un parametro libraries per caricare le librerie facoltative.

Nel caso più semplice, il bootstrap v3 specifica solo il parametro 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 versione 3.

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

Introduzione allo spazio dei nomi google.maps

Probabilmente il cambiamento più notevole nell'API Maps JavaScript v3 è l'introduzione dello spazio dei nomi google.maps. Per impostazione predefinita, l'API v2 inserisce tutti gli oggetti nello spazio dei nomi globale, il che può causare conflitti di denominazione. Nella versione v3, tutti gli oggetti si trovano all'interno dello spazio dei nomi google.maps.

Quando esegui la migrazione della tua applicazione alla versione v3, devi modificare il codice per utilizzare il nuovo spazio dei nomi. Purtroppo, la ricerca di "G" e la sostituzione con "google.maps" non funzionano completamente, ma è una buona regola generale da applicare durante la revisione del 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 in corso...

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

Le seguenti classi non hanno parallelo nella versione 3 dell'API Maps JavaScript:

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

Confronto tra codice

Confrontiamo due applicazioni, piuttosto semplici, scritte con l'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 puoi vedere, ci sono diverse differenze tra le due applicazioni. Le modifiche più importanti includono:

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

Riepilogo

A questo punto avrai un'idea di alcuni dei punti chiave coinvolti nella migrazione dalla v2 alla v3 dell'API Maps JavaScript. Potresti dover conoscere ulteriori informazioni, ma dipenderanno dalla tua applicazione. Nelle sezioni seguenti abbiamo incluso le istruzioni per la migrazione dei casi specifici che potresti riscontrare. Inoltre, esistono diverse risorse che potrebbero esserti utili durante il processo di upgrade.

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

Riferimento dettagliato

Questa sezione fornisce un confronto dettagliato delle funzionalità più usate delle versioni 2 e 3 dell'API Maps JavaScript. Ogni sezione del riferimento è progettata per essere letta singolarmente. Ti consigliamo di non leggere questo riferimento interamente, ma di utilizzare questo materiale per facilitare la migrazione caso per caso.

  • Eventi: registrazione e gestione degli eventi.
  • Controlli: manipolazione dei controlli di navigazione visualizzati sulla mappa.
  • Sovrapposizioni: aggiunta e modifica di oggetti sulla mappa.
  • Tipi di mappa: i riquadri che compongono la mappa base.
  • Livelli: aggiunta e modifica di contenuti come gruppo, ad esempio i livelli KML o Traffico.
  • Servizi: con la geocodifica, le indicazioni stradali o i servizi di Street View di Google.

Eventi

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

Controlli

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 l'aspetto di questi controlli.

Sovrapposizioni

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

Tipi di mappa

I tipi di mappe disponibili nelle versioni 2 e 3 sono leggermente diversi, ma tutti i tipi di mappe di base sono disponibili in entrambe le versioni dell'API. Per impostazione predefinita, la versione v2 utilizza riquadri di mappe stradali "dipinti" standard. Tuttavia, v3 richiede di specificare un tipo di mappa specifico durante la creazione di un oggetto google.maps.Map.

Livelli

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

Servizi