Mettre à niveau votre application API Maps JavaScript de la V2 à la V3

Nouvel événement pour la prise en charge MVC

L'API v3 ajoute un nouveau type d'événement pour refléter les changements d'état MVC. Il existe désormais deux types d'événements:

• Les événements utilisateur (tels que les événements de souris "clic") sont propagés du DOM vers l'API Maps JavaScript. Ils sont distincts des événements standards du DOM.
• Les notifications de changement d'état MVC reflètent les modifications apportées aux objets de l'API Google Maps et sont nommées selon la convention property_changed.

Chaque objet Maps API exporte un certain nombre d'événements nommés. Les applications intéressées par des événements spécifiques doivent enregistrer des écouteurs d'événements pour ces événements et exécuter du code lorsqu'ils sont reçus. Ce mécanisme basé sur les événements est le même dans les versions 2 et 3 de l'API Maps JavaScript, si ce n'est que l'espace de noms est passé de GEvent à 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.');
});

Supprimer des écouteurs d'événement

Pour des raisons de performances, il est préférable de supprimer un écouteur d'événements lorsqu'il n'est plus nécessaire. La suppression d'un écouteur d'événements fonctionne de la même manière dans les versions 2 et 3:

1. Lorsque vous créez un écouteur d'événements, un objet opaque (GEventListener dans la version 2, MapsEventListener dans la version 3) est renvoyé.
2. Lorsque vous souhaitez supprimer l'écouteur d'événements, transmettez cet objet à la méthode removeListener() (GEvent.removeListener() dans la version 2 ou google.maps.event.removeListener() dans la version 3) afin de supprimer l'écouteur d'événements.

Écouter les événements DOM

Si vous souhaitez capturer des événements du DOM (Document Object Model) et y répondre, la version 3 fournit la méthode statique google.maps.event.addDomListener(), équivalente à la méthode GEvent.addDomListener() dans la version 2.

Utiliser des arguments transmis dans des événements

Les événements d'interface utilisateur transmettent souvent un argument d'événement auquel l'écouteur d'événements peut ensuite accéder. Dans la version 3, la plupart des arguments d'événement ont été simplifiés pour être plus cohérents avec les objets de l'API. (Pour en savoir plus, consultez la documentation de référence de la v3.)

Aucun argument overlay n'existe dans les écouteurs d'événements v3. Si vous enregistrez un événement click sur une carte v3, le rappel n'est effectué que lorsque l'utilisateur clique sur la carte de base. Vous pouvez enregistrer des rappels supplémentaires sur les superpositions cliquables si vous devez réagir à ces clics.

// 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
  });
});

Modifications des types de commande

Certaines modifications apportées aux types control ont été introduites avec l'API v3.

1. La version 3 de l'API est compatible avec d'autres types de carte, y compris des cartes de relief et la possibilité d'ajouter des types de carte personnalisés.
2. La commande hiérarchique v2, GHierarchicalMapTypeControl, n'est plus disponible. Vous pouvez obtenir un effet similaire en utilisant la commande google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. La mise en page horizontale fournie par GMapTypeControl dans la version 2 n'est pas disponible dans la version 3.

Ajouter des commandes à la carte

Avec l'API Maps JavaScript v2, vous auriez ajouté des commandes à votre carte via la méthode addControl() de votre objet de carte. Dans la version 3, au lieu d'accéder aux commandes ou de les modifier directement, vous devez modifier l'objet MapOptions associé. L'exemple ci-dessous montre comment personnaliser la carte pour ajouter les commandes suivantes:

• des boutons permettant à l'utilisateur de naviguer entre les types de carte disponibles
• une échelle de carte

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);

Positionner des commandes sur la carte

Le positionnement des commandes a fait l'objet d'importantes modifications dans la version 3 de l'API. Dans la version 2, la méthode addControl() utilise un deuxième paramètre facultatif qui vous permet de spécifier la position de la commande par rapport aux angles de la carte.

Dans la version 3, vous définissez la position d'une commande via la propriété position des options de commande. Le positionnement de ces commandes n'est pas absolu. Au lieu de cela, l'API les affiche de manière intelligente autour des éléments existants sur la carte, en respectant certaines contraintes (telles que la taille de la carte). Cela permet de veiller à ce que les commandes par défaut soient compatibles avec vos commandes. Pour en savoir plus, consultez la section Positionnement des commandes dans la version 3.

Le code suivant modifie la position des commandes fournies dans les exemples précédents :

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);

Commandes personnalisées

L'API Maps JavaScript vous permet de créer des commandes de navigation personnalisées. Pour personnaliser des commandes avec la version 2 de l'API, vous devez sous-classer la classe GControl et définir des gestionnaires pour les méthodes initialize() et getDefaultPosition(). Il n'existe pas d'équivalent à la classe GControl dans la version 3. Au lieu de cela, les commandes sont représentées par des éléments DOM. Pour ajouter une commande personnalisée avec l'API v3, créez une structure DOM pour la commande dans un constructeur en tant qu'enfant d'un Node (par exemple, un élément <div>) et ajoutez des écouteurs d'événements pour gérer tous les événements DOM. Transférez Node dans le tableau controls[position] de la carte pour ajouter une instance de la commande personnalisée à votre carte.

Étant donné une implémentation de la classe HomeControl conforme aux exigences d'interface mentionnées ci-dessus (consultez la documentation sur les commandes personnalisées pour en savoir plus), les exemples de code suivants montrent comment ajouter une commande personnalisée à une carte.

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);

Ajouter et supprimer des superpositions

Les types d'objets représentés par une superposition sont identiques dans les versions 2 et 3. Toutefois, ils sont gérés différemment.

Dans la version 2 de l'API, les superpositions ont été ajoutées à la carte et supprimées de celle-ci à l'aide des méthodes addOverlay() et removeOverlay() de l'objet GMap2. Dans la version 3, vous attribuez une carte à une superposition via la propriété map de la classe d'options de superposition associée. Vous pouvez également ajouter ou supprimer une superposition directement en appelant la méthode setMap() de l'objet de superposition et en spécifiant la carte souhaitée. Définir la propriété de carte sur null supprime la superposition.

Aucune méthode clearOverlays() n'existe dans la version 3. Si vous souhaitez gérer un ensemble de superpositions, vous devez créer un tableau pour les stocker. À l'aide de ce tableau, vous pouvez ensuite appeler setMap() sur chaque superposition du tableau (en transmettant null si vous devez les supprimer).

Marqueurs déplaçables

Par défaut, les marqueurs sont cliquables, mais pas déplaçables. Les deux exemples suivants ajoutent un repère déplaçable:

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
});

Icônes

Vous pouvez définir une icône personnalisée à afficher à la place du marqueur par défaut. Pour utiliser une image personnalisée dans la version 2, vous pouvez créer une instance GIcon à partir de G_DEFAULT_ICON type, puis la modifier. Si votre image est plus grande ou plus petite que l'icône par défaut, vous devez la spécifier avec une instance GSize. La version 3 de l'API simplifie légèrement ce processus. Il vous suffit de définir la propriété icon du repère sur l'URL de votre image personnalisée, et l'API redimensionne automatiquement l'icône.

L'API Maps JavaScript est également compatible avec les icônes complexes. Une icône complexe peut inclure plusieurs tuiles et formes complexes, ou spécifier "l'ordre d'empilement" des images par rapport aux autres superpositions. Pour ajouter une forme à un repère dans la version 2, vous devez spécifier la propriété supplémentaire dans chaque instance GIcon et la transmettre en tant qu'option à un constructeur GMarker. Dans la version 3, les icônes spécifiées de cette manière doivent définir leurs propriétés icon sur un objet de type Icon. Les ombres de marqueur ne sont pas prises en charge dans le version 3.

Les exemples suivants présentent un drapeau de plage sur la plage de Bondi, en Australie. Il n'est pas possible de cliquer sur la partie transparente de l'icône:

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
});

Polylignes

Une polyligne est constituée d'un tableau de valeurs LatLng et d'une série de segments de lignes, qui relient ces points géographiques dans une séquence ordonnée. La création et l'affichage d'un objet Polyline dans la version 3 sont semblables à l'utilisation d'un objet GPolyline dans la version 2. Les exemples suivants tracent une polyligne géodésique semi-transparente de 3 pixels de large de Zurich à Sydney en passant par Singapour:

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);

Polylignes encodées

Dans la version 3, il n'est pas possible de créer des objets Polyline directement à partir de polylignes encodées. Au lieu de cela, la bibliothèque de géométrie fournit des méthodes pour encoder et décoder les polylignes. Pour savoir comment charger cette bibliothèque, consultez Bibliothèques dans la version 3 de l'API Google Maps.

Les exemples ci-dessous dessinent la même polyligne encodée. Le code v3 utilise la méthode decodePath() de l'espace de noms 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);

Polygones

Un polygone définit une région dans une boucle fermée. Tout comme l'objet Polyline, les objets Polygon sont constitués d'une série de points dans une séquence ordonnée. La classe Polygon v3 est très semblable à la classe GPolygon v2, à une exception près : vous n'avez plus besoin de répéter le sommet de départ à la fin du chemin pour fermer la boucle. La version 3 de l'API ferme automatiquement tous les polygones en dessinant un trait qui relie la dernière coordonnée à la première. Les extraits de code suivants créent un polygone représentant le triangle des Bermudes:

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);

Formes modifiables par l'utilisateur

Les polylignes et les polygones peuvent être créés de manière à être modifiables par l'utilisateur. Les extraits de code suivants sont équivalents:

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

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

Pour des fonctionnalités de dessin plus avancées, consultez la bibliothèque de dessins dans la documentation de la version 3.

Fenêtres d'informations

Un InfoWindow affiche le contenu dans une fenêtre flottante au-dessus de la carte. Il y a plusieurs différences importantes entre les fenêtres d'info de la version 2 et de la version 3 :

• La version 2 de l'API n'accepte que les GInfoWindow par carte, tandis que la version 3 accepte plusieurs InfoWindow simultanés sur chaque carte.
• La version 3 de InfoWindow reste ouverte lorsque vous cliquez sur la carte. La version 2 de GInfoWindow se ferme automatiquement lorsque vous cliquez sur la carte. Vous pouvez émuler le comportement de la version 2 en ajoutant un écouteur click au niveau de l'objet Map.
• L'API v3 n'offre pas de compatibilité native avec un InfoWindow à onglets.

Superpositions au sol

Pour placer une image sur une carte, vous devez utiliser un objet GroundOverlay. Le constructeur d'une GroundOverlay est essentiellement le même dans les versions 2 et 3: il spécifie l'URL d'une image et les limites de l'image en tant que paramètres.

L'exemple suivant place une carte ancienne de Newark, New Jersey, sur la carte en tant que superposition:

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);

Types de carte courants

Les quatre types de carte basiques sont disponibles dans les versions 2 et 3 :

• MapTypeId.ROADMAP (remplace G_NORMAL_MAP) affiche la carte routière.
• MapTypeId.SATELLITE (remplace G_SATELLITE_MAP) affiche les images satellite de Google Earth.
• MapTypeId.HYBRID (remplace G_HYBRID_MAP) affiche à la fois des vues normales et des vues satellite.
• MapTypeId.TERRAIN (remplace G_PHYSICAL_MAP) affiche une carte physique en fonction des informations de relief.

Un exemple définissant la carte sur la vue de terrain dans les versions 2 et 3 est illustré ci-dessous :

map.setMapType(G_PHYSICAL_MAP);
    

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

L'API Maps JavaScript v3 a également apporté quelques modifications aux types de carte moins courants:

• Les tuiles de carte pour les corps célestes autres que la Terre ne sont pas disponibles en tant que types de carte dans l'API v3, mais sont accessibles en tant que types de carte personnalisés, comme illustré dans cet exemple.
• Aucun type de carte spécial dans la version 3 ne remplace le type G_SATELLITE_3D_MAP de la version 2. À la place, vous pouvez intégrer le plug-in Google Earth dans vos cartes v3 à l'aide de cette bibliothèque.

Maximum Zoom Imagery

Les images satellite ne sont pas toujours disponibles à des niveaux de zoom élevés. Si vous souhaitez connaître le niveau de zoom le plus élevé disponible avant de définir le niveau de zoom, utilisez la classe google.maps.MaxZoomService. Cette classe remplace la méthode GMapType.getMaxZoomAtLatLng() de la v2.

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.");
    }
});

Images aériennes en perspective

Lorsque vous activez les images aériennes dans la version 3, les commandes sont semblables à la commande GLargeZoomControl3D de la version 2, avec une commande de rotation interstitielle supplémentaire permettant une rotation dans les directions compatibles.

Vous pouvez suivre les villes pour lesquelles des images à 45° sont actuellement disponibles sur cette carte. Lorsque des images à 45° sont disponibles, une option de sous-menu est ajoutée au bouton Satellite de l'API Google Maps.