Uaktualnianie aplikacji korzystającej z interfejsu Maps JavaScript API z wersji 2 na 3

Nowe zdarzenie do obsługi MVC

Interfejs API w wersji 3 dodaje nowy typ zdarzenia, aby odzwierciedlać zmiany stanu MVC. Obecnie dostępne są 2 rodzaje zdarzeń:

• Zdarzenia użytkownika (np. zdarzenia myszy „kliknięcie”) są propagowane z DOM do Maps JavaScript API. Te zdarzenia są odrębne i różnią się od standardowych zdarzeń DOM.
• Powiadomienia o zmianie stanu MVC odzwierciedlają zmiany w obiektach interfejsu Maps API i są nazywane zgodnie z konwencją property_changed.

Każdy obiekt interfejsu Maps API eksportuje określoną liczbę nazwanych zdarzeń. Aplikacje, które interesują się określonymi zdarzeniami, powinny zarejestrować ich detektory i wykonać kod po ich otrzymaniu. Ten mechanizm sterowany zdarzeniami jest taki sam w wersjach 2 i 3 interfejsu Maps JavaScript API, z tym że zmieniła się przestrzeń nazw: z GEvent na 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.');
});

Usuwanie detektorów zdarzeń

Ze względu na wydajność najlepiej usunąć detektor zdarzeń, gdy nie jest już potrzebny. Usuwanie detektora zdarzeń działa tak samo w wersjach 2 i 3:

1. Podczas tworzenia detektora zdarzeń zwracany jest obiekt nieprzezroczysty (GEventListener w wersji 2, MapsEventListener w wersji 3).
2. Aby usunąć detektor zdarzeń, przekaż ten obiekt metodzie removeListener() (GEvent.removeListener() w wersji 2 lub google.maps.event.removeListener() w wersji 3), aby usunąć detektor zdarzeń.

Nasłuchiwanie zdarzeń DOM

Jeśli chcesz rejestrować zdarzenia DOM (Document Object Model) i na nie odpowiadać, w wersji 3 dostępna jest metoda statyczna google.maps.event.addDomListener(), która jest odpowiednikiem metody GEvent.addDomListener() w wersji 2.

Używanie parametrów przekazywanych w zdarzeniach

Zdarzenia interfejsu użytkownika często przekazują argument zdarzenia, do którego odbiornik zdarzenia może uzyskać dostęp. Większość argumentów zdarzeń w wersji 3 została uproszczona, aby była bardziej spójna z obiektami w interfejsie API. (więcej informacji znajdziesz w materiałach referencyjnych wersji 3).

W detektorach zdarzeń w wersji 3 nie ma argumentu overlay. Jeśli zarejestrujesz zdarzenie click na mapie w wersji 3, wywołanie zwrotne nastąpi tylko wtedy, gdy użytkownik kliknie mapę podstawową. Jeśli chcesz reagować na kliknięcia, możesz zarejestrować dodatkowe wywołania zwrotne dla klikalnych nakładek.

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

Zmiany w typach kontroli

Wprowadziliśmy pewne zmiany w typach control w interfejsie API w wersji 3.

1. Interfejs API w wersji 3 obsługuje dodatkowe typy map, w tym mapy terenu i możliwość dodawania niestandardowych typów map.
2. Element hierarchiczny w wersji 2, GHierarchicalMapTypeControl, nie jest już dostępny. Podobny efekt możesz uzyskać, używając ustawienia google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Układ poziomy udostępniany przez tag GMapTypeControl w wersji 2 jest niedostępny w wersji 3.

Dodawanie elementów sterujących do mapy

W interfejsie Maps JavaScript API v2 możesz dodać elementy sterujące do mapy za pomocą metody addControl() obiektu mapy. W wersji 3 zamiast uzyskiwać dostęp do elementów sterujących lub modyfikować ich bezpośrednio, modyfikujesz powiązany obiekt MapOptions. Przykład poniżej pokazuje, jak dostosować mapę, aby dodać te opcje:

• przyciski umożliwiające użytkownikowi przełączanie się między dostępnymi typami map;
• skali mapy;

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

Elementy sterujące pozycjonowaniem na mapie

Ustawienia pozycjonowania zostały znacznie zmienione w wersji 3. W wersji 2 metoda addControl() przyjmuje opcjonalny drugi parametr, który umożliwia określenie położenia elementu sterującego względem narożników mapy.

W wersji 3 pozycję elementu sterującego ustawiasz za pomocą właściwości position opcji elementu. Położenie tych elementów nie jest absolutne. Zamiast tego interfejs API rozmieszcza je inteligentnie, „przesuwając” je wokół istniejących elementów mapy w ograniczonych ramach (np. rozmiaru mapy). Dzięki temu domyślne ustawienia będą zgodne z Twoimi ustawieniami. Więcej informacji znajdziesz w artykule Zarządzanie pozycjonowaniem w wersji 3.

Poniższy kod zmienia położenie elementów sterujących z powyższych przykładów:

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

Elementy sterujące niestandardowe

Interfejs Maps JavaScript API umożliwia tworzenie niestandardowych elementów sterujących nawigacją. Aby dostosować elementy sterujące za pomocą interfejsu API w wersji 2, musisz utworzyć podklasę klasy GControl i zdefiniować metody obsługi dla metod initialize() i getDefaultPosition(). W wersji 3 nie ma odpowiednika klasy GControl. Zamiast tego kontrolki są reprezentowane jako elementy DOM. Aby dodać element sterujący niestandardowy za pomocą interfejsu API w wersji 3, utwórz strukturę DOM elementu sterującego w konstruktorze jako element podrzędny elementu Node (np. elementu <div>) i dodaj odbiorniki zdarzeń, które będą obsługiwać zdarzenia DOM. Prześlij element Node do tablicy controls[position] map, aby dodać do mapy instancję elementu sterującego niestandardowego.

W przypadku implementacji klasy HomeControl, która spełnia wymagania dotyczące interfejsu opisane powyżej (szczegółowe informacje znajdziesz w dokumentacji elementów sterujących niestandardowych), poniższe przykłady kodu pokazują, jak dodać do mapy element sterujący niestandardowy.

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

Dodawanie i usuwanie nakładek

Typy obiektów reprezentowanych przez nakładkę są takie same w wersji 2 i 3, ale są one obsługiwane w inny sposób.

Na mapie dodano i usunięto nakłady w interfejsie API w wersji 2 za pomocą metod addOverlay() i removeOverlay() obiektu GMap2. W wersji 3 mapę przypisujesz do nakładki za pomocą właściwości map powiązanej klasy opcji nakładki. Możesz też dodać lub usunąć nakładkę bezpośrednio, wywołując metodę setMap() obiektu nakładki i określając żądaną mapę. Ustawienie właściwości mapy na null powoduje usunięcie nakładki.

W wersji 3 nie ma metody clearOverlays(). Jeśli chcesz zarządzać zestawem nakładek, utwórz tablicę, która będzie je przechowywać. Następnie możesz wywołać funkcję setMap() dla każdego nakładania w tablicy (przekazując null, jeśli chcesz je usunąć).

Znaczniki, które można przeciągać

Domyślnie znaczniki można klikać, ale nie można ich przeciągać. W tych 2 przykładach pokazano dodawanie znacznika, który można przeciągać:

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

Ikony

Możesz zdefiniować ikonę niestandardową, która będzie wyświetlana zamiast domyślnego znacznika. Aby użyć niestandardowego obrazu w wersji 2, możesz utworzyć instancję GIcon z poziomu G_DEFAULT_ICON type i ją zmodyfikować. Jeśli obraz jest większy lub mniejszy niż domyślna ikona, musisz go określić za pomocą instancji GSize. Interfejs API w wersji 3 nieco upraszcza ten proces. Wystarczy ustawić w markerze właściwość icon na adres URL niestandardowego obrazu, a interfejs API automatycznie dostosuje rozmiar ikony.

Interfejs Maps JavaScript API obsługuje też złożone ikony. Ikona złożona może zawierać wiele kafelków, złożone kształty lub określać „kolejność nakładania” obrazów względem innych nakładek. Aby dodać kształt do znacznika w wersji 2, musisz podać dodatkową właściwość w każdym wystąpieniu GIcon i przekazać ją jako opcję konstruktorowi GMarker. W wersji 3 ikony określone w ten sposób powinny mieć właściwości icon ustawione na obiekt typu Icon. Cienie znaczników nie są obsługiwane w wersji 3.

W tych przykładach widać flagę na plaży Bondi w Australii. Przezroczysta część ikony nie jest klikalna:

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

Linie łamane

Linia złożona składa się z tablicy elementów LatLng oraz serii odcinków linii, które łączą te lokalizacje w uporządkowanej kolejności. Tworzenie i wyświetlanie obiektu Polyline w wersji 3 jest podobne do korzystania z obiektu GPolyline w wersji 2. W tych przykładach rysowana jest półprzezroczysta linia geodezyjna o szerokości 3 pikseli z Zurychu do Sydney przez Singapur:

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

Zaszyfrowane linie łamane

Wersja 3 nie obsługuje tworzenia obiektów Polyline bezpośrednio z zakodowanych polilinii. Zamiast tego biblioteka Geometry Library udostępnia metody kodowania i dekodowania ścieżek poliliniowych. Więcej informacji o wczytywaniu tej biblioteki znajdziesz w sekcji Biblioteki w interfejsie API Map w wersji 3.

Przykłady poniżej rysują ten sam zakodowany wielokąt; kod v3 używa metody decodePath() z przestrzeni nazw 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);

Wielokąty

Wielokąt definiuje obszar wewnątrz zamkniętej pętli. Podobnie jak obiekt Polyline, obiekty Polygon składają się z szeregu punktów w uporządkowanej sekwencji. Klasa Polygon w wersji 3 jest bardzo podobna do klasy GPolygon w wersji 2, z tą różnicą, że nie trzeba już powtarzać wierzchołka początkowego na końcu ścieżki, aby zamknąć pętlę. Interfejs API v3 automatycznie zamyka wielokąty, łącząc ostatnią współrzędną z pierwszą. Poniższe fragmenty kodu tworzą wielokąt reprezentujący Trójkąt Bermudzki:

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

Kształty edytowalne przez użytkownika

Linie i wielokąty można udostępnić do edycji przez użytkowników. Te fragmenty kodu są równoważne:

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

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

Więcej informacji o zaawansowanych funkcjach rysowania znajdziesz w bibliotece rysunków w dokumentacji wersji 3.

Okna informacyjne

InfoWindow wyświetla treści w oknie nakładanym na mapę. Oto kilka kluczowych różnic między oknami informacyjnymi w wersji 2 a 3:

• Interfejs API w wersji 2 obsługuje tylko GInfoWindow na mapę, natomiast interfejs API w wersji 3 obsługuje wiele jednoczesnych InfoWindow na każdą mapę.
• Po kliknięciu mapy InfoWindow wersji 3 pozostanie otwarta. W wersji 2 GInfoWindowzamyka się automatycznie, gdy klikniesz mapę. Możesz emulować zachowanie wersji 2, dodając do obiektu click listenera.Map
• Interfejs API w wersji 3 nie obsługuje natywnych kart.InfoWindow

Nakładki na powierzchnię

Aby umieścić obraz na mapie, użyj obiektu GroundOverlay. Konstruktor elementu GroundOverlay jest w wersji 2 i 3 zasadniczo taki sam: określa adres URL obrazu i jego granice jako parametry.

W tym przykładzie umieszczamy na mapie antyczną mapę Newark w New Jersey jako nakładkę:

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

Typy map

W wersji 2 i 3 dostępne są 4 podstawowe typy map:

• MapTypeId.ROADMAP (zastępuje G_NORMAL_MAP) wyświetla widok mapy drogowej.
• MapTypeId.SATELLITE (zastępuje G_SATELLITE_MAP) wyświetla zdjęcia satelitarne Google Earth.
• MapTypeId.HYBRID (zastępuje G_HYBRID_MAP) wyświetla widok mieszany: normalny i satelitarny.
• MapTypeId.TERRAIN (zastępuje G_PHYSICAL_MAP) wyświetla mapę fizyczną opartą na informacjach o terenie.

Poniżej znajdziesz przykład ustawienia mapy na widok terenu w wersji 2 i 3:

map.setMapType(G_PHYSICAL_MAP);
    

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

W wersji 3 interfejsu Maps JavaScript API wprowadzono też kilka zmian dotyczących rzadziej używanych typów map:

• Płytki mapy dla obiektów niebieskich innych niż Ziemia nie są dostępne jako typy map w interfejsie API w wersji 3, ale można uzyskać do nich dostęp jako niestandardowe typy map, jak pokazano w tym przykładzie.
• W wersji 3 nie ma specjalnego typu mapy, który zastąpiłby typ G_SATELLITE_3D_MAP z wersji 2. Zamiast tego możesz zintegrować wtyczkę Google Earth z mapami w wersji 3, korzystając z tej biblioteki.

Obraz w maksymalnym powiększeniu

Zdjęcia satelitarne nie zawsze są dostępne przy dużym powiększeniu. Jeśli przed ustawieniem poziomu powiększenia chcesz poznać najwyższy dostępny poziom powiększenia, użyj klasy google.maps.MaxZoomService. Ta klasa zastępuje metodę GMapType.getMaxZoomAtLatLng() z wersji 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.");
    }
});

Zdjęcia lotnicze w perspektywie

Po włączeniu zdjęć lotniczych w wersji 3 elementy sterujące są podobne do elementów sterujących w wersji 2.GLargeZoomControl3D, z dodatkowym elementem przejściowym. Obracanie pozwala przełączać się między obsługiwanymi kierunkami.

Na tej mapie możesz sprawdzić, w których miastach są obecnie dostępne zdjęcia o rozdzielczości 45°. Gdy obrazy pod kątem 45° są dostępne, do przycisku satelitarnego interfejsu Maps API zostanie dodana opcja menu.