Events

The Yandex Maps API uses a Yandex-developed mechanism for working with events. The Yandex Maps API event model is used for working with browser, browser window, and DOM tree events, as well as API objects.

To use events, set up handlers — change in the state of the YMapListener class istance that is added as a child of the YMap map's root object.

Initializing the ListenerInitializing the Listener

const clickCallback = () => alert('Oh, the event!');
const mouseMoveCallback = () => console.log('I am moving the mouse...');

// Creating a Listener object.
const mapListener = new YMapListener({
  layer: 'any',
  // Adding handlers to the Listener.
  onClick: clickCallback,
  onMouseMove: mouseMoveCallback
});

// Adding the Listener to the map.
map.addChild(mapListener);

Interface of the passed handlerInterface of the passed handler

Handlers passed to the Listener have the following interfaces, depending on the type of the event they handle:

• MapEventHandler
• DomEventHandler
• BehaviorEventHandler

MapEventHandler

The MapEventHandler is used for processing map events.

The handler is called with the following parameters:

• for onUpdate method:

  • type — update.
  • camera — YMapCamera object.
  • location — YMapLocation object.
  • mapInAction — Flag of the map animation at the handler call time.

• for onResize method:

  • type — resize.
  • size — Map container size in PixelCoordinates.
  • mapInAction — Flag of the map animation at the handler call time.

Usage example:

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

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

DomEventHandler

The DomEventHandler is used for processing DOM events.

The handler is called with the following parameters:

• object: Object in which the event occurred. It contain fields type and entity. Depends on type field, entity field may be YMapFeatue, YMapMarker or YMapHotspot. If the click was made elsewhere apart from the map, the undefined value is passed.
• event — Map event. It contain both coordinates and screenCoordinates fields - geographic and screen coordinates of the location on the map that corresponds to the DOM point where the event occurred.

Usage example:

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

When adding the DOM events handler to the listener, you need to set the layer — the ID of the layer an event occurs on, after which the corresponding handler is triggered.

// Creating a new Listener.
const mapListener = new YMapListener({
  layer: 'any',
  onClick: clickHandler
});

// Updating the existing Listener.
mapListener.update({
  onClick: anotherClickHandler
});

// Updating the ID if necessary
// or if the value wasn't passed during initialization.
mapListener.update({
  layer: 'markers',
  onClick: clickHandler
});

BehaviorEventHandler

The BehaviorEventHandler handler is used for distinguishing between the types of events you can work with in the JS Maps API.

The handler is called with the following parameters:

• type — Type of behavior, that occurred on the map.
• location — YMapLocation object.
• camera — YMapCamera object.

Usage example:

const behaviorHandler = ({type}) => {
  if (type === 'pinchRotate') {
    console.log('The user rotates the map with gestures!');
  }
};

mapListener.update({onActionStart: behaviorHandler});

The behavior handler linked to onActionStart is called before all the MapEventHandler and DomEventHandler handlers. Behavior handlers linked to onActionEnd are called last:

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
});

Deleting handlersDeleting handlers

All handlers are autmatically unlinked when YMapListener stops being the YMap child:

map.removeChild(mapListener); // mapListener is a YMapListener class instance.

You can also unlink specific handlers:

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

// Later, when a handler is no longer needed.
// Deleting the dblClick handler.
mapListener.update({
  dblClick: null
});

Supported eventsSupported events

The YMapListener class object constructor and the update() method take on an object with the properties listed below. Each of these properties is a handler called when a corresponding event is triggered.

MapEventHandler

• onUpdate: Event activated when the map status changes.
• onResize: Event activated when the map size changes.
• onIndoorPlansChanged is an event triggered when changing the internal display of the building.

DomEventHandler

• onTouchStart is an event similar to the 'touchstart' native event.
• onTouchMove is an event similar to the 'touchmove' native event.
• onTouchEnd is an event similar to the 'touchend' native event.
• onTouchCancel is an event similar to the 'touchcancel' native event.
• onPointerDown is an event similar to the 'pointerdown' native event.
• onPointerMove is an event similar to the 'pointermove' native event.
• onPointerUp is an event similar to the 'pointerup' native event.
• onPointerCancel is an event similar to the 'pointercancel' native event.
• onClick is an event triggered when the left mouse button is clicked after a little pause (the pause is necessary to distinguish this click from double click).
• onDblClick is an event triggered when double-clicking the left mouse button.
• onFastClick is an event similar to the 'click' native event.
• onRightDblClick is an event triggered when double-clicking the right mouse button.
• onMouseDown is an event similar to the 'mousestart' native event.
• onMouseEnter is an event similar to the 'mouseenter' native event.
• onMouseLeave is an event similar to the 'mouseleave' native event.
• onMouseMove is an event similar to the 'mousemove' native event.
• onContextMenu is an event similar to the 'contextmenu' native event after a little pause (the pause is necessary to distinguish this click from double click).

BehaviorEventHandler

• onActionStart is an event triggered when a map-related action is started.
• onActionEnd is an event triggered when a map-related action is ended.

Behavior typesBehavior types

• drag: Dragging the object.
• pinchZoom: Zoom in/Zoom out with a gesture (using two fingers).
• scrollZoom: Zoom in/Zoom out with the mouse scroll.
• dblClick: Double mouse click.
• magnifier: Selecting a rectangular map area by holding the right mouse button and zooming the map in on the selected rectangle according to the following principle: the length of the selected rectangle is 100% of the map container's viewport width after zooming.
• oneFingerZoom: Zoom in/Zoom out with one finger.
• mouseRotate: Rotate the map with the mouse.
• mouseTilt: Tilt the map with the mouse.
• pinchRotate: Rotate the map with the gesture.
• panTilt: Pinch the map with the gesture.