Aktualizacja aplikacji Maps JavaScript API z wersji 2 do 3

Nowe zdarzenie obsługi MVC

Interfejs API w wersji 3 dodaje nowy typ zdarzenia, aby odzwierciedlić zmiany stanu MVC. Istnieją teraz 2 rodzaje zdarzeń:

• Zdarzenia użytkownika (takie jak zdarzenia myszy „kliknięcie”) są przesyłane z interfejsu DOM do interfejsu Maps JavaScript API. Zdarzenia te są niezależne i różnią się od standardowych zdarzeń DOM.
• Powiadomienia o zmianie stanu MVC odzwierciedlają zmiany w obiektach interfejsu API Map Google i są nazywane zgodnie z konwencją property_changed.

Każdy obiekt interfejsu API Map Google eksportuje pewną liczbę nazwanych zdarzeń. Aplikacje zainteresowane konkretnymi zdarzeniami powinny rejestrować detektory tych zdarzeń i uruchamiać kod po ich otrzymaniu. Ten mechanizm oparty na zdarzeniach jest taki sam w interfejsach Maps JavaScript API w wersjach 2 i 3 z tą różnicą, że przestrzeń nazw uległa zmianie 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. Gdy utworzysz odbiornik, zwracany jest nieprzezroczysty obiekt (GEventListener w wersji 2, MapsEventListener w wersji 3).
2. Jeśli chcesz usunąć detektor zdarzeń, przekaż ten obiekt do metody removeListener() (GEvent.removeListener() w wersji 2 lub google.maps.event.removeListener() w wersji 3), aby go usunąć.

Odsłuchiwanie zdarzeń DOM

Jeśli chcesz przechwytywać zdarzenia DOM (model obiektu dokumentu) i odpowiadać na nie, wersja 3 udostępnia metodę statyczną google.maps.event.addDomListener(), która odpowiada metodzie GEvent.addDomListener() w wersji 2.

Używanie przekazanych argumentów w zdarzeniach

Zdarzenia interfejsu często przekazują argument zdarzenia, do którego detektor zdarzeń ma dostęp. Większość argumentów zdarzeń w wersji 3 została uproszczona, aby była bardziej spójna w porównaniu z obiektami w interfejsie API. (Więcej informacji znajdziesz w dokumentacji 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 będzie możliwe tylko wtedy, gdy użytkownik kliknie mapę podstawową. Możesz zarejestrować dodatkowe wywołania zwrotne dla klikalnych nakładek, jeśli chcesz zareagować na te kliknięcia.

// 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 elementów sterujących

W interfejsie API w wersji 3 wprowadzono pewne zmiany w typach control.

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 sterujący hierarchiczny w wersji 2 (GHierarchicalMapTypeControl) nie jest już dostępny. Podobny efekt możesz uzyskać za pomocą elementu sterującego google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Układ poziomy udostępniony przez GMapTypeControl w wersji 2 nie jest dostępny w wersji 3.

Dodawanie elementów sterujących do mapy

Za pomocą interfejsu Maps JavaScript API w wersji 2 możesz dodawać elementy sterujące do mapy za pomocą metody addControl() obiektu mapy. W wersji 3 zamiast uzyskiwać bezpośredni dostęp do elementów sterujących i ich modyfikować, zmodyfikujesz powiązany obiekt MapOptions. Poniższy przykład pokazuje, jak dostosować mapę, aby dodać te elementy sterujące:

• przyciski umożliwiające przełączanie się między dostępnymi typami map.
• skalę 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

W wersji 3 elementy sterujące pozycjonowaniem znacznie się zmieniły. W wersji 2 metoda addControl() przyjmuje opcjonalny drugi parametr, który pozwala określić położenie elementu sterującego względem narożników mapy.

W wersji 3 położenie elementu sterującego ustawia się we właściwości position w opcjach sterujących. Umiejscowienie tych elementów sterujących nie jest bezwzględne. Interfejs API rozmieści je w inteligentny sposób, „obciągając” je wokół istniejących elementów mapy w ramach określonych ograniczeń (takich jak rozmiar mapy). Dzięki temu domyślne elementy sterujące są zgodne z Twoimi elementami. Więcej informacji znajdziesz w artykule Kontrola pozycjonowania w wersji 3.

Poniższe przykładowe elementy sterujące umożliwiają zmianę położenia kodu:

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

Ustawienia niestandardowe

Interfejs Maps JavaScript API umożliwia tworzenie niestandardowych elementów sterujących nawigacją. Aby dostosować ustawienia za pomocą interfejsu API w wersji 2, musisz podklasyfikować klasę GControl i zdefiniować moduły obsługi metod initialize() i getDefaultPosition(). Nie ma odpowiednika klasy GControl w wersji 3. Zamiast tego elementy sterujące są reprezentowane jako elementy DOM. Aby dodać niestandardową kontrolkę za pomocą interfejsu API w wersji 3, utwórz strukturę DOM dla elementu sterującego w konstruktorze jako element podrzędny elementu Node (np. elementu <div>) i dodaj detektory zdarzeń do obsługi dowolnych zdarzeń DOM. Wypchnij Node do tablicy controls[position] map, aby dodać do mapy instancję niestandardowego elementu sterującego.

Biorąc pod uwagę implementację klasy HomeControl, która jest zgodna z wymienionymi powyżej wymaganiami interfejsu (szczegóły znajdziesz w dokumentacji niestandardowych elementów sterujących), poniższe przykłady kodu pokazują, jak dodać do mapy niestandardowy element sterujący.

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 wersjach 2 i 3, ale są obsługiwane inaczej.

Nakładki w interfejsie API w wersji 2 zostały dodane do mapy i usunięte z niej za pomocą metod addOverlay() i removeOverlay() obiektu GMap2. W wersji 3 mapę do nakładki przypisujesz 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 odpowiednią 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, musisz utworzyć tablicę do przechowywania nakładek. Korzystając z tej tablicy, możesz następnie wywołać setMap() przy każdej nakładce w tablicy (jeśli musisz usunąć nakładkę, przejdź do tablicy null).

Znaczniki do przeciągania

Domyślnie znaczniki można klikać, ale nie można ich przeciągać. Te 2 przykłady dodają znacznik, 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 w miejscu domyślnego znacznika. Aby użyć obrazu niestandardowego w wersji 2, możesz utworzyć instancję GIcon z G_DEFAULT_ICON type, a następnie ją zmodyfikować. Jeśli obraz jest większy lub mniejszy od ikony domyślnej, musisz go określić za pomocą instancji GSize. Interfejs API w wersji 3 nieco upraszcza ten proces. Wystarczy ustawić właściwość icon znacznika na adres URL niestandardowego obrazu, a interfejs API automatycznie dostosuje rozmiar ikony.

Interfejs Maps JavaScript API zapewnia również obsługę złożonych ikon. Złożona ikona może zawierać wiele kafelków lub złożonych kształtów albo określać „kolejność stosu” określającą sposób wyświetlania obrazów w stosunku do innych nakładek. Aby dodać kształt do znacznika w wersji 2, musisz określić dodatkową właściwość w każdym wystąpieniu GIcon i przekazać ją jako opcję do konstruktora GMarker. W wersji 3 ikony określone w ten sposób powinny ustawiać właściwości icon na obiekt typu Icon. Cienie znaczników nie są obsługiwane w wersji 3.

W poniższych przykładach widać flagę plażową na plaży Bondi w Australii, a 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 łamana składa się z tablicy elementów LatLng oraz serii segmentów łączących te lokalizacje w ustalonej kolejności. Tworzenie i wyświetlanie obiektu Polyline w wersji 3 przypomina użycie obiektu GPolyline w wersji 2. W poniższych przykładach narysowaliśmy półprzezroczystą linię łamaną geodezyjną 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);

Kodowane linie łamane

Wersja 3 nie obsługuje tworzenia obiektów Polyline bezpośrednio z zakodowanych linii łamanych. Zamiast tego biblioteka geometrii udostępnia metody kodowania i dekodowania linii łamanych. Więcej informacji o wczytywaniu tej biblioteki znajdziesz w sekcji Biblioteki interfejsu API Map Google w wersji 3.

W przykładach poniżej widać tę samą zakodowaną linię łamaną. W kodzie w wersji 3 używamy 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 region w zamkniętej pętli. Podobnie jak obiekt Polyline, obiekty Polygon składają się z serii punktów w uporządkowanej kolejności. Klasa Polygon w wersji 3 jest bardzo podobna do klasy GPolygon w wersji 2. Różnica polega na tym, że nie trzeba już powtarzać początkowego wierzchołka na końcu ścieżki, aby zamknąć pętlę. Interfejs API w wersji 3 automatycznie zamknie wszystkie wielokąty, rysując linię łączącą ostatnią współrzędną z pierwszą współrzędną. 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 dostępne do edycji przez użytkownika

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

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

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

Więcej informacji o zaawansowanych możliwościach rysowania znajdziesz w bibliotece rysunków w dokumentacji wersji 3.

Okna informacyjne

Element InfoWindow wyświetla zawartość w pływającym oknie nad mapą. Okna informacyjne w wersjach 2 i 3 różnią się między sobą:

• Interfejs API w wersji 2 obsługuje tylko GInfoWindow na mapę, a interfejs API v3 obsługuje wiele równoczesnych komponentów InfoWindow w przypadku każdej mapy.
• Gdy klikniesz mapę, InfoWindow w wersji 3 pozostanie otwarty. GInfoWindow w wersji 2 zamyka się automatycznie po kliknięciu mapy. Możesz emulować działanie wersji 2, dodając odbiornik click w obiekcie Map.
• Interfejs API w wersji 3 nie zapewnia natywnej obsługi kart InfoWindow.

Warstwy

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

Poniższy przykład pokazuje, jak zabytkową mapę Newark (NJ) umieszczono na mapie 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);

Popularne typy map

Cztery podstawowe typy map są dostępne zarówno w wersji 2, jak i 3:

• MapTypeId.ROADMAP (zamiast G_NORMAL_MAP) to widok mapy drogowej.
• MapTypeId.SATELLITE (zamiast G_SATELLITE_MAP) wyświetla zdjęcia satelitarne z Google Earth.
• MapTypeId.HYBRID (zastępuje G_HYBRID_MAP) pokazuje zarówno widok normalny, jak i widok satelitarny.
• MapTypeId.TERRAIN (zamiast G_PHYSICAL_MAP) wyświetla fizyczną mapę na podstawie informacji o ukształtowaniu terenu.

Poniżej znajduje się przykład wykorzystania wersji 2 oraz 3 ustawienia mapy na widok terenu:

map.setMapType(G_PHYSICAL_MAP);
    

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

W interfejsie Maps JavaScript API w wersji 3 wprowadzono też kilka zmian w mniej popularnych typach map:

• Kafelki map ciał 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 w postaci niestandardowych typów 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.

Zdjęcia z maksymalnym powiększeniem

Zdjęcia satelitarne nie zawsze są dostępne przy dużym poziomie powiększenia. Jeśli przed ustawieniem poziomu powiększenia chcesz poznać największy 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 z perspektywy z lotu ptaka

Po włączeniu zdjęć lotniczych w wersji 3 elementy sterujące są podobne do opcji GLargeZoomControl3D w wersji 2, z dodatkową opcją obracania reklamy pełnoekranowej umożliwiającej obracanie widoku w obsługiwanych kierunkach.

Na tej mapie możesz śledzić miasta, w których obecnie dostępne są zdjęcia sferyczne. Gdy zdjęcia pod kątem 45° są dostępne, do przycisku Maps API zmienia się w podmenu.