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. „click“-Mausereignisse werden vom DOM an die Maps JavaScript API weitergegeben. Diese Ereignisse sind unabhängig von den standardmäßigen DOM-Ereignissen.
• Benachrichtigungen über MVC-Statusänderungen geben Aufschluss über Änderungen an Google Maps API-Objekten und werden entsprechend der property_changed-Konvention benannt.

Mit jedem Maps API-Objekt wird eine Anzahl benannter Ereignisse exportiert. Anwendungen, die sich für bestimmte Ereignisse interessieren, sollten Ereignis-Listener für diese Ereignisse registrieren und Code ausführen, wenn diese Ereignisse empfangen werden. Dieser ereignisgesteuerte Mechanismus ist in Version 2 und 3 der Maps JavaScript API identisch. Der einzige Unterschied besteht darin, dass der Namespace von GEvent zu 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.');
});

Ereignislistener entfernen

Aus Leistungsgründen ist es am besten, einen Ereignis-Listener zu entfernen, wenn er nicht mehr benötigt wird. Das Entfernen eines Ereignis-Listeners funktioniert in v2 und v3 auf dieselbe Weise:

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

Reaktionen auf DOM-Ereignisse

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

UI-Ereignisse übergeben häufig ein Ereignisargument, auf das der Ereignis-Listener zugreifen kann. Die meisten Ereignisargumente in Version 3 wurden vereinfacht, um Objekte in der API einheitlicher zu machen. Weitere Informationen finden Sie in der V3-Referenz.

In v3-Ereignis-Listenern ist kein Argument overlay vorhanden. Wenn du ein click-Ereignis auf einer v3-Karte registrierst, erfolgt der Callback nur, wenn der Nutzer auf die Basiskarte klickt. Du kannst zusätzliche Callbacks für anklickbare Overlays registrieren, wenn du auf diese Klicks reagieren musst.

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

In der API V3 wurden einige Änderungen an control-Typen eingeführt.

1. Die API v3 unterstützt zusätzliche Kartentypen, einschließlich Geländekarten und die Möglichkeit, benutzerdefinierte Kartentypen hinzuzufügen.
2. Das hierarchische Steuerelement V2 (GHierarchicalMapTypeControl) ist nicht mehr verfügbar. Einen ähnlichen Effekt erzielen Sie mit dem Steuerelement google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Das horizontale Layout von GMapTypeControl in Version 2 ist in Version 3 nicht verfügbar.

Steuerelemente zur Karte hinzufügen

Mit der Maps JavaScript API Version 2 kannst du deiner Karte Steuerelemente hinzufügen, die über die Methode addControl() deines Kartenobjekts ausgeführt werden. In Version 3 ändern Sie das verknüpfte MapOptions-Objekt, anstatt direkt auf Steuerelemente zuzugreifen oder diese zu ändern. 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);

Positionierung von Steuerelementen auf der Karte

Die Positionierung von Steuerelementen wurde in v3 erheblich geändert. In Version 2 verwendet die Methode addControl() einen optionalen zweiten Parameter, mit dem Sie die Position des Steuerelements in Bezug auf die Ecken der Karte festlegen können.

In v3 legen Sie die Position eines Steuerelements über das Attribut position der Steuerelementoptionen fest. Die Positionierung der Steuerelemente ist nicht absolut. Stattdessen werden die Steuerelemente von der API intelligent mithilfe der fließenden Elemente innerhalb vorhandener Einschränkungen wie der Kartengröße angeordnet. So wird die Kompatibilität der Standardsteuerelemente mit Ihren Steuerelementen sichergestellt. Weitere Informationen finden Sie unter Steuerung der Positionierung in v3.

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. Zum Anpassen der Steuerelemente mit der API V2 würden Sie die Klasse GControl erstellen und Handler für die Methoden initialize() und getDefaultPosition() definieren. In Version 3 gibt es keine Entsprechung für die Klasse GControl. Stattdessen werden Steuerelemente als DOM-Elemente dargestellt. Zum Hinzufügen eines benutzerdefinierten Steuerelements mit der v3 API erstellen Sie eine DOM-Struktur für das Steuerelement in einem Konstruktor als untergeordnetes Element eines Node (z.B. ein <div>-Element) und fügen Ereignis-Listener zum Verarbeiten von DOM-Ereignissen hinzu. Übertragen Sie Node in das Maps-Array controls[position], 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 durch ein Overlay dargestellten Objekttypen sind in v2 und v3 identisch. Sie werden jedoch anders behandelt.

Overlays in der v2 API wurden mit den Methoden addOverlay() und removeOverlay() des Objekts GMap2 zur Karte hinzugefügt und daraus entfernt. In Version 3 weisen Sie eine Karte über die Property map der zugehörigen Overlay-Optionsklasse einem Overlay zu. Du kannst ein Overlay auch direkt hinzufügen oder entfernen. Rufe dazu die Methode setMap() des Overlay-Objekts auf und gib die gewünschte Karte an. Wenn das Kartenattribut auf null gesetzt ist, wird das Overlay entfernt.

In Version 3 ist keine clearOverlays()-Methode vorhanden. Wenn Sie eine Gruppe von Overlays verwalten möchten, sollten Sie ein Array erstellen, das die Overlays enthält. Mit diesem Array können Sie dann setMap() für jedes Overlay im Array aufrufen und null übergeben, wenn Sie es entfernen möchten.

Ziehbare Marker

Marker sind standardmäßig klickbar, aber nicht ziehbar. In den folgenden beiden Beispielen wird eine dragbare 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 in Version 2 ein benutzerdefiniertes Image verwenden möchten, können Sie eine GIcon-Instanz aus G_DEFAULT_ICON type erstellen und ändern. Wenn das 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 icon-Property der Markierung auf die URL Ihres benutzerdefinierten Bilds fest 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 umfassen oder angeben, wie die Bilder im Verhältnis zu anderen Overlays angezeigt werden sollen. Wenn Sie einer Markierung in Version 2 eine Form hinzufügen möchten, müssen Sie das zusätzliche Attribut in jeder GIcon-Instanz angeben und diese als Option an einen GMarker-Konstruktor übergeben. In v3 sollten auf diese Weise angegebene Symbole ihre icon-Eigenschaften auf ein Objekt des Typs Icon gesetzt werden. Markerschatten werden in v3 nicht unterstützt.

Die folgenden Beispiele zeigen eine Strandflagge am Bondi Beach in Australien, 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 Reihe von Liniensegmenten, die diese Orte in einer geordneten Reihenfolge miteinander verbinden. Das Erstellen und Anzeigen eines Polyline-Objekts in v3 ähnelt dem Verwenden eines GPolyline-Objekts in v2. In den folgenden Beispielen wird eine halbtransparente, 3 Pixel breite, geodätische Polylinie von Zürich nach Sydney über Singapur 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 Version 3.

In den folgenden Beispielen wird dieselbe codierte Polylinie dargestellt. Der v3-Code verwendet die Methode decodePath() aus dem Namespace 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);

Polygone

Ein Polygon definiert einen Bereich in einem geschlossenen Rahmen. Ähnlich wie das Objekt Polyline bestehen Polygon-Objekte aus einer Reihe von Punkten in einer geordneten Reihenfolge. Die Polygon-Klasse von v3 entspricht weitgehend der GPolygon-Klasse von v2. Die einzige Ausnahme ist, dass Sie den Eckpunkt am Ende des Pfads nicht mehr wiederholen müssen, um die Schleife zu schließen. Die v3 API schließt automatisch alle Polygone, indem ein Strich gezogen wird, 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);

Weitere Funktionen zum Zeichnen finden Sie in der v3-Dokumentation unter Zeichnungsbibliothek.

Infofenster

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

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

Boden-Overlays

Verwenden Sie ein GroundOverlay-Objekt, um ein Bild auf einer Karte zu platzieren. Der Konstruktor für ein GroundOverlay-Element ist in v2 und v3 im Wesentlichen identisch. Er gibt als Parameter die URL eines Bildes und die Grenzen des Bildes 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ßenansicht 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.
• MapTypeId.TERRAIN (ersetzt G_PHYSICAL_MAP) zeigt eine physische Karte basierend auf Geländeinformationen.

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 der Maps JavaScript API Version 3 wurden außerdem einige Änderungen an den weniger gängigen Kartentypen vorgenommen:

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

Maximale Bildvergrößerung

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

Luftbilder

Wenn Sie die Luftaufnahmen in Version 3 aktivieren, ähneln die Steuerelemente dem Steuerelement GLargeZoomControl3D in Version 2. Zusätzlich gibt es ein Steuerelement zum Drehen von Interstitials, mit dem Sie die Kamera in die unterstützten Richtungen drehen können.

Auf dieser Karte kannst du sehen, in welchen Städten 45°-Bilder verfügbar sind. Wenn 45°-Bilder verfügbar sind, wird der Satelliten-Schaltfläche der Maps API eine Untermenüoption hinzugefügt.