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, wie z. B. Mausklicks, werden vom DOM an die Maps JavaScript API weitergeleitet. Diese Ereignisse unterscheiden sich von standardmäßigen DOM-Ereignissen und werden separat verarbeitet.
• Benachrichtigungen zu MVC-Statusänderungen geben Aufschluss über Änderungen an Maps API-Objekten und werden einer property_changed-Konvention entsprechend benannt.

Jedes Maps-API-Objekt exportiert eine Anzahl benannter Ereignisse. Anwendungen, für die bestimmte Ereignisse benötigt werden, sollten Ereignis-Listener für die entsprechenden Ereignisse registrieren und Code ausführen, wenn die Ereignisse erfasst werden. Dieser ereignisgesteuerte Mechanismus ist in der Maps JavaScript API Version 2 und Version 3 identisch, mit der Ausnahme, dass sich der Namespace von GEvent in google.maps.event geändert hat:

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 sollten Sie einen Ereignis-Listener entfernen, wenn er nicht mehr benötigt wird. Das Entfernen eines Ereignislisteners funktioniert in Version 2 und Version 3 auf die gleiche Weise:

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

DOM-Ereignisse beobachten

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

Übergebene Argumente in Ereignissen

Bei UI-Ereignissen wird häufig ein Ereignisargument übergeben, auf das der Ereignis-Listener dann zugreifen kann. Die meisten Ereignisargumente in Version 3 wurden vereinfacht, um für Objekte in der API einheitlicher zu sein. Weitere Informationen finden Sie in der Referenz für Version 3.

In Ereignis-Listenern der Version 3 gibt es kein overlay-Argument. Wenn Sie ein click-Ereignis auf einer V3-Karte registrieren, erfolgt der Callback nur dann, wenn der Nutzer auf die Basiskarte klickt. Du kannst zusätzliche Callbacks für anklickbare Overlays registrieren, wenn du auf diese Klicks reagieren möchtest.

// 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

Mit der v3 API wurden einige Änderungen an control-Typen eingeführt.

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

Steuerelemente zur Karte hinzufügen

Mit der Maps JavaScript API 2 fügen Sie Ihrer Karte Steuerelemente über die addControl()-Methode Ihres Kartenobjekts hinzu. In Version 3 ändern Sie nicht mehr direkt die Steuerelemente, sondern das zugehörige MapOptions-Objekt. Im folgenden Beispiel wird gezeigt, wie die Karte angepasst wird, um die folgenden Steuerelemente hinzuzufü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);

Steuerelemente auf der Karte positionieren

Die Positionierung von Steuerelementen wurde in v3 erheblich geändert. In Version 2 nimmt die addControl()-Methode einen optionalen zweiten Parameter an, 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 das Attribut position der Steuerelementoptionen fest. Die Positionierung dieser Steuerelemente ist nicht absolut. Stattdessen ordnet die API die Steuerelemente auf intelligente Weise an. Dabei werden vorhandene Kartenelemente sowie die jeweiligen Einschränkungen (z. B. die Kartengröße) berücksichtigt. So wird die Kompatibilität der Standardsteuerelemente mit Ihren Steuerelementen sichergestellt. Weitere Informationen finden Sie unter Positionierung in Version 3 steuern.

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 V2 API anpassen möchten, müssen Sie eine Unterklasse der Klasse GControl erstellen und Handler für die Methoden initialize() und getDefaultPosition() definieren. In Version 3 gibt es kein Äquivalent für die Klasse GControl. Stattdessen werden Steuerelemente als DOM-Elemente dargestellt. Wenn Sie ein benutzerdefiniertes Steuerelement mit der V3 API hinzufügen möchten, erstellen Sie in einem Konstruktor eine DOM-Struktur für das Steuerelement als untergeordnetes Element eines Node (z.B. eines <div>-Elements) und fügen Sie Ereignis-Listener hinzu, um alle DOM-Ereignisse zu verarbeiten. Fügen Sie den Node in das controls[position]-Array der Karten ein, um der Karte eine Instanz des benutzerdefinierten Steuerelements hinzuzufügen.

Angenommen, es gibt eine HomeControl-Klassenimplementierung, die den oben genannten Anforderungen an die Benutzeroberfläche entspricht (weitere Informationen finden Sie in der Dokumentation zu benutzerdefinierten Steuerelementen). In den folgenden Codebeispielen wird gezeigt, wie einer Karte ein benutzerdefiniertes Steuerelement hinzugefügt wird.

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. Sie werden jedoch unterschiedlich behandelt.

In der v2 API wurden Overlays mithilfe der Methoden addOverlay() und removeOverlay() des GMap2-Objekts zur Karte hinzugefügt oder daraus entfernt. In Version 3 ordnen Sie einem Overlay über das Attribut map der zugehörigen Klasse mit Overlay-Optionen eine Karte 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 Sie die Karteneigenschaft auf null festlegen, wird das Overlay entfernt.

In Version 3 gibt es keine clearOverlays()-Methode. Wenn Sie mehrere Overlays verwalten möchten, erstellen Sie ein Array für die Overlays. Sie können dann setMap() für jedes Overlay im Array aufrufen und null übergeben, um sie zu entfernen.

Frei verschiebbare Markierungen

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 dem G_DEFAULT_ICON type erstellen und ändern. Wenn Ihr Bild 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. Legen Sie dazu einfach die Eigenschaft icon der Markierung auf die URL Ihres benutzerdefinierten Bildes fest. Die API passt die Größe des Symbols dann automatisch an.

Die Maps JavaScript API unterstützt auch komplexe Symbole. Ein komplexes Symbol kann mehrere Kacheln, komplexe Formen oder die „Stapelreihenfolge“ für die Anzeige der Bilder im Verhältnis zu anderen Overlays enthalten. 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 sie als Option an einen GMarker-Konstruktor übergeben. In Version 3 sollten für Symbole, die so definiert werden, die icon-Eigenschaften auf ein Objekt vom Typ Icon festgelegt werden. Markerschatten werden in v3 nicht unterstützt.

In den folgenden Beispielen ist eine Strandflagge am Bondi Beach in Australien zu sehen. Der transparente Teil des Symbols ist nicht anklickbar:

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 sowie einer Reihe von Liniensegmenten, die diese Orte in einer geordneten Reihenfolge miteinander verbinden. Das Erstellen und Darstellen eines Polyline-Objekts in Version 3 ähnelt der Verwendung eines GPolyline-Objekts in Version 2. In den folgenden Beispielen wird eine halbtransparente, 3 Pixel breite geodätische Polylinie von Zürich über Singapur 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 Erstellen von Polyline-Objekten direkt aus codierten Polylinien nicht unterstützt. Stattdessen bietet die Geometry Library Methoden zum Codieren und Decodieren von Polylinien. Weitere Informationen zum Laden dieser Bibliothek finden Sie unter Bibliotheken in der Maps API v3.

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 Klasse Polygon von Version 3 ähnelt der Klasse GPolygon von Version 2, mit der wichtigen Ausnahme, dass der Startknoten am Ende des Pfads nicht mehr wiederholt werden muss, um den Kreis zu schließen. Die V3 API schließt alle Polygone automatisch, indem ein Strich gezogen wird, der die letzte Koordinate mit der ersten 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);

Weitere Informationen zu erweiterten Zeichenfunktionen finden Sie in der Drawing Library in der V3-Dokumentation.

Infofenster

Mit einem InfoWindow werden Inhalte in einem schwebenden Fenster über der Karte angezeigt. Zwischen den Info-Fenstern in v2 und v3 gibt es einige wesentliche Unterschiede:

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

Boden-Overlays

Wenn Sie ein Bild auf einer Karte platzieren möchten, sollten Sie ein GroundOverlay-Objekt verwenden. Der Konstruktor für ein GroundOverlay ist in Version 2 und Version 3 im Wesentlichen identisch: Er gibt eine Bild-URL und die Grenzen des Bilds als Parameter an.

Im folgenden Beispiel wird eine antike Karte von Newark, New Jersey, als Overlay auf die Karte gelegt:

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

Typische Kartentypen

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

• MapTypeId.ROADMAP (ersetzt G_NORMAL_MAP) zeigt die Straßenkarte an.
• MapTypeId.SATELLITE (ersetzt G_SATELLITE_MAP) zeigt Google Earth-Satellitenbilder an.
• MapTypeId.HYBRID (ersetzt G_HYBRID_MAP) zeigt eine Mischung aus normalen und Satellitenbildern an.
• MapTypeId.TERRAIN (ersetzt G_PHYSICAL_MAP) zeigt eine physische Karte an, die auf Geländedaten beruht.

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

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

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

Maximum Zoom Imagery

Satellitenbilder sind auf großen Vergrößerungsstufen nicht immer verfügbar. Wenn Sie vor dem Festlegen der Zoomstufe wissen möchten, welche maximale Zoomstufe verfügbar ist, verwenden Sie die Klasse google.maps.MaxZoomService. Diese Klasse ersetzt die GMapType.getMaxZoomAtLatLng()-Methode 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.");
    }
});

Perspektivische Luftbilder

Wenn Sie in v3 Flugaufnahmen aktivieren, ähneln die Steuerelemente dem Steuerelement GLargeZoomControl3D aus v2. Zusätzlich gibt es noch das Zwischensteuerelement „Rotate“ zum Drehen in die unterstützten Richtungen.

Auf dieser Karte können Sie sehen, in welchen Städten derzeit 45°-Bilder verfügbar sind. Wenn Bilder mit einem Blickwinkel von 45 Grad verfügbar sind, wird der Schaltfläche „Satellitenbilder“ der Maps API ein Untermenü hinzugefügt.