Eseguire l'upgrade dell'applicazione API Maps JavaScript dalla versione 2 alla versione 3

Nuovo evento per il supporto MVC

L'API v3 aggiunge un nuovo tipo di evento per riflettere le modifiche dello stato MVC. Ora esistono due tipi di eventi:

• Gli eventi utente (ad esempio gli eventi del mouse "click") vengono propagati dal DOM all'API JavaScript di Maps. Questi eventi sono separati e distintamente dagli eventi DOM standard.
• Le notifiche di modifica dello stato MVC riflettono le modifiche agli oggetti dell'API Maps e vengono denominate utilizzando una convenzione property_changed.

Ogni oggetto dell'API Maps esporta una serie di eventi denominati. Le applicazioni interessate a eventi specifici devono registrare gli ascoltatori di eventi per questi eventi ed eseguire il codice quando vengono ricevuti. Questo meccanismo basato su eventi è lo stesso nell'API Maps JavaScript v2 e v3, tranne per il fatto che lo spazio dei nomi è passato da GEvent a google.maps.event:

GEvent.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

google.maps.event.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

Rimozione dei listener di eventi

Per motivi di prestazioni, è meglio rimuovere un gestore di eventi quando non è più necessario. La rimozione di un gestore di eventi funziona allo stesso modo nella versione 2 e v3:

1. Quando crei un listener di eventi, viene restituito un oggetto opaco (GEventListener nella versione 2, MapsEventListener nella versione 3).
2. Quando vuoi rimuovere il listener di eventi, passa questo oggetto al metodo removeListener() (GEvent.removeListener() nella versione 2 o google.maps.event.removeListener() nella versione 3) per rimuoverlo.

Ascolto degli eventi DOM

Se vuoi acquisire e rispondere agli eventi DOM (Document Object Model), la versione 3 fornisce il metodo statico google.maps.event.addDomListener(), equivalente al metodo GEvent.addDomListener() nella versione 2.

Utilizzare gli argomenti passati negli eventi

Gli eventi della UI spesso passano un argomento evento a cui può accedere l'ascoltatore di eventi. La maggior parte degli argomenti evento nella versione 3 è stata semplificata per essere più coerente con gli oggetti dell'API. Per maggiori dettagli, consulta la documentazione di riferimento della versione 3.

Non esiste alcun argomento overlay nei listener di eventi della versione 3. Se registri un evento click su una mappa v3, il callback si verifica solo quando l'utente fa clic sulla mappa di base. Se devi reagire a questi clic, puoi registrare callback aggiuntivi per gli overlay cliccabili.

// Passes an overlay argument when clicking on a map

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

GEvent.addListener(map,'click', function(overlay, latlng) {
  if (latlng) {
    var marker = new GMarker(latlng);
    map.addOverlay(marker);
  }
});

// Passes only an event argument

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

google.maps.event.addListener(map, 'click', function(event) {
  var marker = new google.maps.Marker({
      position: event.latLng,
      map: map
  });
});

Modifiche ai tipi di controllo

Con l'API v3 sono state introdotte alcune modifiche ai tipi control.

1. L'API v3 supporta altri tipi di mappe , tra cui le mappe del terreno e la possibilità di aggiungere tipi di mappe personalizzate.
2. Il controllo gerarchico v2, GHierarchicalMapTypeControl, non è più disponibile. Puoi ottenere un effetto simile utilizzando il controllo google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Il layout orizzontale fornito da GMapTypeControl nella versione 2 non è disponibile nella versione 3.

Aggiunta di controlli alla mappa

Con la versione 2 dell'API Maps JavaScript, aggiungi i controlli alla mappa tramite il metodo addControl() dell'oggetto mappa. Nella versione 3, anziché accedere o modificare direttamente i controlli, modifichi l'oggetto MapOptions associato. L'esempio riportato di seguito mostra come personalizzare la mappa per aggiungere i seguenti controlli:

• pulsanti che consentono all'utente di passare da un tipo di mappa all'altro
• una scala della mappa

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP,

    // Add controls
    mapTypeControl: true,
    scaleControl: true
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Controlli di posizionamento sulla mappa

I controlli di posizionamento sono cambiati molto nella versione 3. Nella versione 2, il metodo addControl() accetta un secondo parametro facoltativo che consente di specificare la posizione del controllo rispetto ai vertici della mappa.

Nella versione 3, imposti la posizione di un controllo tramite la proprietà position delle opzioni di controllo. Il posizionamento di questi controlli non è assoluto; l'API li dispone in modo intelligente facendoli "scorrere" attorno agli elementi della mappa esistenti entro determinati vincoli (ad esempio le dimensioni della mappa). In questo modo, i controlli predefiniti sono compatibili con i tuoi controlli. Per ulteriori informazioni, consulta Controllare il posizionamento nella versione 3.

Il seguente codice riposiziona i controlli degli esempi precedenti:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
    G_ANCHOR_TOP_LEFT, new GSize(10, 10)));

// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
    G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));

var myOptions = {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP,

  // Add map type control
  mapTypeControl: true,
  mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_LEFT
  },

  // Add scale
  scaleControl: true,
  scaleControlOptions: {
      position: google.maps.ControlPosition.BOTTOM_RIGHT
  }
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Controlli personalizzati

L'API Maps JavaScript ti consente di creare controlli di navigazione personalizzati. Per personalizzare i controlli con l'API v2, devi creare una sottoclasse della classe GControl e definire i gestori per i metodi initialize() e getDefaultPosition(). Non esiste un equivalente per la classe GControl nella versione 3. I controlli vengono invece rappresentati come elementi DOM. Per aggiungere un controllo personalizzato con l'API v3, crea una struttura DOM per il controllo in un costruttore come elemento secondario di un Node (ad es. un elemento <div>) e aggiungi ascoltatori di eventi per gestire eventuali eventi DOM. Inserisci Node nell'array controls[position] delle mappe per aggiungere un'istanza del controllo personalizzato alla mappa.

Data un'implementazione della classe HomeControl che rispetti i requisiti di interfaccia indicati sopra (per maggiori dettagli, consulta la documentazione relativa ai controlli personalizzati), i seguenti esempi di codice mostrano come aggiungere un controllo personalizzato a una mappa.

map.addControl(new HomeControl(),
    GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));

var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);

map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
    homeControlDiv);

Aggiunta e rimozione di overlay

I tipi di oggetti rappresentati da un overlay sono gli stessi tra la versione 2 e la versione 3, ma vengono gestiti in modo diverso.

Gli overlay nell'API v2 sono stati aggiunti e rimossi dalla mappa utilizzando i metodi addOverlay() e removeOverlay() dell'oggetto GMap2. Nella versione 3, assegni una mappa a un overlay tramite la proprietà map della classe di opzioni di overlay associata. Puoi anche aggiungere o rimuovere un overlay direttamente chiamando il metodo setMap() dell'oggetto overlay e specificando la mappa che ti interessa. Se imposti la proprietà mappa su null, l'overlay viene rimosso.

Nella versione 3 non esiste il metodo clearOverlays(). Se vuoi gestire un insieme di overlay, devi creare un array per contenerli. Utilizzando questo array, puoi chiamare setMap() su ogni overlay nell'array (passando null se devi rimuoverli).

Indicatori spostabili

Per impostazione predefinita, gli indicatori sono cliccabili, ma non possono essere trascinati. I seguenti due esempi aggiungono un indicatore trascinabile:

var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);

var marker = new GMarker(latLng, {
  draggable: true
});
map.addOverlay(marker);

var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
  document.getElementById('map'), {
  center: myLatLng,
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var marker = new google.maps.Marker({
    position: myLatLng,
    draggable: true,
    map: map
});

Icone

Puoi definire un'icona personalizzata da mostrare al posto dell'indicatore predefinito. Per utilizzare un'immagine personalizzata nella versione 2, puoi creare un'istanza GIcon da G_DEFAULT_ICON type e modificarla. Se l'immagine è più grande o più piccola dell'icona predefinita, devi specificarla con un'istanza GSize. L'API v3 semplifica leggermente questa procedura. Basta impostare la proprietà icon dell'indicatore sull'URL dell'immagine personalizzata e l'API imposterà automaticamente le dimensioni dell'icona.

L'API Maps JavaScript supporta anche le icone complesse. Un'icona complessa può includere più riquadri, forme complesse o specificare l'"ordine di impilaggio" di come devono essere visualizzate le immagini rispetto ad altri overlay. Per aggiungere una forma a un indicatore nella versione 2, devi specificare la proprietà aggiuntiva in ogni istanza GIcon e passarla come opzione a un costruttore GMarker. Nella versione 3, le icone specificate in questo modo devono impostare le proprietà icon su un oggetto di tipo Icon. Le ombre degli indicatori non sono supportate nella versione 3.

Gli esempi seguenti mostrano una bandiera da spiaggia a Bondi Beach, in Australia, con la parte trasparente dell'icona non cliccabile:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);

map.addOverlay(new GMarker(bbLatLng, {
  icon: flagIcon
}));

var map = new google.maps.Map(
  document.getElementById('map'), {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var shape = {
    coord: [1, 1, 1, 20, 18, 20, 18 , 1],
    type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);

var bbMarker = new google.maps.Marker({
    icon: '/images/beachflag.png'
    shape: shape,
    position: bbLatLng,
    map: map
});

Polilinee

Un polilinea è costituito da un array di LatLng, oltre a una serie di segmenti che collegano le posizioni in una sequenza ordinata. La creazione e la visualizzazione di un oggetto Polyline nella versione 3 è simile all'utilizzo di un oggetto Polyline nella versione 2.GPolyline I seguenti esempi disegnano un polilinea geodetico semitrasparente di 3 pixel di larghezza da Zurigo a Sydney passando per Singapore:

var polyline = new GPolyline(
  [
    new GLatLng(47.3690239, 8.5380326),
    new GLatLng(1.352083, 103.819836),
    new GLatLng(-33.867139, 151.207114)
  ],
  '#FF0000', 3, 0.5, {
  geodesic: true
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: [
    new google.maps.LatLng(47.3690239, 8.5380326),
    new google.maps.LatLng(1.352083, 103.819836),
    new google.maps.LatLng(-33.867139, 151.207114)
  ],
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
  geodesic: true
});

polyline.setMap(map);

Polilinee codificate

La versione 3 non supporta la creazione di oggetti Polyline direttamente da polilinee codificate. La libreria di geometria fornisce invece metodi per codificare e decodificare le polilinee. Per ulteriori informazioni su come caricare questa libreria, consulta la sezione Raccolte nell'API Maps v3.

Gli esempi riportati di seguito disegnano lo stesso polilinea codificato; il codice della versione 3 utilizza il metodo decodePath() dello spazio dei nomi google.maps.geometry.encoding.

var polyline = new GPolyline.fromEncoded({
  points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
  levels: 'PPP',
  zoomFactor: 2,
  numLevels: 18,
  color: '#ff0000',
  opacity: 0.8,
  weight: 3
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: google.maps.geometry.encoding.decodePath(
    'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
});

polyline.setMap(map);

Poligoni

Un poligono definisce una regione all'interno di un circuito chiuso. Molto simile all'oggetto Polyline, gli oggetti Polygon sono costituiti da una serie di punti in una sequenza ordinata. La classe Polygon v3 è molto simile alla classe GPolygon v2, con la notevole eccezione che non è più necessario ripetere il vertice iniziale alla fine del percorso per chiudere il ciclo. L'API v3 chiude automaticamente tutti i poligoni disegnando un tratto che collega la ultima alla prima coordinata. I seguenti snippet di codice creano un poligono che rappresenta il triangolo delle Bermude:

var map = new GMap2(document.getElementById('map'));

map.setCenter(new GLatLng(24.886436, -70.268554), 5);

var bermudaTriangle = new GPolygon(
  [
    new GLatLng(25.774252, -80.190262),
    new GLatLng(18.466465, -66.118292),
    new GLatLng(32.321384, -64.75737),
    new GLatLng(25.774252, -80.190262)
  ],
  '#FF0000', 2, 0.8, '#FF0000', 0.35);

map.addOverlay(bermudaTriangle);

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(24.886436, -70.268554),
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  zoom: 5
});

var bermudaTriangle = new google.maps.Polygon({
  paths: [
    new google.maps.LatLng(25.774252, -80.190262),
    new google.maps.LatLng(18.466465, -66.118292),
    new google.maps.LatLng(32.321384, -64.75737)
  ],
  strokeColor: '#FF0000',
  strokeWeight: 2,
  strokeOpacity: 0.8,
  fillColor: '#FF0000',
  fillOpacity: 0.35
});

bermudaTriangle.setMap(map);

Forme modificabili dall'utente

È possibile rendere modificabili da parte dell'utente le polilinee e i poligoni. I seguenti snippet di codice sono equivalenti:

map.addOverlay(polyline);
polyline.enableEditing();

polyline.setMap(map);
polyline.setEditable(true);

Per funzionalità di disegno più avanzate, consulta la libreria di disegni nella documentazione della versione 3.

Finestre di informazioni

Un InfoWindow mostra i contenuti in una finestra popup sopra la mappa. Esistono alcune differenze fondamentali tra le finestre di informazioni della versione 2 e della versione 3:

• L'API v2 supporta un solo GInfoWindow per mappa, mentre l'API v3 supporta più InfoWindow simultanei su ogni mappa.
• La versione 3 InfoWindow rimarrà aperta quando farai clic sulla mappa. La versione 2 GInfoWindow si chiude automaticamente quando fai clic sulla mappa. Puoi emulare il comportamento della v2 aggiungendo un ascoltatore click all'oggetto Map.
• L'API v3 non fornisce il supporto nativo per un InfoWindow con schede.

Overlay del suolo

Per posizionare un'immagine su una mappa, devi utilizzare un oggetto GroundOverlay. Il costruttore di un GroundOverlay è essenzialmente lo stesso nella versione 2 e 3: specifica un URL di un'immagine e i relativi confini come parametri.

L'esempio seguente mostra una mappa antica di Newark, nel New Jersey, come overlay sulla mappa:

var bounds = new GLatLngBounds(
    new GLatLng(40.716216, -74.213393),
    new GLatLng(40.765641, -74.139235));

var overlay = new GGroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

map.addOverlay(overlay);

var bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(40.716216, -74.213393),
    new google.maps.LatLng(40.765641, -74.139235));

var overlay = new google.maps.GroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

overlay.setMap(map);

Tipi di mappe comuni

I quattro tipi di mappe di base sono disponibili sia nella versione 2 che nella versione 3:

• MapTypeId.ROADMAP (sostituisce G_NORMAL_MAP) mostra la visualizzazione della mappa stradale.
• MapTypeId.SATELLITE (sostituisce G_SATELLITE_MAP) mostra le immagini satellitari di Google Earth.
• MapTypeId.HYBRID (sostituisce G_HYBRID_MAP) mostra una combinazione di viste normali e satellitari.
• MapTypeId.TERRAIN (sostituisce G_PHYSICAL_MAP) mostra una mappa fisica basata sulle informazioni del terreno.

Di seguito è riportato un esempio di v2 e v3 che impostano la mappa sulla visualizzazione del terreno:

map.setMapType(G_PHYSICAL_MAP);
    

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    

La versione 3 dell'API Maps JavaScript ha apportato alcune modifiche anche ai tipi di mappa meno comuni:

• I tessere della mappa per corpi celesti diversi dalla Terra non sono disponibili come tipi di mappa nell'API v3, ma è possibile accedervi come tipi di mappa personalizzati come mostrato in questo esempio.
• Nella versione 3 non è presente un tipo di mappa speciale che sostituisca il tipo G_SATELLITE_3D_MAP della versione 2. In alternativa, puoi integrare il plug-in di Google Earth nelle tue mappe v3 utilizzando questa raccolta.

Immagini con zoom massimo

Le immagini satellitari non sono sempre disponibili a livelli di zoom elevati. Se vuoi conoscere il livello di zoom più alto disponibile prima di impostarlo, utilizza la classe google.maps.MaxZoomService. Questa classe sostituisce il metodo GMapType.getMaxZoomAtLatLng() della versione 2.

var point = new GLatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);

map.getCurrentMapType().getMaxZoomAtLatLng(point,
  function(response) {
    if (response.status) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

var myLatlng = new google.maps.LatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
  document.getElementById("map"),{
    zoom: 0,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
  myLatlng,
  function(response) {
    if (response.status == google.maps.MaxZoomStatus.OK) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

Immagini aeree prospettiche

Quando attivi le immagini aeree nella versione 3, i controlli sono simili a quelli della versione 2.GLargeZoomControl3D, con un controllo aggiuntivo di rotazione per passare tra le direzioni supportate.

Puoi monitorare le città in cui le immagini a 45° sono attualmente disponibili su questa mappa. Quando sono disponibili immagini a 45°, viene aggiunta un'opzione di sottomenu al pulsante Satellite dell'API Maps.