Мероприятия

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

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

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

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

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

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

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

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

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

• 'click'
• 'drag'
• 'dragend'
• 'dragstart'
• 'gmp-click'

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

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

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

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

Как обрабатывать события

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

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

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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const myLatlng = { lat: -25.363, lng: 131.044 };

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: myLatlng,
      mapId: "DEMO_MAP_ID",
    }
  );

  const marker = new google.maps.marker.AdvancedMarkerElement({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.position as google.maps.LatLng);
    }, 3000);
  });

  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.position as google.maps.LatLng);
  });
}

initMap();
index.ts

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
    mapId: "DEMO_MAP_ID",
  });
  const marker = new google.maps.marker.AdvancedMarkerElement({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.position);
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.position);
  });
}

initMap();
index.js

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

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

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

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

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

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

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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
      mapId: "DEMO_MAP_ID",
    }
  );

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng: google.maps.LatLng, map: google.maps.Map) {
  new google.maps.marker.AdvancedMarkerElement({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

initMap();
index.ts

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary(
    "marker",
  );
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

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

initMap();
index.js

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

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

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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
      mapId: "DEMO_MAP_ID",
    }
  );

  const bounds: google.maps.LatLngBoundsLiteral = {
    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.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const marker = new google.maps.marker.AdvancedMarkerElement({
      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: google.maps.marker.AdvancedMarkerElement,
  secretMessage: string
) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.map, marker);
  });
}

initMap();
index.ts

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });
  const 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.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const marker = new google.maps.marker.AdvancedMarkerElement({
      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) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.map, marker);
  });
}

initMap();
index.js

Как получить и установить свойства в обработчиках событий

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

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

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

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: originalMapCenter,
    }
  );

  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);

  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom()!);
  });
}

initMap();
index.ts

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: originalMapCenter,
  });
  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);
  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom());
  });
}

initMap();
index.js

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

Модель событий Maps JavaScript API создает собственные события и управляет ими. Однако DOM (модель 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 или выше. Подробные сведения можно найти в справочной документации Mozilla по уровням DOM.

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  const mapDiv = document.getElementById("map") as HTMLElement;
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

initMap();
index.ts

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const mapDiv = document.getElementById("map");
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

initMap();
index.js

<html>
  <head>
    <title>Listening to DOM Events</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

Хотя приведенный выше код является кодом Maps JavaScript API, метод addDomListener() привязывается к объекту window браузера и позволяет 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 */ };