Класс DG.Map

Описание
Пример использования
Конструктор
Опции
События
Методы изменения состояния карты
Методы получения состояния карты
Методы слоев и элементов управления
Методы преобразования
Другие методы
Опции определения местоположения
Опции масштабирования и перемещения
Опции перемещения
Опции масштабирования
Опции соответствия границам
Свойства
Панели карты

Описание

DG.Map — основной класс API, используется для создания и управления картами на странице.

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

Инициализация карты в элементе div с id "map", также указаны координаты центра карты и коэффициент масштабирования:

var map = DG.map('map', {
    center: [54.98, 82.89],
    zoom: 13
});

Конструктор

Конструктор	Использование	Описание
`DG.Map( <HTMLElement \| String> id, <map options> options? )`	`DG.map(…)`	Инициализирует карту в переданном DOM элементе (также можно передать его id) с необязательным набором опций, которые описаны ниже.

Опции

Опции	Тип	По умолчанию	Описание
`center`	`LatLng`	`null`	Начальный географический центр карты.
`zoom`	`Number`	`null`	Начальный уровень масштаба.
`layers`	`ILayer[]`	`null`	Слои, изначально добавленные на карту.
`minZoom`	`number`	`null`	Минимальный уровень масштабируемости карты. Переопределяет свойство minZoom используемых тайлов.
`maxZoom`	`number`	`null`	Максимальный уровень масштабируемости карты. Переопределяет свойство maxZoom используемых тайлов.
`maxBounds`	`LatLngBounds`	`null`	Если свойство установлено, карта ограничивает область просмотра согласно заданным географическим границам, "отбрасывая" пользователя назад, если он пытается выйти за пределы установленных границ, а также не позволяет уменьшить масштаб так, чтобы можно было просмотреть неразрешенные участки карты. Для установки ограничения динамически используйте метод setMaxBounds.

Опции взаимодействия

Опция	Тип	По умолчанию	Описание
`dragging`	`Boolean`	`true`	Разрешено ли перетаскивать карту мышкой.
`touchZoom`	`Boolean`	`true`	Разрешено ли изменять масштаб карты двумя пальцами на тач-устройствах.
`scrollWheelZoom`	`Boolean \| String`	`true \| ''`	Разрешено ли изменять масштаб карты колесиком мышки. Если передано значение `center`, карта всегда масштабируется в центр просматриваемой области, независимо от положения курсора.
`doubleClickZoom`	`Boolean \| String`	`true \| ''`	Разрешено ли изменять масштаб карты двойным кликом мышки. Если передано значение `center`, карта всегда масштабируется в центр просматриваемой области, независимо от положения курсора.
`boxZoom`	`Boolean`	`true`	Разрешено ли изменять масштаб карты, выделив прямоугольную область карты зажав клавишу shift.
`trackResize`	`Boolean`	`true`	Обновляется ли карта при изменении размера окна браузера.
`worldCopyJump`	`Boolean`	`false`	Опция позволяет зациклить просмотр карты с сохранением слоев и маркеров на ней.
`closePopupOnClick`	`Boolean`	`true`	Закрывать ли балуны при клике в карту.
`bounceAtZoomLimits`	`Boolean`	`false`	Опция позволяет установить анимацию восстановления карты при масштабировании пальцами на тач-устройствах на минимальных/максимальных уровнях масштаба.
`geoclicker`	`Boolean \| Object`	`false`	Включено ли геокодирование по клику (геокликер). Если `false`, тогда при клике в любой объект карты (улицы, дома, остановки) не будет отображаться информация об этом объекте. Если в качестве параметра передан объект с опциями, тогда геокликер будет включен. Опции `showPhotos` и `showBooklet` позволяют отключить в балуне организации ссылки на буклеты и фотографии.
`projectDetector`	`Boolean`	`true`	Включает или отключает механизм определения проектов 2ГИС. Проект — это агломерация, включающая крупный город и ближайшие населённые пункты.

Опции навигации клавишами

Опция	Тип	По умолчанию	Описание
`keyboard`	`Boolean`	`true`	Устанавливает фокус на карту и позволяет перемещаться по карте с помощью кнопок `+`/`-` и стрелок клавиатуры.
`keyboardPanOffset`	`Number`	`80`	Указывает, на сколько пикселей сдвинется карта при нажатии стрелки на клавиатуре.
`keyboardZoomOffset`	`Number`	`1`	Указывает, на сколько уровней изменится масштаб при нажатии на кнопки `+`/`-`.

Опции инерции карты

Опция	Тип	По умолчанию	Описание
`inertia`	`Boolean`	`true`	Если опция включена, тогда создается эффект инерции при движении карты — при перетаскивании карта продолжает движение в том же направлении какое-то время. Полезно для тач-устройств.
`inertiaDeceleration`	`Number`	`3000`	Величина, на которую замедляется движение карты, указывается в пикселях/секунду².
`inertiaMaxSpeed`	`Number`	`1500`	Максимальная скорость инерционного движения, указывается в пикселях/секунду.
`inertiaThreshold`	`Number`	`depends`	Количество миллисекунд, которое должно пройти между остановкой движения карты и отпусканием кнопки мышки, для прекращения эффекта инерции. По умолчанию `32` для тач-устройств и `14` для остальных.

Опции элементов управления

Опция	Тип	По умолчанию	Описание
`zoomControl`	`Boolean`	`true`	Добавлен ли элемент управления масштабом на карту.
`fullscreenControl`	`Boolean`	`true`	Добавлена ли кнопка включения полноэкранного режима на карту.

Опции анимации

Опция	Тип	По умолчанию	Описание
`fadeAnimation`	`Boolean`	depends	Включена ли анимация затухания тайлов. По умолчанию включена во всех браузерах поддерживающих CSS3 transitions, кроме Android.
`zoomAnimation`	`Boolean`	depends	Включена ли анимация масштабирования тайлов. По умолчанию включена во всех браузерах поддерживающих CSS3 transitions, кроме Android.
`zoomAnimationThreshold`	`Number`	4	Порог, начиная с которого будет отключаться анимация масштабирования.
`markerZoomAnimation`	`Boolean`	depends	Включена ли анимация масштабирования маркеров при анимации масштабирования карты, если выключена, тогда маркеры пропадают во время анимации карты. По умолчанию включена во всех браузерах поддерживающих CSS3 transitions, кроме Android.

События

Вы можете подписаться на следующие события, используя эти методы:

События	Данные	Описание
`click`	`MouseEvent`	Вызывается при клике в карту.
`dblclick`	`MouseEvent`	Вызывается при двойном клике в карту.
`mousedown`	`MouseEvent`	Вызывается при нажатии кнопки мышки над областью карты.
`mouseup`	`MouseEvent`	Вызывается когда пользователь отпускает кнопку мышки над областью карты.
`mouseover`	`MouseEvent`	Вызывается при наведении курсора мышки на карту.
`mouseout`	`MouseEvent`	Вызывается когда курсор мышки покидает область карты.
`mousemove`	`MouseEvent`	Вызывается когда курсор мышки перемещается над картой.
`contextmenu`	`MouseEvent`	Вызывается при нажатии правой кнопки мышки на карте, предотвращает появление стандартного контекстного меню браузера, если на это событие подписан обработчик.
`focus`	`Event`	Вызывается при установке фокуса на карту (с помощью клавиши tab, либо при клике в карту или ее перетаскивании).
`blur`	`Event`	Вызывается при потере фокуса картой.
`preclick`	`MouseEvent`	Вызывается перед кликом мышки на карте (полезно, если нужно выполнить какое-либо действие до вызова обработчика клика).
`load`	`Event`	Вызывается при инициализации карты (при первой установке ее центра и масштаба).
`viewreset`	`Event`	Вызывается когда нужно перерисовать содержимое карты (обычно при изменении масштаба или загрузке).
`movestart`	`Event`	Вызывается при начале изменения области просмотра карты (например, когда пользователь начинает перетаскивать карту).
`move`	`Event`	Вызывается во время любого передвижения карты.
`moveend`	`Event`	Вызывается при окончании передвижения краты (например, когда пользователь прекращает перетаскивать карту).
`dragstart`	`Event`	Вызывается когда пользователь начинает перетаскивать карту.
`drag`	`Event`	Вызывается когда пользователь перетаскивает карту.
`dragend`	`DragEndEvent`	Вызывается когда пользователь прекращает перетаскивать карту.
`zoomstart`	`Event`	Вызывается в начале изменения масштаба (перед анимацией изменения масштаба).
`zoomend`	`Event`	Вызывается после изменения масштаба.
`zoomlevelschange`	`Event`	Вызывается, если при добавлении или удалении слоя карты изменилось количество доступных уровней масштабирования.
`resize`	`ResizeEvent`	Вызывается при изменении размера карты.
`requestfullscreen`	`Event`	Вызывается при активации полноэкранного режима.
`cancelfullscreen`	`Event`	Вызывается при выходе из полноэкранного режима.
`autopanstart`	`Event`	Вызывается при автоматическом сдвиге карты после появления балуна.
`layeradd`	`LayerEvent`	Вызывается при добавлении нового слоя на карту.
`locationfound`	`LocationEvent`	Вызывается при успешном обнаружении местоположения пользователя (используется метод locate).
`locationerror`	`ErrorEvent`	Вызывается при возникновении ошибок во время обнаружения местоположения пользователя.
`popupopen`	`PopupEvent`	Вызывается при открытии балуна (используя метод `openPopup`).
`popupclose`	`PopupEvent`	Вызывается при закрытии балуна (используя метод `closePopup`).
`projectchange`	`ProjectEvent`	Вызывается при перемещении пользователя из одного проекта 2ГИС в другой.
`projectleave`	`ProjectEvent`	Вызывается при выходе пользователя из текущего проекта 2ГИС.
`entranceshow`	`Event`	Вызывается при отображении входа в здание.
`entrancehide`	`Event`	Вызывается при скрытии входа в здание.
`poihover`	`MetaEvent`	Вызывается при наведении курсора мышки на точку интереса.
`poileave`	`MetaEvent`	Вызывается когда курсор мышки покидает область точки интереса.
`langchange`	`LangEvent`	Вызывается при изменении языка карты.

Методы изменения состояния карты

Метод	Возвращает	Описание
`setView( <LatLng> center, <Number> zoom?, <zoom/pan options> options? )`	`this`	Устанавливает область просмотра карты (географический центр и масштаб). Дополнительно можно указать опции анимации.
`setZoom( <Number> zoom, <zoom options> options? )`	`this`	Устанавливает уровень масштаба.
`zoomIn( <Number> delta?, <zoom options> options? )`	`this`	Увеличивает масштаб карты на величину `delta` (по умолчанию `1`).
`zoomOut( <Number> delta?, <zoom options> options? )`	`this`	Уменьшает масштаб карты на величину `delta` (по умолчанию `1`).
`setZoomAround( <LatLng> latlng, <Number> zoom, <zoom options> options? )`	`this`	Масштабирует карту, сохраняя при этом указанную точку в области видимости (например, используется для масштабировании при помощи колесика мышки и двойного клика).
`fitBounds( <LatLngBounds> bounds, <fitBounds options> options? )`	`this`	Устанавливает область просмотра карты так, чтобы она содержала заданные границы на максимально возможном уровне масштаба.
`fitWorld( <fitBounds options> options? )`	`this`	Устанавливает область просмотра карты так, чтобы та отображала весь мир на максимально возможном уровне масштаба.
`panTo( <LatLng> latlng, <pan options> options? )`	`this`	Перемещает карту в указанный центр. Передвижение анимируется, если центр находится на расстоянии не более одного экрана относительно текущего.
`panInsideBounds( <LatLngBounds> bounds, <pan options> options? )`	`this`	Перемещает карту в ближайшую область просмотра, лежащую в пределах заданных границ. Можно контролировать анимацию, передав объект опций вторым параметром.
`panBy( <Point> point, <pan options> options? )`	`this`	Перемещает карту на заданное колличетво пикселей (анимируется).
`invalidateSize( <Boolean> animate?, <zoom/pan options> options? )`	`this`	Обновляет карту при изменении размера ее контейнера. Этот метод необходимо вызывать если размер контейнера изменяется динамически или карта нуждается в перерисовке (например, после отображения\скрытия родительского элемента). Если параметр `animate` установлен в `true`, тогда обновление карты анимируется.
`setMaxBounds( <LatLngBounds> bounds )`	`this`	Ограничивает область просмотра карты заданными границами (см. опцию maxBounds).
`locate( <locate options> options? )`	`this`	Пытается определить местоположение пользователя используя Geolocation API. При успешном определении вызывается событие `locationfound` с данными о местоположении, в случае ошибки будет вызвано событие `locationerror`. Опционально устанавливает область просмотра карты согласно местоположению пользователя (или отображает карту мира, если возникла ошибка геолокации). Для дополнительной информации см. опции определения местоположения.
`stopLocate()`	`this`	Останавливает отслеживание местоположения, предварительно инициированное методом `map.locate({watch: true})`.
`setLang( <String> lang )`	`String`	Устанавливает язык карты. В качестве параметра принимает код языка (например, 'it').
`remove()`	`this`	Удаляет карту и очищает все связанные с ней обработчики событий.

Методы получения состояния карты

Метод	Возвращает	Описание
`getCenter()`	`LatLng`	Возвращает географический центр области просмотра карты.
`getZoom()`	`Number`	Возвращает текущий уровень масштабирования.
`getMinZoom()`	`Number`	Возвращает минимальный уровень масштабирования.
`getMaxZoom()`	`Number`	Возвращает максимальный уровень масштабирования.
`getBounds()`	`LatLngBounds`	Возвращает географические прямоугольные границы текущей области просмотра карты.
`getBoundsZoom( <LatLngBounds> bounds, <Boolean> inside? )`	`Number`	Возвращает максимальный уровень масштабирования, при котором заданные границы полностью входят в область просмотра. Если опция `inside` установлена в `true`, тогда метод возвращает минимальный уровень зума с теми же условиями.
`getSize()`	`Point`	Возвращает текущий размер контейнера карты.
`getPixelBounds()`	`Bounds`	Возвращает пиксельные прямоугольные границы области просмотра карты.
`getPixelOrigin()`	`Point`	Возвращает пиксельные координаты левой верхней точки слоя карты.
`getLang()`	`String`	Возвращает текущий язык карты.

Методы слоев и элементов управления

Метод	Возвращает	Описание
`addLayer( <ILayer> layer, <Boolean> insertAtTheBottom? )`	`this`	Добавляет слой на карту. Если опция `insertAtTheBottom` установлена в `true`, тогда слой добавляется под всеми остальными.
`removeLayer( <ILayer> layer )`	`this`	Удаляет переданные слои с карты.
`hasLayer( <ILayer> layer )`	`Boolean`	Возвращает `true`, если слой на данный момент добавлен на карту.
`getLayer( <String>)`	`ILayer`	Возвращает cлой по заданному идентификатору. Для слоя можно указать свой идентификатор, задав ему значение options.uid.
`openPopup( <Popup> popup )`	`this`	Показывает переданный балун, предварительно закрыв все открытые.
`openPopup( <String> html \| <HTMLElement> el, <LatLng> latlng, <Popup options> options? )`	`this`	Создает балун с переданными опциями и открывает его в определенной точке на карте.
`closePopup( <Popup> popup? )`	`this`	Закрывает балун, открытый с помощью openPopup.
`addControl( <IControl> control )`	`this`	Добавляет элемент управления на карту.
`removeControl( <IControl> control )`	`this`	Удаляет элемент управления с карты.

Методы преобразования

Метод	Возвращает	Описание
`latLngToLayerPoint( <LatLng> latlng )`	`Point`	Возвращает точку на карте, соответствующую переданным географическим координатам (удобно при размещении дополнительных слоев на карте).
`layerPointToLatLng( <Point> point )`	`LatLng`	Возвращает географические координаты, соответствующие переданной точке на карте.
`containerPointToLayerPoint( <Point> point )`	`Point`	Конвертирует точку контейнера карты в точку слоя карты.
`layerPointToContainerPoint( <Point> point )`	`Point`	Конвертирует точку слоя карты в точку контейнера карты.
`latLngToContainerPoint( <LatLng> latlng )`	`Point`	Возвращает точку контейнера карты, соответствующую географическим координатам.
`containerPointToLatLng( <Point> point )`	`LatLng`	Возвращает географические координаты, соответствующие переданной точке контейнера.
`project( <LatLng> latlng, <Number> zoom? )`	`Point`	Проецирует географические координаты в пиксельные для переданного уровня масштаба (по умолчанию текущий уровень).
`unproject( <Point> point, <Number> zoom? )`	`LatLng`	Проецирует пиксельные координаты в географические для переданного уровня масштаба (по умолчанию текущий уровень).
`mouseEventToContainerPoint( <MouseEvent> event )`	`Point`	Возвращает пиксельные координаты мышки относительно левого верхнего угла контейнера карты, на основе переданного объекта `event`.
`mouseEventToLayerPoint( <MouseEvent> event )`	`Point`	Возвращает пиксельные координаты мышки относительно слоя, на основе переданного объекта `event`.
`mouseEventToLatLng( <MouseEvent> event )`	`LatLng`	Возвращает географические координаты мышки, на основе переданного объекта `event`.

Другие методы

Метод	Возвращает	Описание
`getContainer()`	`HTMLElement`	Возвращает контейнер карты.
`getPanes()`	`MapPanes`	Возвращает объект с панелями карты (для отрисовки дополнительных слоев).
`whenReady( <Function> fn, <Object> context? )`	`this`	Выполняет функцию `fn` после инициализации карты или сразу, если она была инициализирована ранее. Опционально можно передать контекст выполнения.

Опции определения местоположения

Опция	Тип	По умолчанию	Описание
`watch`	`Boolean`	`false`	Если `true`, тогда постоянно отслеживает изменения местоположения (вместо определения местоположения один раз) используя W3C метод `watchPosition`. Можно остановить отслеживание вызвав метод `map.stopLocate()`.
`setView`	`Boolean`	`true`	Если `true`, тогда автоматически устанавливает область просмотра карты в точку местоположения пользователя в соответствии с точностью определения. В случае ошибки поиска отображаетcя карта мира.
`maxZoom`	`Number`	`Infinity`	Задает максимальный уровень масштабирования при автоматическом перемещения карты (если включена опция `setView`).
`timeout`	`Number`	`10000`	Количество миллисекунд ожидания ответа геолокации перед тем как вызовется событие `locationerror`.
`maximumAge`	`Number`	`0`	Максимальное время жизни данных местоположения. Если с момента последнего поиска прошло меньше времени, чем указанно в данной опции, данные будут получены из кэша.
`enableHighAccuracy`	`Boolean`	`false`	Включает функцию повышения точности, см. описание в W3C спецификации.

Опции масштабирования и перемещения

Опция	Тип	По умолчанию	Описание
`reset`	`Boolean`	`false`	Если `true`, тогда область просмотра карты будет сброшена без каких-либо анимаций.
`pan`	`pan options`	`-`	Опции перемещения.
`zoom`	`zoom options`	`-`	Опции масштабирования.
`animate`	`Boolean`	`-`	Эквивалентно передаче `animate` и для опций масштабирования и для опций перемещения.

Опции перемещения

Опция	Тип	По умолчанию	Описание
`animate`	`Boolean`	`-`	Если `true`, тогда перемещение будет всегда анимироваться, если это возможно, в противном случае анимация не будет осуществляться.
`duration`	`Number`	`0.25`	Продолжительность анимации перемещения.
`easeLinearity`	`Number`	`0.25`	Уровень искривления затухания анимации (третий параметр Кривой Безье). Значение 1.0 означает линейную анимацию.
`noMoveStart`	`Boolean`	`false`	Если `true`, тогда при перемещении не будет инициироваться событие `movestart`.

Опции масштабирования

Опция	Тип	По умолчанию	Описание
`animate`	`Boolean`	`-`	Если не указано, тогда масштабирование будет анимироваться в пределах просматриваемой области карты. Если `true`, тогда всегда будет произведена попытка анимировать масштабирование, вне зависимости от положения источника масштабирования. Если `false`, тогда масштабирование будет происходить без анимации.

Опции соответствия границам

То же самое, что в опциях масштабирования и перемещения и дополнительно:

Опция	Тип	По умолчанию	Описание
`paddingTopLeft`	`Point`	`[0, 0]`	Задает отступ от верхнего левого угла контейнера карты, который не должен учитываться при подстройке центра и масштаба. Удобно использовать, например, если на карте приложения имеется левая панель и вы не хотите, чтобы при масштабировании под ней скрывались объекты.
`paddingBottomRight`	`Point`	`[0, 0]`	То же самое, но для нижнего правого угла карты.
`padding`	`Point`	`[0, 0]`	Эквивалентно установке и верхнего левого и нижнего правого отступов в одинаковые значения.
`maxZoom`	`Number`	`null`	Максимальный уровень зума.

Свойства

Свойства карты включают в себя обработчики взаимодействия, которые позволяют контролировать интерактивное поведение, подключение и отключение определенных возможностей карты, таких как масштабирование и тач-события (см. методы IHandler). Например:

map.doubleClickZoom.disable();

Вы также можете получить доступ к элементам управления картой, которые включены по умолчанию, например, к элементу управления масштабом:

map.zoomControl.setPosition('topright');

Свойство	Тип	Описание
`dragging`	`IHandler`	Обработчик перетаскивания карты (мышкой и тачем).
`touchZoom`	`IHandler`	Обработчик тач-масштабирования.
`doubleClickZoom`	`IHandler`	Обработчик масштабирования по двойному клику.
`scrollWheelZoom`	`IHandler`	Обработчик масштабирования по скроллу.
`boxZoom`	`IHandler`	Обработчик box-масштабирования (shift + выделение мышкой).
`keyboard`	`IHandler`	Обработчик навигации с помощью клавиатуры.
`geoclicker`	`IHandler`	Обработчик геокодирования по клику.
`projectDetector`	`IHandler`	Обработчик определения проекта 2ГИС.
`zoomControl`	`Control.Zoom`	Элемент управления масштабом.
`fullscreenControl`	`Control.FullScreen`	Кнопка включения полноэкранного режима.
`rulerControl`	`Control.Ruler`	Кнопка включения линейки.
`trafficControl`	`Control.Traffic`	Кнопка включения слоя с пробками.
`baseLayer`	`TileLayer`	Слой с тайлами 2ГИС, автоматически добавляемый на карту при её создании.

Панели карты

Объект (возвращаемый методом getPanes) содержит панели карты, которые можно использовать для собственных слоев. Основное различие панелей в параметре zIndex, определяющем порядок наложения.

Свойство	Тип	Описание
`mapPane`	`HTMLElement`	Панель, содержащая все другие панели карты.
`tilePane`	`HTMLElement`	Панель слоя тайлов.
`objectsPane`	`HTMLElement`	Панель, содержащая все панели, кроме тайловой.
`shadowPane`	`HTMLElement`	Панель для наложения теней.
`overlayPane`	`HTMLElement`	Панель геометрий, таких как ломаные и многоугольники.
`markerPane`	`HTMLElement`	Панель маркеров.
`popupPane`	`HTMLElement`	Панель балунов.