Все готово!

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

Активация Google Maps JavaScript API

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Maps JavaScript API и связанных служб
  3. Создание соответствующих ключей

События

На этой странице описываются события пользовательского интерфейса и события ошибок, которые можно отследить и обработать программным способом.

События пользовательского интерфейса

JavaScript в браузере работает на основе событий. Это означает, что JavaScript реагирует на действия, генерируя события, и ожидает, что программа будет отслеживать нужные ей события. Существует два типа событий:

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

Каждый объект Maps JavaScript API экспортирует определенное количество именованных событий. Программы, заинтересованные в определенных событиях, регистрируют блоки JavaScript для прослушивания этих событий и в случае их возникновения выполняют код, регистрируя обработчики событий addListener() в объекте.

В примере ниже показано, какие события активируются google.maps.Map при взаимодействии с картой.

Полный список событий приведен в Справочнике по Google Maps JavaScript API. Перечень событий приводится в отдельном разделе для каждого объекта, содержащего события.

События пользовательского интерфейса

Для некоторых объектов Google Maps JavaScript API предусмотрено реагирование на пользовательские события, например, на сигналы от клавиатуры или мыши. Ниже приведены примеры некоторых пользовательских событий, которые может отслеживать объект google.maps.Marker:

  • 'click'
  • 'dblclick'
  • 'mouseup'
  • 'mousedown'
  • 'mouseover'
  • 'mouseout'

Полный список см. в описании класса Marker. Эти события могут выглядеть стандартными событиями DOM, однако в действительности они являются частью Maps JavaScript API. Поскольку в разных браузерах реализованы разные модели событий DOM, Maps JavaScript API предоставляет механизмы отслеживания и обработки событий DOM без необходимости подстраиваться под особенности конкретных браузеров. Также вместе с этими событиями обычно передаются аргументы, указывающие на определенное состояние пользовательского интерфейса (например, положение курсора мыши).

Изменение состояний MVC

Объекты MVC обычно содержат информацию о состоянии. При изменении свойства объекта Google Maps JavaScript API выдает событие изменения свойства. Например, API выдает событие zoom_changed на карте при изменении ее масштаба. Вы можете перехватить эти изменения состояния, вызвав метод addListener(), чтобы зарегистрировать обработчики событий также и для этого объекта.

Пользовательские события и изменения состояния MVC могут выглядеть похоже, но их обработка в программном коде обычно отличается. Например, события MVC не передают аргументы. Чтобы проверить свойство, измененное при изменении состояния MVC, вызывается соответствующий метод getProperty для этого объекта.

Обработка событий

Регистрация для получения уведомлений о событиях требует использования обработчика событий addListener(). Этот метод передаются событие для отслеживания и функция, вызываемая при возникновении указанного события.

Пример: события карты и маркера

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

function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

Просмотр примера (event-simple.html).

Совет. Если вы пытаетесь обнаружить изменение отображаемой области, следует использовать конкретное событие bounds_changed, а не составляющие события zoom_changed и center_changed. Поскольку Maps JavaScript API создает последние два события независимо друг от друга, метод getBounds() может не выдать полезные результаты, пока область просмотра окончательно не изменится. Если вы хотите выполнить метод getBounds() после такого события, обязательно отслеживайте событие bounds_changed.

Пример: события редактирования и перетаскивания фигур

После завершения действия редактирования или перетаскивания фигуры возникает событие. Список событий и некоторые фрагменты кода приведены в разделе Фигуры.

Просмотр примера (rectangle-event.html)

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

События пользовательского интерфейса в Google Maps JavaScript API обычно передают свой аргумент, который может быть получен блоком прослушивания событий. Этот аргумент сообщает состояние пользовательского интерфейса на момент события. Например, событие 'click' пользовательского интерфейса обычно передает событие MouseEvent со свойством latLng, обозначающее точку нажатия на карте. Такое поведение характерно только для событий пользовательского интерфейса, при событиях изменения состояния MVC аргументы не передаются.

Доступ к аргументам события в блоке прослушивания событий можно получить точно так же, как и к свойствам объекта. Следующий пример добавляет блок прослушивания для карты и создает маркер в точке, нажатой пользователем.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}

Просмотр примера (event-arguments.html).

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

При запуске блока прослушивания событий часто возникает необходимость в прикреплении к объекту частных и постоянных данных. JavaScript не поддерживает "частные" данные экземпляра, но поддерживает замыкания, позволяющие внутренним функциям получать доступ к внешним переменным. Замыкания применяются в блоках прослушивания событий для доступа к переменным, которые обычно не прикреплены к объектам, на которых происходят события.

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

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random()
      },
      map: map
    });
    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random()
      },
      map: map
    });
    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}

Просмотр примера (event-closure.html).

Получение и установка свойств в обработчиках событий

Никакие события изменения состояния MVC в системе событий Google Maps JavaScript API не передают аргументы при своем возникновении. (Пользовательские события передают аргументы, которые могут быть проверены.) Если необходимо проверить свойство при изменении состояния MVC, следует явно вызвать соответствующий метод getProperty() для этого объекта. Эта проверка всегда позволяет получить текущее состояние объекта MVC, которое может не соответствовать состоянию при первой активации события.

Примечание. Явная установка свойства в обработчике событий, который реагирует на изменение состояния этого конкретного свойства, может вызвать непредсказуемое или нежелательное поведение программы. Установка такого свойства запускает новое событие. Например, постоянная установка свойства в обработчике событий может привести к бесконечному циклу.

В приведенном ниже примере обработчик событий настроен реагировать на события изменения масштаба, выводя информационное окно с отображением уровня.

function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}

Просмотр примера (event-properties.html).

Отслеживание событий DOM

Модель событий Google Maps JavaScript API создает собственные события и управляет ими. Однако модель DOM (модель объектов документов) в браузере также создает собственные события и управляет ими в соответствии с используемой моделью событий браузера. Для записи этих событий и реагирования на них Maps JavaScript API предоставляет статический метод addDomListener(), обеспечивающий отслеживание событий DOM и привязку к ним.

Вызов этого вспомогательного метода записывается следующим образом:

addDomListener(instance:Object, eventName:string, handler:Function)

где instance может быть любым элементом DOM, который поддерживается браузером, включая:

  • иерархические элементы модели DOM, такие как window или document.body.myform;
  • именованные элементы, такие как document.getElementById("foo").

Следует отметить, что addDomListener() просто передает указанное событие в браузер, который обрабатывает его в соответствии с моделью событий DOM этого браузера. Большинство современных браузеров поддерживают, как минимум, модель DOM уровня 2. (Дополнительную информацию о событиях уровня DOM см. в справочном материале по уровням DOM для Mozilla.)

Если вы читали документацию ранее, возможно вы уже знакомы с одним из событий DOM, window.onload, которое мы обрабатывали через тег <body>. Мы используем это событие для запуска исходного кода JavaScript после полной загрузки страницы HTML, как показано ниже:

<script>
  function initialize() {

    // Map initialization

  }
</script>
<body onload="initialize()">
  <div id="map"></div>
</body>

Хотя здесь это событие прикреплено к элементу <body>, на самом деле оно представляет собой событие window, указывающее, что иерархия DOM под элементом window была полностью построена и прорисована.

Хотя понять все довольно просто, наличие события onload в теге <body> смешивает контент с поведением. Обычно рекомендуется отделять код контента (HTML) от кода поведения (JavaScript), а также использовать отдельный код представления (CSS). Это можно сделать, заменив в коде Maps JavaScript API включенный в строку обработчик событий onload блоком прослушивания DOM, например так:

<script>
  function initialize() {

    // Map initialization

  }

  google.maps.event.addDomListener(window, 'load', initialize);
</script>
<body>
  <div id="map"></div>
</body>

Просмотр примера (event-domListener.html)

Хотя выше приведен код Maps JavaScript API, метод addDomListener() привязывается к объекту window браузера и позволяет API взаимодействовать с объектами за пределами обычной области действия API.

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

Для удаления определенного блока прослушивания событий необходимо, чтобы он был присвоен переменной. В этом случае можно вызвать метод removeListener(), передав в него имя переменной, которой присвоен блок прослушивания.

var listener1 = marker.addListener('click', aFunction);

google.maps.event.removeListener(listener1);

Для удаления всех блоков прослушивания из определенного экземпляра нужно вызвать clearInstanceListeners(), передав имя экземпляра.

var listener1 = marker.addListener('click', aFunction);
var listener2 = marker.addListener('mouseover', bFunction);

// Remove listener1 and listener2 from marker instance.
google.maps.event.clearInstanceListeners(marker);

Чтобы удалить все блоки прослушивания определенного типа событий для определенного экземпляра, нужно вызвать метод clearListeners() и передать в него имя экземпляра вместе с именем события.

marker.addListener('click', aFunction);
marker.addListener('click', bFunction);
marker.addListener('click', cFunction);

// Remove all click listeners from marker instance.
google.maps.event.clearListeners(marker, 'click');

Дополнительную информацию см. в справочной документации по области имен google.maps.event.

Отслеживание ошибок аутентификации

Если вы хотите определять ошибки аутентификации (например, автоматическую отправку маячка) программным способом, можно подготовить соответствующую функцию обратного вызова. Если следующая глобальная функция определена, она будет вызываться в случае сбоя аутентификации. function gm_authFailure() { /* Code */ };

Оставить отзыв о...

Текущей странице
Google Maps JavaScript API
Google Maps JavaScript API
Нужна помощь? Обратитесь в службу поддержки.