События
В 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
: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
— наклон карты жестом.