Mettre à niveau l'application API Maps JavaScript de la version 2 à la version 3

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 (comme 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 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, à l'exception du fait que le nom d'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énement 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) pour le supprimer.

Écouter les événements DOM

Si vous souhaitez capturer et répondre aux événements DOM (Document Object Model), la version 3 fournit la méthode statique google.maps.event.addDomListener(), équivalente à la méthode GEvent.addDomListener() de 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. La plupart des arguments d'événement de la version 3 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 version 3.)

Aucun argument overlay n'existe dans les écouteurs d'événements de la version 3. Si vous enregistrez un événement click sur une carte v3, le rappel ne se produira que lorsque l'utilisateur cliquera 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

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

1. L'API v3 est compatible avec d'autres types de cartes, y compris les cartes de relief et la possibilité d'ajouter des types de cartes personnalisés.
2. Le contrôle hiérarchique v2, GHierarchicalMapTypeControl, n'est plus disponible. Vous pouvez obtenir un effet similaire à l'aide du contrôle 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 la version 2 de l'API Maps JavaScript, vous ajoutez des commandes à votre carte via la méthode addControl() de votre objet carte. Dans la version 3, au lieu d'accéder ou de modifier directement les commandes, vous modifiez 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 coins 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. L'API les positionnera donc de manière intelligente autour des éléments existants sur la carte, dans les limites données (comme 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 Contrôler le positionnement 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 les commandes avec l'API v2, 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. À la place, les commandes sont représentées par des éléments DOM. Pour ajouter un contrôle personnalisé avec l'API v3, créez une structure DOM pour le contrôle 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] des cartes pour ajouter une instance de la commande personnalisée à votre carte.

Étant donné une implémentation de classe HomeControl conforme aux exigences d'interface indiquées ci-dessus (pour en savoir plus, consultez la documentation sur les commandes personnalisées), 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 les mêmes entre les versions 2 et 3, mais ils sont gérés différemment.

Les superpositions de l'API V2 ont été ajoutées et supprimées de la carte à 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 superposition et en spécifiant la carte souhaitée. Définir la propriété de la 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 et 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. L'API redimensionnera automatiquement l'icône.

L'API Maps JavaScript est également compatible avec les icônes complexes. Une icône complexe peut inclure plusieurs cartes, des 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 affichent un drapeau de plage sur la plage de Bondi en Australie, la partie transparente de l'icône n'étant pas cliquable:

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 composée d'un tableau d'LatLng, ainsi que d'une série de segments de ligne qui relient ces emplacements dans une séquence ordonnée. La création et l'affichage d'un objet Polyline dans la version 3 est semblable à l'utilisation d'un objet GPolyline dans la version 2. Les exemples suivants dessinent 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

La version 3 ne permet pas de créer d'objets Polyline directement à partir de polylignes encodées. À la place, la bibliothèque de géométrie fournit des méthodes permettant d'encoder et de décoder des polylignes. Pour savoir comment charger cette bibliothèque, consultez la section Bibliothèques de l'API Maps v3.

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 composé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, à l'exception notable que vous n'avez plus besoin de répéter le sommet de départ à la fin du chemin pour fermer la boucle. L'API v3 ferme automatiquement tous les polygones en dessinant un trait reliant 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 en savoir plus sur les fonctionnalités de dessin avancées, consultez la bibliothèque de dessins dans la documentation de la version 3.

Fenêtres d'informations

Un InfoWindow affiche du 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 :

• L'API v2 n'est compatible qu'avec un seul GInfoWindow par carte, tandis que l'API v3 accepte plusieurs InfoWindow simultanés sur chaque carte.
• La InfoWindow v3 reste ouverte lorsque vous cliquez sur la carte. La GInfoWindow v2 se ferme automatiquement lorsque vous cliquez sur la carte. Vous pouvez émuler le comportement de la version 2 en ajoutant un écouteur click à l'objet Map.
• L'API v3 n'est pas compatible en mode natif avec un InfoWindow à onglets.

Superpositions au sol

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

L'exemple suivant place une ancienne carte de Newark (New Jersey) sur la carte en 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 vue de la carte routière.
• MapTypeId.SATELLITE (remplace G_SATELLITE_MAP) affiche les images satellites de Google Earth.
• MapTypeId.HYBRID (remplace G_HYBRID_MAP) affiche une combinaison de vues normales et de vues satellite.
• MapTypeId.TERRAIN (remplace G_PHYSICAL_MAP) affiche une carte physique basée sur les informations de terrain.

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

La version 3 de l'API Maps JavaScript a également apporté quelques modifications aux types de cartes les 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 peuvent être accessibles en tant que types de carte personnalisés, comme illustré dans cet exemple.
• Il n'existe aucun type de carte spécial dans la version 3 qui 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 version 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.");
    }
});

Images aériennes en perspective

Lorsque vous activez les images aériennes dans la version 3, les commandes sont semblables à celles de la version 2, avec une commande de rotation interstitielle supplémentaire pour faire pivoter l'image dans les directions compatibles.GLargeZoomControl3D

Vous pouvez suivre les villes dans lesquelles les 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 Maps.