Как обновить приложение с Maps JavaScript API с версии 2 до версии 3

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

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

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

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

Как удалять прослушиватели событий

В целях повышения производительности рекомендуется удалять прослушиватель событий, когда он больше не нужен. Удаление прослушивателя событий в версиях 2 и 3 выполняется одинаково:

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

Как прослушивать события DOM

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

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

События пользовательского интерфейса часто передают аргумент, к которому затем может обращаться прослушиватель событий. Большинство аргументов событий в версии 3 были упрощены, чтобы обеспечить большую согласованность между объектами в API. Подробную информацию можно найти в справочнике по 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
  });
});

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

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

1. В API версии 3 поддерживаются дополнительные типы карт, в том числе карты рельефа, а также возможность добавлять собственные типы карт.
2. Иерархический элемент управления v2, GHierarchicalMapTypeControl, больше не доступен. Похожего эффекта можно добиться с помощью элемента управления google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. Горизонтальный макет, который в версии 2 задавался с помощью GMapTypeControl, в версии 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. Во второй версии метод 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);

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

Используйте Maps JavaScript API, чтобы создать собственные элементы управления навигацией. Чтобы настроить элементы управления с помощью 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() объекта наложения и указав нужную карту. Чтобы удалить наложение, задайте для свойства map значение 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
});

Значки.

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

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

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

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 версии 3.

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

Дополнительные возможности рисования описаны в разделе Библиотека Drawing документации по Maps JavaScript API версии 3.

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

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

• API версии 2 поддерживает только один объект GInfoWindow на карту, а API версии 3 – несколько параллельных объектов InfoWindow на каждой карте.
• В версии 3 InfoWindow остается открытым при нажатии на карту. Окно 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);

Общие типы карт

В v2 и v3 имеется четыре базовых типа карт:

• MapTypeId.ROADMAP (заменяет G_NORMAL_MAP) – дорожная карта.
• MapTypeId.SATELLITE (заменяет G_SATELLITE_MAP) – спутниковые снимки Google Планета Земля.
• 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 версии 3 также внесены некоторые изменения в менее распространенные типы карт:

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

Сервис Maximum Zoom Imagery

Спутниковые снимки не всегда доступны с высокими уровнями масштабирования. Если вы хотите узнать максимальный доступный уровень масштабирования, прежде чем задавать его, используйте класс 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 добавляется соответствующий пункт.