Maps JavaScript API-Anwendung von Version 2 auf Version 3 aktualisieren

Neues Ereignis zur Unterstützung von MVC

Die API v3 enthält eine neue Art von Ereignis, um Änderungen des MVC-Zustands darzustellen. Es gibt jetzt zwei Arten von Ereignissen:

• Nutzerereignisse, z. B. Mausklicks, werden vom DOM an die Maps JavaScript API weitergegeben. Diese Ereignisse sind separate Ereignisse, die sich von standardmäßigen DOM-Ereignissen unterscheiden.
• Benachrichtigungen über MVC-Statusänderungen geben Aufschluss über Änderungen an Google Maps API-Objekten und werden nach der property_changed-Konvention benannt.

Mit jedem Maps API-Objekt wird eine Anzahl benannter Ereignisse exportiert. Für Anwendungen, die bestimmte Ereignisse benötigen, sollten Ereignis-Listener für diese Ereignisse registriert und Code ausgeführt werden, wenn diese Ereignisse empfangen werden. Dieser ereignisgesteuerte Mechanismus ist in Version 2 und 3 der Maps JavaScript API identisch mit dem Unterschied, dass der Namespace von GEvent in google.maps.event geändert wurde:

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

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

Event-Listener entfernen

Aus Leistungsgründen empfiehlt es sich, einen nicht mehr benötigten Event-Listener zu entfernen. Das Entfernen eines Event-Listeners funktioniert in v2 und v3 auf dieselbe Weise:

1. Wenn Sie einen Event-Listener erstellen, wird ein intransparentes Objekt zurückgegeben (GEventListener in Version 2, MapsEventListener in Version 3).
2. Wenn Sie den Event-Listener entfernen möchten, übergeben Sie dieses Objekt an die removeListener()-Methode (GEvent.removeListener() in V2 oder google.maps.event.removeListener() in V3), um den Event-Listener zu entfernen.

Auf DOM-Ereignisse warten

Wenn Sie DOM-Ereignisse (Document Object Model) erfassen und darauf reagieren möchten, bietet v3 die statische Methode google.maps.event.addDomListener(), die der Methode GEvent.addDomListener() in Version 2 entspricht.

Übergebene Argumente in Ereignissen

UI-Ereignisse übergeben häufig ein Ereignisargument, auf das der Ereignis-Listener zugreifen kann. Die meisten Ereignisargumente in v3 wurden vereinfacht, damit sie gegenüber Objekten in der API konsistenter sind. Weitere Informationen finden Sie in der v3-Referenz.

In den Ereignis-Listenern von Version 3 ist kein overlay-Argument vorhanden. Wenn Sie auf einer Karte in Version 3 ein click-Ereignis registrieren, erfolgt der Callback nur dann, wenn der Nutzer auf die Basiskarte klickt. Sie können zusätzliche Callbacks für anklickbare Overlays registrieren, wenn Sie auf diese Klicks reagieren müssen.

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

Änderungen an Steuerelementtypen

Einige Änderungen an den control-Typen wurden mit der API v3 eingeführt.

1. Version 3 der API unterstützt zusätzliche Kartentypen wie Geländekarten und die Möglichkeit, benutzerdefinierte Kartentypen hinzuzufügen.
2. Das hierarchische V2-Steuerelement GHierarchicalMapTypeControl ist nicht mehr verfügbar. Mit dem Steuerelement google.maps.MapTypeControlStyle.HORIZONTAL_BAR können Sie einen ähnlichen Effekt erzielen.
3. Das von GMapTypeControl in Version 2 bereitgestellte horizontale Layout ist in Version 3 nicht verfügbar.

Steuerelemente zur Karte hinzufügen

In der Maps JavaScript API Version 2 würden Sie Ihrer Karte über die Methode addControl() des Kartenobjekts Steuerelemente hinzufügen. In v3 ändern Sie das verknüpfte MapOptions-Objekt, anstatt direkt auf Steuerelemente zuzugreifen oder sie zu ändern. Im folgenden Beispiel sehen Sie, wie Sie die Karte anpassen und die folgenden Steuerelemente hinzufügen:

• Schaltflächen, über die der Nutzer zwischen den verfügbaren Kartentypen wechselt
• Eine Kartenskalierung

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

Positionierung von Steuerelementen auf der Karte

Die Positionierung von Steuerelementen wurde in v3 erheblich geändert. In Version 2 wird für die Methode addControl() ein optionaler zweiter Parameter verwendet, mit dem Sie die Position des Steuerelements relativ zu den Ecken der Karte angeben können.

In Version 3 legen Sie die Position eines Steuerelements über die Eigenschaft position der Optionen für Steuerelemente fest. Die Positionierung dieser Steuerelemente ist nicht absolut. Stattdessen werden die Steuerelemente von der API intelligent um vorhandene Kartenelemente innerhalb der jeweiligen Einschränkungen (z. B. der Kartengröße) angeordnet. So wird die Kompatibilität der Standardsteuerelemente mit Ihren Steuerelementen sichergestellt. Weitere Informationen finden Sie unter Positionierung der Steuerelemente in Version 3.

Im folgenden Code werden die Steuerelemente der obigen Beispiele neu positioniert:

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

Benutzerdefinierte Steuerelemente

Mit der Maps JavaScript API können Sie benutzerdefinierte Navigationssteuerelemente erstellen. Wenn Sie Steuerelemente mit der API V2 anpassen möchten, müssen Sie eine abgeleitete Klasse der Klasse GControl erstellen und Handler für die Methoden initialize() und getDefaultPosition() definieren. In Version 3 gibt es kein Äquivalent zur Klasse GControl. Stattdessen werden Steuerelemente als DOM-Elemente dargestellt. Wenn Sie ein benutzerdefiniertes Steuerelement mit der API v3 hinzufügen möchten, erstellen Sie eine DOM-Struktur für das Steuerelement in einem Konstruktor als untergeordnetes Element eines Node-Elements (z.B. eines <div>-Elements) und fügen Sie Ereignis-Listener hinzu, um DOM-Ereignisse zu verarbeiten. Übertragen Sie Node in das controls[position]-Array der Karte, um der Karte eine Instanz des benutzerdefinierten Steuerelements hinzuzufügen.

Bei einer HomeControl-Klassenimplementierung, die die oben genannten Schnittstellenanforderungen erfüllt (weitere Informationen finden Sie in der Dokumentation zu benutzerdefinierten Steuerelementen), zeigen die folgenden Codebeispiele, wie Sie einer Karte ein benutzerdefiniertes Steuerelement hinzufügen.

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

Overlays hinzufügen und entfernen

Die Objekttypen, die durch ein Overlay dargestellt werden, sind in Version 2 und Version 3 identisch, werden aber unterschiedlich gehandhabt.

Die Overlays in der Version 2 der API wurden der Karte mit den Methoden addOverlay() und removeOverlay() des GMap2-Objekts hinzugefügt und daraus entfernt. In Version 3 weisen Sie einem Overlay eine Karte über die Eigenschaft map der zugehörigen Klasse der Overlay-Optionen zu. Sie können ein Overlay auch direkt hinzufügen oder entfernen, indem Sie die Methode setMap() des Overlay-Objekts aufrufen und die gewünschte Karte angeben. Wenn die Karteneigenschaft auf null gesetzt wird, wird das Overlay entfernt.

In Version 3 gibt es keine clearOverlays()-Methode. Wenn Sie eine Gruppe von Overlays verwalten möchten, erstellen Sie ein Array für die Overlays. Mithilfe dieses Arrays können Sie dann setMap() für jedes Overlay im Array aufrufen und null übergeben, wenn Sie sie entfernen müssen.

Ziehbare Marker

Marker sind standardmäßig klickbar, aber nicht ziehbar. In den folgenden beiden Beispielen wird eine ziehbare Markierung hinzugefügt:

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

Symbole

Sie können ein benutzerdefiniertes Icon festlegen, das anstelle des Standardmarkers angezeigt wird. Wenn Sie ein benutzerdefiniertes Image in V2 verwenden möchten, können Sie eine GIcon-Instanz aus G_DEFAULT_ICON type erstellen und ändern. Wenn das Image größer oder kleiner als das Standardsymbol ist, müssen Sie es mit einer GSize-Instanz angeben. Dieser Prozess wird in der API v3 ein wenig vereinfacht. Dazu setzen Sie einfach die Eigenschaft icon der Markierung auf die URL des benutzerdefinierten Bildes und die API passt die Größe des Symbols automatisch an.

Die Maps JavaScript API unterstützt auch komplexe Symbole. Ein komplexes Symbol kann mehrere Kacheln und komplexe Formen enthalten oder die „Stapelreihenfolge“ für die Anzeige von Bildern im Verhältnis zu anderen Overlays angeben. Wenn Sie einer Markierung in Version 2 eine Form hinzufügen möchten, müssen Sie die zusätzliche Eigenschaft in jeder GIcon-Instanz angeben und als Option an einen GMarker-Konstruktor übergeben. In Version 3 sollte für Symbole, die so angegeben werden, die icon-Eigenschaften auf ein Objekt des Typs Icon festgelegt werden. Markerschatten werden in v3 nicht unterstützt.

In den folgenden Beispielen wird eine Strandflagge am Bondi Beach in Australien angezeigt, wobei der transparente Teil des Symbols nicht anklickbar ist:

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

Polylinien

Eine Polylinie besteht aus einem Array von LatLngs und einer Folge von Liniensegmenten, die diese Orte in einer geordneten Reihenfolge verbinden. Das Erstellen und Anzeigen eines Polyline-Objekts in v3 ähnelt dem Erstellen und Anzeigen eines GPolyline-Objekts in v2. In den folgenden Beispielen wird eine halbtransparente, 3 Pixel breite, geodätische Polylinie über Singapur von Zürich nach Sydney gezeichnet:

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

Kodierte Polylinien

In Version 3 wird das direkte Erstellen von Polyline-Objekten aus codierten Polylinien nicht unterstützt. Methoden zum Codieren und Decodieren von Polylinien finden Sie stattdessen in der Geometriebibliothek. Weitere Informationen zum Laden dieser Bibliothek finden Sie unter Bibliotheken in der Maps API Version 3.

In den folgenden Beispielen wird dieselbe codierte Polylinie gezeichnet. Im V3-Code wird die Methode decodePath() aus dem Namespace google.maps.geometry.encoding verwendet.

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

Polygone

Ein Polygon definiert einen Bereich in einem geschlossenen Rahmen. Ähnlich wie das Polyline-Objekt bestehen Polygon-Objekte aus einer Reihe von Punkten in einer geordneten Reihenfolge. Die Polygon-Klasse von Version 3 entspricht weitgehend der Klasse GPolygon der Version 2, mit der Ausnahme, dass Sie den Startpunkt am Ende des Pfads nicht mehr wiederholen müssen, um die Schleife zu schließen. In Version 3 der API werden alle Polygone automatisch geschlossen. Dazu wird ein Strich gezogen, der die letzte Koordinate mit der ersten Koordinate verbindet. Mit den folgenden Code-Snippets wird ein Polygon erstellt, das das Bermudadreieck darstellt:

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

Vom Nutzer bearbeitbare Formen

Polylinien und Polygone lassen sich so definieren, dass sie vom Nutzer bearbeitet werden können. Die folgenden Code-Snippets sind äquivalent:

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

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

Informationen zu erweiterten Zeichenfunktionen finden Sie in der Dokumentation zu Version 3 in der Drawing-Bibliothek.

Infofenster

Ein InfoWindow zeigt Inhalte in einem unverankerten Fenster über der Karte an. Zwischen den Info-Fenstern in v2 und v3 gibt es einige wesentliche Unterschiede:

• API V2 unterstützt nur GInfoWindow pro Karte, Version 3 der API mehrere, gleichzeitige InfoWindows auf jeder Karte.
• InfoWindow von Version 3 bleibt geöffnet, wenn Sie auf die Karte klicken. GInfoWindow von Version 2 wird automatisch geschlossen, wenn Sie auf die Karte klicken. Sie können das V2-Verhalten emulieren, indem Sie dem Map-Objekt einen click-Listener hinzufügen.
• Die API V3 bietet keine native Unterstützung für InfoWindow mit Tabs.

Boden-Overlays

Um ein Bild auf einer Karte zu platzieren, sollten Sie ein GroundOverlay-Objekt verwenden. Der Konstruktor für ein GroundOverlay ist in v2 und v3 im Wesentlichen der gleiche: Er gibt die URL eines Bildes und die Begrenzungen des Bildes als Parameter an.

Im folgenden Beispiel wird eine antike Karte von Newark, NJ, als Overlay auf der Karte platziert:

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

Gängige Kartentypen

Die vier Basiskartentypen sind sowohl in v2 als auch in v3 verfügbar:

• MapTypeId.ROADMAP (ersetzt G_NORMAL_MAP) zeigt die Straßenkartenansicht an.
• MapTypeId.SATELLITE (ersetzt G_SATELLITE_MAP) zeigt Google Earth-Satellitenbilder an.
• MapTypeId.HYBRID (ersetzt G_HYBRID_MAP) zeigt eine Mischung aus der normalen und der Satellitenansicht an.
• MapTypeId.TERRAIN (ersetzt G_PHYSICAL_MAP) zeigt eine physische Karte an, die auf Geländeinformationen basiert.

Im nachfolgenden Beispiel wird die Karte in v2 und v3 auf die Geländeansicht gesetzt:

map.setMapType(G_PHYSICAL_MAP);
    

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

In Version 3 der Maps JavaScript API wurden auch einige Änderungen an den weniger gängigen Kartentypen vorgenommen:

• Kartenkacheln für andere Himmelskörper als die Erde sind in Version 3 der API nicht als Kartentypen verfügbar. Sie können aber wie in diesem Beispiel gezeigt als benutzerdefinierte Kartentypen aufgerufen werden.
• In Version 3 gibt es keinen speziellen Kartentyp, der den G_SATELLITE_3D_MAP-Typ aus Version 2 ersetzt. Stattdessen können Sie das Google Earth-Plug-in mithilfe dieser Bibliothek in Ihre Karten der Version 3 einbinden.

Maximum Zoom Imagery

Satellitenbilder sind auf großen Vergrößerungsstufen nicht immer verfügbar. Wenn Sie die höchste verfügbare Zoomstufe ermitteln möchten, bevor Sie die Zoomstufe festlegen, verwenden Sie die Klasse google.maps.MaxZoomService. Diese Klasse ersetzt die Methode GMapType.getMaxZoomAtLatLng() aus 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.");
    }
});

Luftbilder

Beim Aktivieren von Flugaufnahmen in Version 3 ähneln die Steuerelemente dem GLargeZoomControl3D-Steuerelement aus Version 2. Es gibt jedoch eine zusätzliche Interstitial-Steuerung zum Drehen, die die Drehung in die unterstützten Richtungen ermöglicht.

Auf dieser Karte sehen Sie die Städte, für die derzeit 45°-Bilder verfügbar sind. Wenn 45°-Bilder verfügbar sind, wird der Satellitenschaltfläche der Maps API eine Untermenüoption hinzugefügt.