Обновление приложения Maps JavaScript API с версии V2 до версии V3

Новое событие для поддержки MVC

API версии 3 добавляет новый тип событий для отражения изменений состояния MVC. Теперь есть два типа событий:

• Пользовательские события (например, события щелчка мышью) передаются из DOM в Maps JavaScript API. Эти события отделены от стандартных событий DOM.
• Уведомления об изменении состояния MVC отражают изменения в объектах Maps API и именуются с использованием соглашения property _changed .

Каждый объект Maps API экспортирует несколько именованных событий. Приложения, заинтересованные в определенных событиях, должны регистрировать прослушиватели событий для этих событий и выполнять код при получении этих событий. Этот механизм, управляемый событиями, одинаков в Maps JavaScript API v2 и v3, за исключением того, что пространство имен изменилось с GEvent на 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.');
});

Удаление прослушивателей событий

По соображениям производительности лучше всего удалить прослушиватель событий, когда он больше не нужен. Удаление прослушивателя событий работает одинаково в v2 и v3:

1. Когда вы создаете прослушиватель событий, возвращается непрозрачный объект ( GEventListener в версии 2, MapsEventListener в версии 3).
2. Если вы хотите удалить прослушиватель событий, передайте этот объект методу removeListener() ( GEvent.removeListener() в версии 2 или google.maps.event.removeListener() в версии 3), чтобы удалить прослушиватель событий.

Прослушивание событий DOM

Если вы хотите перехватывать события DOM (объектная модель документа) и реагировать на них, версия 3 предоставляет статический метод google.maps.event.addDomListener() , эквивалентный методу GEvent.addDomListener() в версии 2.

Использование переданных аргументов в событиях

События пользовательского интерфейса часто передают аргумент события, к которому затем может получить доступ прослушиватель событий. Большинство аргументов событий в версии 3 были упрощены, чтобы обеспечить большую согласованность с объектами API. (Подробную информацию см . в справочнике по версии 3. )

В прослушивателях событий версии 3 нет аргумента overlay . Если вы зарегистрируете событие click на карте версии 3, обратный вызов произойдет только тогда, когда пользователь нажмет на базовую карту. Вы можете зарегистрировать дополнительные обратные вызовы на интерактивных наложениях, если вам нужно реагировать на эти клики.

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

Изменения в типах управления

Некоторые изменения в типах элементов control были внесены в API версии 3.

1. API версии 3 поддерживает дополнительные типы карт , включая карты местности и возможность добавления пользовательских типов карт.
2. Иерархический элемент управления версии 2, GHierarchicalMapTypeControl , больше недоступен. Аналогичного эффекта можно добиться, используя элемент управления google.maps.MapTypeControlStyle.HORIZONTAL_BAR .
3. Горизонтальный макет, предоставляемый GMapTypeControl в версии 2, недоступен в версии 3.

Добавление элементов управления на карту

С помощью Maps JavaScript API v2 вы можете добавить элементы управления на свою карту с помощью метода addControl() вашего объекта карты. В версии 3 вместо прямого доступа к элементам управления или их изменения вы изменяете связанный объект MapOptions . В приведенном ниже примере показано, как настроить карту, добавив следующие элементы управления:

• кнопки, которые позволяют пользователю переключаться между доступными типами карт
• масштаб карты

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

Элементы управления позиционированием на карте

Элементы управления позиционированием сильно изменились в v3. В версии 2 метод addControl() принимает необязательный второй параметр, который позволяет указать положение элемента управления относительно углов карты.

В версии 3 положение элемента управления устанавливается через свойство position параметров элемента управления. Расположение этих элементов управления не является абсолютным; вместо этого API будет разумно размещать элементы управления, «обтекая» их вокруг существующих элементов карты в пределах заданных ограничений (например, размера карты). Это гарантирует, что элементы управления по умолчанию совместимы с вашими элементами управления. Дополнительную информацию см. в разделе «Позиционирование управления» в версии 3 .

Следующий код меняет положение элементов управления из приведенных выше примеров:

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

Пользовательские элементы управления

API JavaScript Карт позволяет создавать собственные элементы управления навигацией. Чтобы настроить элементы управления с помощью API версии 2, вы должны создать подкласс класса GControl и определить обработчики для методов initialize() и getDefaultPosition() . В версии 3 нет эквивалента классу GControl . Вместо этого элементы управления представлены как элементы DOM. Чтобы добавить пользовательский элемент управления с помощью API версии 3, создайте структуру DOM для элемента управления в конструкторе как дочерний элемент Node (например, элемент <div> ) и добавьте прослушиватели событий для обработки любых событий DOM. Вставьте Node в массив controls[ position ] карты, чтобы добавить экземпляр настраиваемого элемента управления на вашу карту.

Учитывая реализацию класса HomeControl , которая соответствует требованиям к интерфейсу, указанным выше (подробные сведения см. в документации по пользовательским элементам управления ), в следующих примерах кода показано, как добавить пользовательский элемент управления на карту.

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

Добавление и удаление наложений

Типы объектов, представленных наложением, одинаковы в версиях 2 и 3, однако обрабатываются они по-разному.

Наложения в API версии 2 добавлялись на карту и удалялись с нее с помощью методов addOverlay() и removeOverlay() объекта GMap2 . В версии 3 вы назначаете карту наложению через свойство map соответствующего класса параметров наложения. Вы также можете добавить или удалить наложение напрямую, вызвав метод setMap() объекта наложения и указав нужную карту. Установка для свойства карты значения null удаляет наложение.

В версии 3 не существует метода clearOverlays() . Если вы хотите управлять набором наложений, вам следует создать массив для хранения наложений. Используя этот массив, вы можете затем вызвать setMap() для каждого наложения в массиве (передавая null , если вам нужно их удалить).

Перетаскиваемые маркеры

По умолчанию маркеры можно щелкать, но нельзя перетаскивать. В следующих двух примерах добавлен перетаскиваемый маркер:

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

Иконки

Вы можете определить собственный значок, который будет отображаться вместо маркера по умолчанию. Чтобы использовать собственное изображение в версии 2, вы можете создать экземпляр GIcon из G_DEFAULT_ICON type и изменить его. Если ваше изображение больше или меньше значка по умолчанию, вы должны указать его с помощью экземпляра GSize . API v3 немного упрощает этот процесс. Просто установите для свойства icon маркера URL-адрес вашего пользовательского изображения, и API автоматически определит размер значка.

API JavaScript Карт также обеспечивает поддержку сложных значков. Сложный значок может включать в себя несколько плиток, сложные формы или указывать «порядок стека» того, как изображения должны отображаться относительно других наложений. Чтобы добавить форму к маркеру в версии 2, вам необходимо указать дополнительное свойство в каждом экземпляре GIcon и передать его в качестве опции конструктору GMarker . В версии 3 значки, указанные таким образом, должны устанавливать в качестве свойств icon объект типа Icon . Тени маркеров не поддерживаются в версии 3.

В следующих примерах показан пляжный флаг на пляже Бонди в Австралии, при этом прозрачная часть значка неактивна:

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

Полилинии

Полилиния состоит из массива LatLng , а также серии сегментов линии, которые соединяют эти местоположения в упорядоченной последовательности. Создание и отображение объекта Polyline в версии 3 аналогично использованию объекта GPolyline в версии 2. В следующих примерах рисуется полупрозрачная геодезическая ломаная линия шириной 3 пикселя от Цюриха до Сиднея через Сингапур:

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

Закодированные полилинии

В версии 3 не существует поддержки создания объектов Polyline непосредственно из закодированных полилиний . Вместо этого Библиотека геометрии предоставляет методы для кодирования и декодирования полилиний. Дополнительную информацию о загрузке этой библиотеки см. в разделе « Библиотеки в Maps API v3».

В приведенных ниже примерах рисуется одна и та же закодированная полилиния; код версии 3 использует метод decodePath() из пространства имен 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);

Полигоны

Полигон определяет область внутри замкнутого цикла. Подобно объекту Polyline , объекты Polygon состоят из ряда точек в упорядоченной последовательности. Класс Polygon версии 3 во многом аналогичен классу GPolygon версии 2, с тем заметным исключением, что вам больше не нужно повторять начальную вершину в конце пути, чтобы замкнуть цикл. API версии 3 автоматически закроет все многоугольники, нарисовав обводку, соединяющую последнюю координату с первой координатой. Следующие фрагменты кода создают многоугольник, представляющий Бермудский треугольник:

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

Редактируемые пользователем фигуры

Полилинии и многоугольники можно сделать редактируемыми пользователем. Следующие фрагменты кода эквивалентны:

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

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

Дополнительные возможности рисования см. в библиотеке чертежей документации версии 3.

Информационные окна

InfoWindow отображает контент в плавающем окне над картой. Между информационными окнами версий 2 и 3 есть несколько ключевых отличий:

• API версии 2 поддерживает только GInfoWindow на карте, тогда как API версии 3 поддерживает несколько одновременных окон InfoWindow на каждой карте.
• InfoWindow v3 останется открытым при нажатии на карту. GInfoWindow версии 2 автоматически закрывается при нажатии на карту. Вы можете эмулировать поведение версии 2, добавив прослушиватель click на объект Map .
• API версии 3 не обеспечивает встроенную поддержку InfoWindow с вкладками.

Наложения земли

Чтобы разместить изображение на карте, вам следует использовать объект GroundOverlay . Конструктор GroundOverlay по существу один и тот же в версиях 2 и 3: он указывает URL-адрес изображения и границы изображения в качестве параметров.

В следующем примере старинная карта Ньюарка, штат Нью-Джерси, помещается на карту в виде наложения:

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

Распространенные типы карт

Четыре основных типа карт доступны как в версии 2, так и в версии 3:

• MapTypeId.ROADMAP (заменяет G_NORMAL_MAP ) отображает вид карты дорог.
• MapTypeId.SATELLITE (заменяет G_SATELLITE_MAP ) отображает спутниковые изображения Google Earth.
• MapTypeId.HYBRID (заменяет G_HYBRID_MAP ) отображает смесь обычного и спутникового видов.
• MapTypeId.TERRAIN (заменяет G_PHYSICAL_MAP ) отображает физическую карту на основе информации о местности.

Ниже приведен пример v2 и v3, в которых карта настроена на вид местности:

map.setMapType(G_PHYSICAL_MAP);
    

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

Maps JavaScript API v3 также внес несколько изменений в менее распространенные типы карт:

• Фрагменты карты для небесных тел , отличных от Земли, недоступны как типы карт в API версии 3, но к ним можно получить доступ как к пользовательским типам карт, как показано в этом примере .
• В версии 3 нет специального типа карты, который заменял бы тип G_SATELLITE_3D_MAP из версии 2. Вместо этого вы можете интегрировать плагин Google Earth в свои карты v3, используя эту библиотеку .

Изображение с максимальным увеличением

Спутниковые изображения не всегда доступны при высоком уровне масштабирования. Если вы хотите узнать максимальный доступный уровень масштабирования перед установкой уровня масштабирования, используйте класс google.maps.MaxZoomService . Этот класс заменяет метод GMapType.getMaxZoomAtLatLng() из версии 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.");
    }
});

Аэрофотоснимки

При включении аэрофотоснимков в версии 3 элементы управления аналогичны элементу управления GLargeZoomControl3D версии 2 с дополнительным межстраничным элементом управления «Поворот» для поворота в поддерживаемых направлениях.

На этой карте вы можете отслеживать города, в которых в настоящее время доступны изображения под углом 45°. Если доступны изображения под углом 45°, к кнопке Maps API Satellite добавляется опция подменю.