События

В 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
• DomEventHandler
• BehaviorEventHandler

MapEventHandler

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

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

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

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

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

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

  console.log(location.zoom, location.center);
};

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

  • type — resize;
  • 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 Карт.

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

• type — типом поведения, которое произошло на карте;
• location — объект позиции карты YMapLocation;
• camera — объект камеры YMapCamera;

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

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 — наклон карты жестом.