Mettre à jour votre application API Maps JavaScript vers 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 (tels que les événements de clic et de souris) sont transmis du DOM à l'API Maps JavaScript. Ces événements sont différents des événements DOM standards.
• 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 une 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 lors de leur réception. Ce mécanisme basé sur des événements est le même dans les versions 2 et 3 de l'API Maps JavaScript, à la différence 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) pour supprimer l'écouteur d'événements.

Écouter les événements DOM

Si vous souhaitez capturer des événements DOM (Document Object Model) et y répondre, la v3 fournit la méthode statique google.maps.event.addDomListener(), qui équivaut à 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énement 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 sur 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 ne se produit 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 la version 3 de l'API.

1. La version 3 de l'API accepte d'autres types de carte, y compris des cartes de relief et la possibilité d'ajouter des types de carte personnalisés.
2. Le contrôle hiérarchique de la version 2, GHierarchicalMapTypeControl, n'est plus disponible. Vous pouvez obtenir le même résultat à l'aide de 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 devez ajouter des commandes à votre carte via la méthode addControl() de votre objet de carte. Dans la version 3, vous modifiez l'objet MapOptions associé au lieu d'accéder directement aux commandes ou de les modifier. 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 la commande. Le positionnement de ces commandes n'est pas absolu. En effet, l'API les met en page de manière intelligente par "flux" autour des éléments existants dans la carte en fonction de contraintes spécifiques (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 la page 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(). Dans la version 3, il n'existe pas d'équivalent à la classe GControl. Les commandes sont plutôt représentées par des éléments DOM. Pour ajouter une commande personnalisée à l'aide de l'API v3, créez une structure DOM pour la commande dans un constructeur en tant qu'enfant d'un élément Node (par exemple, un élément <div>) et ajoutez des écouteurs d'événements pour gérer les événements DOM. Intégrez Node dans le tableau controls[position] pour ajouter une instance de la commande personnalisée à votre carte.

Avec une implémentation de classe HomeControl qui respecte les exigences de l'interface mentionnées ci-dessus (pour en savoir plus, consultez la documentation sur les contrôles personnalisés), 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 pour les versions 2 et 3, mais gérés différemment.

Dans la version 2, 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éfinissez la propriété de la carte sur null pour supprimer 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 ajustera automatiquement la taille de l'icône.

L'API Maps JavaScript est également compatible avec les icônes complexes. Une icône complexe peut inclure plusieurs tuiles et des formes complexes, ou spécifier l'ordre d'empilement de l'affichage des images par rapport à d'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 à Bondi Beach en Australie, et la partie transparente de l'icône n'est 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 se compose d'un tableau de LatLng et d'une série de segments de ligne qui relient ces emplacements dans une séquence ordonnée. Dans la version 3, la création et l'affichage d'un objet Polyline sont semblables à l'utilisation d'un objet GPolyline dans la version 2. Les exemples suivants dessinent une polyligne géodésique et 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. La bibliothèque Geometry fournit des méthodes d'encodage et de décodage des polylignes. Pour en savoir plus sur le chargement de cette bibliothèque, consultez la section 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 consistent en une série de points dans une séquence ordonnée. La classe Polygon de la version 3 est à peu près identique à la classe GPolygon de la version 2, à ceci près 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 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 bénéficier de fonctionnalités de dessin plus avancées, consultez la bibliothèque de dessins dans la documentation de la version 3.

Fenêtres d'informations

Une 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'accepte que GInfoWindow par carte, tandis que l'API v3 n'accepte que plusieurs InfoWindow simultanées sur chaque carte.
• La version 3 de InfoWindow restera ouverte lorsque vous cliquerez 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 sur l'objet Map.
• L'API v3 n'est pas compatible en natif avec les 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 de la route.
• 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 en fonction des informations sur le 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 les moins courants:

• Les tuiles de carte pour les corps célestes autres que Earth 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 indiqué dans cet exemple.
• Dans la version 3, il n'existe pas de type de carte spécial qui remplace le type de carte 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 commande GLargeZoomControl3D de la version 2, avec une commande de rotation des interstitiels interstitielle supplémentaire qui permet de faire pivoter l'appareil 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.