Aggiornamento dell'applicazione API Maps JavaScript dalla V2 alla V3

Nuovo evento per il supporto MVC

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

• Gli eventi utente (come gli eventi di clic) vengono propagati dal DOM all'API Maps JavaScript. Questi eventi sono separati e distinti dagli eventi DOM standard.
• Le notifiche di modifica dello stato MVC riflettono le modifiche negli oggetti dell'API di Google Maps e vengono denominate utilizzando una convenzione property_changed.

Ogni oggetto dell'API di Google Maps esporta una serie di eventi denominati. Le applicazioni interessate a eventi specifici devono registrare i listener di eventi per questi eventi ed eseguire il codice alla ricezione. Questo meccanismo basato su eventi è lo stesso nell'API Maps JavaScript v2 e v3, ad eccezione del fatto che lo spazio dei nomi è cambiato 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 legati alle prestazioni, ti consigliamo di rimuovere un listener di eventi quando non è più necessario. La rimozione di un listener di eventi funziona allo stesso modo nelle v2 e 3:

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

Ascolto di eventi DOM

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

Utilizzo di argomenti superati negli eventi

Gli eventi UI spesso passano un argomento evento a cui il listener di eventi può accedere. La maggior parte degli argomenti degli eventi nella versione 3 è stata semplificata per essere più coerente rispetto agli oggetti nell'API. Per maggiori dettagli, consulta la documentazione di riferimento v3.

Nessun argomento overlay esiste nei listener di eventi v3. Se registri un evento click su una mappa v3, il callback si verifica solo quando l'utente fa clic sulla mappa base. Puoi registrare callback aggiuntivi sugli overlay cliccabili se devi reagire a questi clic.

// 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 nei tipi di controllo

Alcune modifiche ai tipi di control sono state introdotte con l'API v3.

1. L'API v3 supporta tipi di mappe aggiuntivi, tra cui mappe dei rilievi e la possibilità di aggiungere tipi di mappe personalizzati.
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 l'API Maps JavaScript v2 puoi aggiungere controlli alla mappa utilizzando il metodo addControl() dell'oggetto mappa. Nella versione 3, anziché accedere o modificare direttamente i controlli, puoi modificare l'oggetto MapOptions associato. L'esempio riportato di seguito mostra come personalizzare la mappa per aggiungere i seguenti controlli:

• che consentono all'utente di alternare tra i tipi di mappa disponibili
• una scala per mappe

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 v2, il metodo addControl() richiede un secondo parametro facoltativo che consente di specificare la posizione del controllo rispetto agli angoli della mappa.

Nella versione 3, puoi impostare la posizione di un controllo tramite la proprietà position delle opzioni di controllo. Il posizionamento di questi controlli non è assoluto; l'API esegue il layout dei controlli in modo intelligente, spostandoli intorno agli elementi della mappa esistenti all'interno di determinati vincoli (ad esempio le dimensioni della mappa). In questo modo ti assicuri che i controlli predefiniti siano compatibili con i tuoi controlli. Per ulteriori informazioni, consulta Controllo del posizionamento in v3.

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 sottoclassere la classe GControl e definire i gestori per i metodi initialize() e getDefaultPosition(). Non esiste un equivalente alla classe GControl nella versione 3. Al contrario, i controlli sono 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 figlio di Node (ad esempio un elemento <div>) e aggiungi listener di eventi per gestire eventuali eventi DOM. Esegui il push di Node nell'array controls[position] delle mappe per aggiungere un'istanza del controllo personalizzato alla tua mappa.

Data un'implementazione della classe HomeControl conforme ai requisiti di interfaccia indicati sopra (per i 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 nella versione 2 e 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, puoi assegnare una mappa a un overlay tramite la proprietà map della classe di opzioni overlay associata. Puoi anche aggiungere o rimuovere un overlay direttamente chiamando il metodo setMap() dell'oggetto overlay e specificando la mappa desiderata. Se imposti la proprietà della mappa su null, l'overlay viene rimosso.

Nessun metodo clearOverlays() esistente nella versione 3. Se vuoi gestire un insieme di overlay, devi creare un array che contenga gli overlay. Utilizzando questo array, puoi chiamare setMap() su ogni overlay dell'array (trasmettendo null se devi rimuoverli).

Indicatori trascinabili

Per impostazione predefinita, gli indicatori sono cliccabili ma non trascinabili. I due esempi riportati di seguito 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 visualizzare 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 questo processo. È sufficiente impostare la proprietà icon dell'indicatore sull'URL dell'immagine personalizzata e l'API ridimensionerà automaticamente l'icona.

L'API Maps JavaScript supporta inoltre le icone complesse. Un'icona complessa può includere più riquadri, forme complesse oppure specificare l'"ordine di sovrapposizione" delle immagini rispetto ad altri overlay. Per aggiungere una forma a un indicatore nella versione v2, devi specificare la proprietà aggiuntiva in ogni istanza GIcon e passarla come opzione a un costruttore GMarker. Nella versione v3, 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.

I seguenti esempi mostrano una bandierina di 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

Una polilinea è composta da un array di LatLng e una serie di segmenti di linea che collegano queste posizioni in una sequenza ordinata. La creazione e la visualizzazione di un oggetto Polyline nella versione 3 è simile all'utilizzo di un oggetto GPolyline nella versione v2. I seguenti esempi tracciano una polilinea geodetica semitrasparente e larga 3 pixel 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 Geometry fornisce invece metodi per codificare e decodificare le polilinee. Consulta la sezione Librerie nell'API di Maps v3 per ulteriori informazioni su come caricare questa libreria.

Gli esempi riportati di seguito tracciano la stessa polilinea codificata; il codice v3 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 ciclo chiuso. Proprio come l'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 l'eccezione che non è più necessario ripetere il vertice iniziale alla fine del percorso per chiudere il loop. L'API v3 chiuderà automaticamente tutti i poligoni disegnando un tratto che colleghi l'ultima coordinata alla prima coordinata. I seguenti snippet di codice creano un poligono che rappresenta il Triangolo delle Bermuda:

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

Polilinee e poligoni possono essere resi modificabili dall'utente. 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 informative

Un elemento InfoWindow mostra i contenuti in una finestra mobile sopra la mappa. Esistono alcune differenze fondamentali tra le finestre informative v2 e v3:

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

Sovrapposizioni del suolo

Per posizionare un'immagine su una mappa, devi usare un oggetto GroundOverlay. Il costruttore di un elemento GroundOverlay è sostanzialmente lo stesso in v2 e v3: specifica l'URL di un'immagine e i limiti dell'immagine come parametri.

Il seguente esempio inserisce una mappa antica di Newark, NJ sulla mappa sotto forma di overlay:

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 mappa 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) visualizza le immagini satellitari di Google Earth.
• MapTypeId.HYBRID (sostituisce G_HYBRID_MAP) mostra una combinazione di vista normale e vista satellite.
• MapTypeId.TERRAIN (sostituisce G_PHYSICAL_MAP) mostra una mappa fisica basata sulle informazioni sui rilievi.

Di seguito è riportato un esempio di come le versioni v2 e v3 impostano la mappa sulla visualizzazione Rilievo:

map.setMapType(G_PHYSICAL_MAP);
    

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

L'API Maps JavaScript v3 ha apportato alcune modifiche anche ai tipi di mappe meno comuni:

• I riquadri della mappa per corpi celesti diversi da Earth non sono disponibili come tipi di mappe nell'API v3, ma è possibile accedervi come tipi di mappa personalizzati, come mostrato in questo esempio.
• Non esiste un tipo di mappa speciale nella versione 3 che sostituisce il tipo G_SATELLITE_3D_MAP nella versione 2. Puoi invece integrare il plug-in Google Earth nelle mappe v3 utilizzando questa libreria.

Numero massimo di immagini con zoom

Le immagini satellitari non sono sempre disponibili a livelli di zoom elevati. Se vuoi conoscere il livello di zoom più alto disponibile prima di impostare il livello, 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 prospettiche aeree

Quando attivi le immagini aeree nella versione 3, i controlli sono simili al controllo GLargeZoomControl3D della versione 2, con un controllo Ruota interstitial aggiuntivo che ti consente di ruotare tra le direzioni supportate.

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