Aktualizacja interfejsu API JavaScript Map Google z wersji 2 do 3

Nowe zdarzenie obsługi MVC

Interfejs API v3 dodaje nowy typ zdarzenia, aby odzwierciedlić zmiany stanu MVC. Są teraz 2 rodzaje zdarzeń:

• Zdarzenia użytkownika (np. "click" zdarzenia myszy) są rozpowszechniane z interfejsu DOM do interfejsu Maps JavaScript API. Te zdarzenia są odrębne od standardowych zdarzeń DOM.
• Powiadomienia o zmianach stanu MVC odzwierciedlają zmiany w obiektach interfejsu API Map Google i nazywają się zgodnie z konwencją property_changed.

Każdy obiekt interfejsu API Map Google eksportuje liczbę nazwanych zdarzeń. Aplikacje zainteresowane określonymi zdarzeniami powinny rejestrować detektory tych zdarzeń i uruchamiać kod po otrzymaniu tych zdarzeń. Ten mechanizm reagujący na zdarzenia jest taki sam w interfejsie Maps JavaScript API w wersji 2 i 3, z tą różnicą, że przestrzeń nazw zmieniła się 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 jest usunąć detektor zdarzeń, gdy nie jest już potrzebny. Usuwanie detektora zdarzeń działa w ten sam sposób w wersjach 2 i 3:

1. Gdy utworzysz detektor zdarzeń, zwracany jest nieprzezroczysty obiekt (GEventListener w wersji 2 lub 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ąć.

Słuchanie zdarzeń DOM

Jeśli chcesz przechwytywać zdarzenia DOM i odpowiadać na nie, v3 udostępnia metodę statyczną google.maps.event.addDomListener() odpowiadającą odpowiednikowi GEvent.addDomListener() w wersji 2.

Używanie przekazywanych argumentów w zdarzeniach

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

W odbiornikach zdarzeń w wersji 3 nie ma argumentu overlay. Jeśli zarejestrujesz zdarzenie click na mapie w wersji 3, wywołanie zwrotne pojawi się tylko wtedy, gdy użytkownik kliknie mapę podstawową. Jeśli chcesz reagować na te kliknięcia, możesz zarejestrować dodatkowe wywołania zwrotne w nakładkach, które można kliknąć.

// 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 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 oraz możliwość dodawania niestandardowych typów map.
2. Wersja hierarchiczna wersji 2 (GHierarchicalMapTypeControl) nie jest już dostępna. Podobny efekt możesz osiągnąć za pomocą ustawienia google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Układ poziomy podany w GMapTypeControl w wersji 2 nie jest dostępny w wersji 3.

Dodawanie elementów sterujących do mapy

W interfejsie Maps JavaScript API w wersji 2 możesz dodać do mapy elementy sterujące metodą addControl() obiektu mapy. W wersji 3 zamiast bezpośrednio uzyskiwać dostęp do elementów sterujących lub modyfikować je, modyfikujesz powiązany obiekt MapOptions. Poniższy przykład pokazuje, jak dostosować mapę, aby uzyskać dostęp do tych elementów:

• przyciski umożliwiające użytkownikom przełączanie się między dostępnymi typami map.
• skala

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

Elementy sterujące pozycjonowaniem znacząco zmieniły się w wersji 3. W wersji 2 metoda addControl() przyjmuje opcjonalny drugi parametr, który umożliwia określenie pozycji elementu względem rogów mapy.

W wersji 3 określasz pozycję kontrolną we właściwości position opcji opcji. Położenie tych elementów sterujących nie jest absolutne. Zamiast tego interfejs API rozmieszcza elementy sterujące inteligentnie według istniejących elementów mapy zgodnie z określonymi ograniczeniami (np. rozmiaru mapy). Dzięki temu możesz mieć pewność, że ustawienia domyślne są zgodne z Twoimi ustawieniami. Więcej informacji znajdziesz w artykule Kontrola nad pozycjonowaniem w wersji 3.

Poniższe elementy sterujące zmianą pozycji 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

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 klasyfikować klasę GControl i zdefiniować moduły obsługi metod initialize() i getDefaultPosition(). Nie ma odpowiednika klasy GControl w wersji 3. Elementy sterujące są natomiast przedstawiane jako elementy DOM. Aby dodać niestandardową kontrolę za pomocą interfejsu API w wersji 3, utwórz strukturę DOM dla konstruktora jako element podrzędny elementu Node (np. element <div>) i dodaj detektory zdarzeń, które będą obsługiwane przez wszystkie zdarzenia DOM. Umieść Node w mapachcontrols[position] i dodaj do mapy instancję niestandardowego elementu sterującego.

Biorąc pod uwagę implementację klasy HomeControl, która spełnia powyższe wymagania dotyczące interfejsu (szczegóły znajdziesz w dokumentacji Ustawienia niestandardowe), poniżej znajdziesz przykładowy kod pokazujący, jak dodać do mapy niestandardowe elementy sterujące.

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 w inny sposób.

Nakładki w interfejsie API w wersji 2 zostały dodane do mapy i usunięte z metody addOverlay() i removeOverlay() obiektu GMap2. W wersji 3 przypisujesz mapę 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 odpowiednią mapę. Ustawienie właściwości mapy na null spowoduje usunięcie nakładki.

Brak metody clearOverlays() w wersji 3. Jeśli chcesz zarządzać zestawem nakładek, utwórz tablicę do przechowywania nakładek. Używając tej tablicy, możesz wywoływać setMap() na każdej nakładce w tablicy (pomijając null, jeśli chcesz je usunąć).

Znaczniki przeciągane

Domyślnie znaczniki są klikalne, ale nie można ich przeciągać. W tych dwóch próbkach znajduje się 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ć niestandardową ikonę, 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 instancji G_DEFAULT_ICON type i zmodyfikować ją. Jeśli obraz jest większy lub mniejszy niż ikona domyślna, musisz go określić w instancji GSize. Interfejs API w wersji 3 nieznacznie upraszcza ten proces. Wystarczy, że ustawisz we właściwości icon znacznik na adres URL niestandardowego obrazu, a interfejs API automatycznie ustawi rozmiar ikony.

Interfejs Maps JavaScript API zapewnia też obsługę złożonych ikon. Złożona ikona może zawierać wiele kafelków i skomplikowanych kształtów, a także określać 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żdej instancji GIcon i przekazać tę opcję jako konstruktor GMarker. W wersji 3 ikony określone w ten sposób powinny ustawić właściwość icon jako obiekt typu Icon. cienie znacznika nie są obsługiwane w wersji 3.

W poniższych przykładach widać flagę plaży przy plaży Bondi w Australii, gdzie 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 LatLng sekund oraz serii segmentów, które łączą te lokalizacje w kolejności. Tworzenie i wyświetlanie obiektu Polyline w wersji 3 jest podobne do używania obiektu GPolyline w wersji 2. W tych przykładach półprzezroczyste, 3-pikselowe linie łamane w stylu geodetycznym 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);

Zakodowane linie łamane

W wersji 3 nie można tworzyć obiektów Polyline bezpośrednio z zakodowanych linii łamanych. Zamiast tego Biblioteka geometrii zawiera metody kodowania i dekodowania linii łamanych. Więcej informacji o wczytywaniu tej biblioteki znajdziesz w bibliotekach w interfejsie API Map Google w wersji 3.

Poniższe przykłady dotyczą tej samej zakodowanej linii łamanej. Kod v3 wykorzystuje metodę 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 określa region w pętli. Podobnie jak obiekt Polyline obiekty Polygon składają się z punktów w określonej kolejności. Klasa Polygon w wersji 3 jest prawie taka sama jak klasa GPolygon w wersji 2, z tą różnicą, że nie musisz już powtarzać początkowego wierzchołka na końcu ścieżki, aby zamknąć pętlę. Interfejs API v3 automatycznie zamknie wszystkie wielokąty, narysowając kreski łączące ostatnią z powrotem ze pierwszą współrzędną. Te fragmenty kodu tworzą wielokąt reprezentujący trójkąt trójkąta Bermudy:

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, które mogą być edytowane przez użytkowników

Linie i wielokąty można edytować jako użytkownik. Te fragmenty kodu są równoważne:

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

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

Bardziej zaawansowane możliwości rysowania znajdziesz w Bibliotece rysunków w dokumentacji wersji 3.

Okna informacyjne

InfoWindow wyświetla zawartość w pływającym oknie nad mapą. Istnieje kilka istotnych różnic między oknami informacyjnymi w wersji 2 i 3:

• Interfejs v2 obsługuje tylko GInfoWindow na mapie, a interfejs v3 obsługuje wiele równoczesnych InfoWindow na każdej mapie.
• Gdy klikniesz mapę, wersja InfoWindow pozostanie otwarta. Wersja 2 GInfoWindow zamyka się automatycznie po kliknięciu mapy. Możesz skonfigurować emulację v2, dodając odbiornik click do obiektu Map.
• Interfejs API w wersji 3 nie zapewnia natywnej obsługi interfejsu z kartami InfoWindow.

Nakładki na powierzchnię

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 na mapie zabytkową mapę Newark, NJ:

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

Typowe typy map

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

• MapTypeId.ROADMAP (zastępuje G_NORMAL_MAP) powoduje wyświetlenie widoku mapy drogi.
• MapTypeId.SATELLITE (zastępuje G_SATELLITE_MAP) wyświetla zdjęcia satelitarne w Google Earth.
• W widoku MapTypeId.HYBRID (zastępuje G_HYBRID_MAP) będą się wyświetlać normalne i widoki satelitarne.
• MapTypeId.TERRAIN (zastąpi G_PHYSICAL_MAP) udostępnia mapę fizyczną opartą na informacjach o terenie.

Oto przykład ustawienia mapy w wersji 2 i 3 w widoku terenu:

map.setMapType(G_PHYSICAL_MAP);
    

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

W interfejsie Maps JavaScript v3 wprowadziliśmy też kilka zmian w mniej popularnych typach map:

• Fragmenty mapy dla ciasnych elementów innych niż Earth są niedostępne jako typy map w interfejsie API v3, ale można je otworzyć jako niestandardowe typy map, jak pokazano w tym przykładzie.
• W wersji 3 nie ma specjalnego typu mapy, który zastępuje typ G_SATELLITE_3D_MAP zamiast wersji 2. Zamiast tego możesz zintegrować wtyczkę Google Earth z mapami v3 za pomocą tej biblioteki.

Maksymalne powiększenie

Zdjęcia satelitarne nie zawsze są dostępne przy wysokim powiększeniu. Jeśli chcesz uzyskać najwyższy dostępny poziom powiększenia przed ustawieniem poziomu 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 z lotu ptaka

W przypadku zdjęć lotniczych w wersji 3 elementy sterujące są podobne do elementów sterujących w wersji GLargeZoomControl3D (2 z dodatkową opcją pełnoekranowego obrotu), która pozwala przełączać się między obsługiwanymi kierunkami.

Możesz śledzić miasta, w których zdjęcia 45° są obecnie dostępne na tej mapie. Gdy zdjęcia 45° są dostępne, do przycisku Satelita interfejsu API Map Google jest dodawana opcja podmenu.