События

В API Яндекс Карт реализован собственный механизм работы с событиями. Для работы с событиями браузера, окна браузера и DOM-дерева, а также для работы с объектами API используется событийная модель API Яндекс Карт.

Использование событий реализуется через установку обработчиков — изменение состояния экземпляра класса YMapListener, который присоединяется в виде потомка корневого объекта карты YMap.

Инициализация слушателя

const clickCallback = () => alert('О, событие!');
const mouseMoveCallback = () => console.log('Я двигаю мышью...');

// Создание объекта-слушателя.
const mapListener = new YMapListener({
  layer: 'any',
  // Добавление обработчиков на слушатель.
  onClick: clickCallback,
  onMouseMove: mouseMoveCallback
});

// Добавление слушателя на карту.
map.addChild(mapListener);

Интерфейс передаваемого обработчика

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

MapEventHandler

Обработчик MapEventHandler служит для обработки событий карты.

Обработчик вызывается со следующими параметрами:

  • для метода onUpdate:

    • typeupdate;
    • camera — объект камеры YMapCamera;
    • location — объект позиции карты YMapLocation;
    • mapInAction — флаг наличия карточной анимации на момент вызова обработчика;

Пример использования onUpdate:

const updateHandler = ({type, camera, location}) => {
  console.log(type, camera.tilt);

  console.log(location.zoom, location.center);
};
  • для метода onResize:

    • typeresize;
    • size — размер контейнера карты в PixelCoordinates.
    • mapInAction — флаг наличия карточной анимации на момент вызова обработчика;
  • для метода onStateChanged:

    • state - объект состояния карты YMapState;
const stateChangedHandler = (state) => {
  console.log(state.getLayerState(ymaps3.YMapDefaultSchemeLayer.defaultProps.source + ':ground', 'tile'));
};

DomEventHandler

Обработчик DomEventHandler служит для обработки событий DOM.

Обработчик вызывается со следующими параметрами:

  • object — Объект карты, на котором произошло событие. Содержит поля type и entity. В зависимости от type, entity может быть YMapFeatue, YMapMarker или YMapHotspot. Если нажатие было совершено не на объект карты, передается undefined;
  • event — Событие карты. Содержит поля coordinates - географические координаты и screenCoordinates - экранные координаты места на карте, в котором произошло событие;

Пример использования:

const clickHandler = (object) => {
  if (object?.type === 'hotspot') {
    console.log('Clicked on hotspot!');
  }
};

При добавлении обработчика DOM-событий в слушатель необходимо задать layer — идентификатор слоя, после возникновения события в котором вызывается соответствующий обработчик:

// Создание нового слушателя.
const mapListener = new YMapListener({
  layer: 'any',
  onClick: clickHandler
});

// Обновление уже существующего слушателя.
mapListener.update({
  onClick: anotherClickHandler
});

// Обновление идентификатора, если необходимо
// или если значение не было передано при инициализации.
mapListener.update({
  layer: 'markers',
  onClick: clickHandler
});

BehaviorEventHandler

Обработчик BehaviorEventHandler служит для разграничения типов событий, с которыми можно работать в API Карт.

Обработчик вызывается с параметрами:

Пример использования:

const behaviorHandler = ({type}) => {
  if (type === 'pinchRotate') {
    console.log('Пользователь вращает карту жестами!');
  }
};

mapListener.update({onActionStart: behaviorHandler});

Обработчик поведения, привязываемый на onActionStart, вызывается перед всеми обработчиками MapEventHandler и DomEventHandler. В свою очередь, обработчики поведения, привязываемые на onActionEnd, вызываются последними:

const behaviorStartHandler = ({type}) => {
  if (type === 'dblClick') {
    console.log('1. Started double click.');
  }
};

const behaviorEndHandler = ({type}) => {
  if (type === 'dblClick') {
    console.log('3. Finished double click.');
  }
};

const dblClickHandler = () => console.log('2. Double click.');

mapListener.update({
  onActionStart: behaviorStartHandler,
  onActionEnd: behaviorEndHandler,
  dblClick: dblClickHandler
});

Удаление обработчиков

Все обработчики автоматически отвязываются, когда YMapListener перестает быть потомком YMap:

map.removeChild(mapListener); // mapListener — экземпляр класса YMapListener.

Также возможно отвязать лишь некоторые обработчики:

mapListener.update({
  onClick: clickHandler,
  dblClick: dblClickHandler,
  onFastClick: fastClickHandler
});

// Позднее, когда один из обработчиков перестал быть нужен.
// Удаление обработчика dblClick.
mapListener.update({
  dblClick: null
});

Поддерживаемые события

Конструктор объекта класса YMapListener и метод update() принимают объект со свойствами ниже. Каждое из этих свойств представляет собой обработчик, который вызывается после срабатывания соотвествующего свойству события.

MapEventHandler

  • onUpdate — событие, срабатывающее при изменении состояния карты;
  • onResize — событие, срабатывающее при изменении размера карты;
  • onStateChanged — событие, срабатывающее при изменении состояния карты;

DomEventHandler

  • onTouchStart — событие, аналогичное нативному 'touchstart';
  • onTouchMove — событие, аналогичное нативному 'touchmove';
  • onTouchEnd — событие, аналогичное нативному 'touchend';
  • onTouchCancel — событие, аналогичное нативному 'touchcancel';
  • onPointerDown — событие, аналогичное нативному 'pointerdown';
  • onPointerMove — событие, аналогичное нативному 'pointermove';
  • onPointerUp — событие, аналогичное нативному 'pointerup';
  • onPointerCancel — событие, аналогичное нативному 'pointercancel';
  • onClick — событие, срабатывающее при нажатии левой кнопкой мыши после небольшой задержки (необходима, чтобы отличить клик от двойного клика);
  • onDblClick — событие, срабатывающее при двойном нажатии левой кнопкой мыши;
  • onFastClick — событие, аналогичное нативному 'click';
  • onRightDblClick — событие, срабатывающее при двойном нажатии правой кнопкой мыши;
  • onMouseDown — событие, аналогичное нативному 'mousestart';
  • onMouseEnter — событие, аналогичное нативному 'mouseenter';
  • onMouseLeave — событие, аналогичное нативному 'mouseleave';
  • onMouseMove — событие, аналогичное нативному 'mousemove';
  • onContextMenu — событие, аналогичное нативному 'contextmenu' после небольшой задержки (необходима, чтобы отличить клик от двойного клика).

BehaviorEventHandler

  • onActionStart — событие, срабатывающее при старте какого-либо действия, связанного с картой;
  • onActionEnd — событие, срабатывающее после завершения какого-либо действия, связанного с картой.

Типы поведений

  • drag — перетаскивание объекта;
  • pinchZoom — приближение/отдаление жестом (двумя пальцами);
  • scrollZoom — приближение/отдаление колесом мыши;
  • dblClick — двойное нажатие мыши;
  • magnifier — выделение прямоугольной области карты зажатием правой кнопки мыши и приближение карты к выделенному прямоугольнику по следующему принципу: длина выделенного прямоугольника составляет 100% ширины видимой области контейнера карты после приближения;
  • oneFingerZoom — приближение/отдаление одним пальцем;
  • mouseRotate — поворот карты мышью;
  • mouseTilt — наклон карты мышью;
  • pinchRotate — поворот карты жестом;
  • panTilt — наклон карты жестом.