3. Метки и элементы управления

Marker

Создание маркера
src/ui/marker.js

Параметры

Название	Тип	Описание
element	HTMLElement	Использовать DOM элемент в качестве маркера. По умолчанию используется голубой, каплевидный svg маркер (light blue, droplet-shaped).
anchor	string default: 'center'	Определяет позицию иконки относительно ее центра. Доступные значения: 'center', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left' и 'bottom-right'.
offset	PointLike	Смещение применяемое относительно центра элемента. Отрицательные значения указывают влево и вверх.
color	string default: '#3FB1CE'	Если options.element не указан, то будет использоваться этот цвет. По умолчанию используется светло-синий цвет.
scale	number default: 1	Если options.element не указан, то будет использоваться этот масштаб. По умолчанию шкала соответствует высоте 41px и ширине 27px.
draggable	boolean default: false	Если true, то можно перетаскивать маркеры на новое место (drag and drop)
clickTolerance	number default: 0	Максимальное количество пикселей, на которое пользователь может переместить указатель мыши во время щелчка по маркеру, чтобы он считался допустимым щелчком (в отличие от перетаскивания маркера). По умолчанию используется наследование clickTolerance карты.
rotation	number default: 0	Угол поворота маркера относительно его соответствующей rotationAlignment . Положительное значение будет вращать маркер по часовой стрелке.
pitchAlignment	string default: 'auto'	'map' выравнивает маркер по плоскости карты (map). 'viewport' выравнивает маркер по плоскости экрана (viewport). 'auto' автоматически соответствует значению rotationAlignment
rotationAlignment	string default: 'auto'	'map' выравнивает поворот маркера относительно карты (map), сохраняя пеленг при вращении карты. 'viewport' выравнивает поворот маркера относительно экрана (viewport), не зависящего от поворотов карты. 'auto' эквивалентно экрану (viewport)

Пример:

var marker = new mmrgl.Marker()
  .setLngLat([30.5, 50.5])
  .addTo(map);
 
// Set options
var marker = new mmrgl.Marker({
  color: "#FFFFFF",
  draggable: true
}).setLngLat([30.5, 50.5])
  .addTo(map);

Методы

Название

Описание

addTo(map)

Прикрепляет маркер к объекту карты.

Пример:

var marker = new mmrgl.Marker()
.setLngLat([30.5, 50.5])
.addTo(map); // add the marker to the map

getElement() Возвращает HTML-элемент маркера.

getLngLat()

Получите географическое местоположение маркера.

Долгота результата может отличаться кратно 360 градусам от долготы, ранее установленной setLngLat, потому что Маркер обертывает якорную долготу по копиям мира, чтобы сохранить маркер на экране.

getOffset() Возвращает смещение маркера.

getPitchAlignment() Возвращает текущее свойство pitchAlignment маркера.

getPopup()

Возвращает экземпляр всплывающего окна, привязанный к Маркеру.

Пример:

var marker = new mmrgl.Marker()
.setLngLat([0, 0])
.setPopup(new mmrgl.Popup().setHTML("<h1>Hello World!</h1>"))
.addTo(map);
  
console.log(marker.getPopup()); // return the popup instance

getRotation() Возвращает текущий угол поворота маркера (в градусах).

getRotationAlignment() Возвращает текущее свойство rotationAlignment маркера.

isDraggable() Возвращает true, если маркер можно перетащить

remove()

Удаляет маркер с карты

Пример:

var marker = new mmrgl.Marker().addTo(map);
marker.remove();

setDraggable(shouldBeDraggable)

Задает перетаскиваемое свойство и функциональность маркера

Параметры:
shouldBeDraggable:boolean (по умолчанию false) Включает/выключает функцию перетаскивания

setLngLat(lnglat)

Устанавливает географическое положение маркера и перемещает его.

Параметры:
lnglat:LngLat где должен быть расположен маркер.

Пример:

// Create a new marker, set the longitude and latitude, and add it to the map
new mmrgl.Marker()
.setLngLat([-65.017, -16.457])
.addTo(map);

setOffset(offset)

Устанавливает смещение маркера

Параметры:
offset:PointLike смещение в пикселях, применяемый относительно центра элемента. Отрицательные значения указывают влево и вверх.

setPitchAlignment(alignment?)

Задает свойство pitchAlignment маркера.

Параметры:
alignment:string задает свойство pitchAlignment маркера. Если «auto», оно автоматически будет соответствовать поворотному rotationAlignment.

setPopup(popup)

Привязывает всплывающее окно к маркеру.

Параметры:
popup:Popup экземпляр всплывающего класса. Если значение undefined или null, то любое всплывающее окно, установленное в этом экземпляре маркера, будет снято.

Пример:

var marker = new mmrgl.Marker()
  .setLngLat([0, 0])
  .setPopup(new mmrgl.Popup().setHTML("<h1>Hello World!</h1>")) // add popup
  .addTo(map);

setRotation(rotation)

Задает свойство поворота маркера.

Параметры:
rotation:number (по умолчанию 0) Угол поворота маркера (по часовой стрелке, в градусах) относительно соответствующего Marker#setRotationAlignment setting.

setRotationAlignment(alignment)

Задает свойство rotationAlignment маркера.

Параметры:
alignment:string (по умолчанию 'auto') Устанавливает свойство rotationAlignment маркера.

togglePopup()

Открывает или закрывает экземпляр всплывающего окна, привязанный к маркеру, в зависимости от текущего состояния всплывающего окна.

Пример:

var marker = new mmrgl.Marker()
  .setLngLat([0, 0])
  .setPopup(new mmrgl.Popup().setHTML("<h1>Hello World!</h1>"))
  .addTo(map);
  
marker.togglePopup(); // toggle popup open or closed

События

Название	Описание
drag	Срабатывает во время перетаскивания
dragend	Срабатывает, когда перетаскивание заканчивается
dragstart	Срабатывает при начале перетаскивания

Создание всплывающего блока.
src/ui/popup.js

Параметры

Название	Тип	Описание
maxWidth	string default: '240px'	Строка, которая задает CSS-свойство максимальной ширины всплывающего окна, например '300px'. Чтобы убедиться, что размер всплывающего окна соответствует его содержимому, установите для этого свойства значение "none" . Доступные значения можно найти здесь: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
anchor	string default: 'bottom'	Определяет позицию иконки относительно ее центра. Доступные значения: 'center', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left' и 'bottom-right'.
offset	number \| PointLike \| Object	Смещение пикселя, примененное к местоположению всплывающего окна, указанному как: число (number), указывает расстояние от местоположения всплывающего окна PointLike указание постоянного смещение (constant offset) объект из точек вида {'center': PointLike, 'top': PointLike...}, указывает смещение для каждой позиции anchor. Отрицательные смещения указывают влево и вверх.
className	string	Имя класса для контейнера
focusAfterOpen	boolean default: true	Если true, то после открытия окна, будет произведена попытка установить фокус (курсор) в первый элемент внутри окна, который это поддерживает, например <input/>.
closeOnMove	boolean default: false	Если true, то всплывающее окно будет закрыто при перемещении карты.
closeOnClick	boolean default: true	Если true, то всплывающее окно будет закрыто при нажатии на карту.
closeButton	boolean default: true	Если true, то в правом верхнем углу всплывающего окна появится кнопка закрытия.

Пример:

var markerHeight = 50, markerRadius = 10, linearOffset = 25;
var popupOffsets = {
  'top': [0, 0],
  'top-left': [0,0],
  'top-right': [0,0],
  'bottom': [0, -markerHeight],
  'bottom-left': [linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
  'bottom-right': [-linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
  'left': [markerRadius, (markerHeight - markerRadius) * -1],
  'right': [-markerRadius, (markerHeight - markerRadius) * -1]
};
var popup = new mmr
gl.Popup({offset: popupOffsets, className: 'my-class'})
  .setLngLat(e.lngLat)
  .setHTML("<h1>Hello World!</h1>")
  .setMaxWidth("300px")
  .addTo(map);

Методы

Название

Описание

addClassName(className)

Добавляет CSS класс к элементу всплывающего контейнера.

Параметры:
className:string Не пустая строка с именем класса для добавления к всплывающему контейнеру

Пример:

let popup = new mmrgl.Popup()
popup.addClassName('some-class')

addTo(map)

Добавляет всплывающее окно на карту.

Пример:

new mmrgl.Popup()
.setLngLat([0, 0])
.setHTML("<h1>Null Island</h1>")
.addTo(map);

getElement()

Возвращает HTML-элемент всплывающего окна.

Пример:

// Change the `Popup` element's font size
var popup = new mmrgl.Popup()
  .setLngLat([-96, 37.8])
  .setHTML("<p>Hello World!</p>")
  .addTo(map);
var popupElem = popup.getElement();
popupElem.style.fontSize = "25px";

getLngLat()

Возвращает географическое местоположение якоря всплывающего окна.

Долгота результата может отличаться кратно 360 градусам от долготы, ранее установленной setLngLat, потому что Popup обертывает якорную долготу по копиям мира, чтобы сохранить всплывающее окно на экране.

getMaxWidth() Возвращает максимальную ширину всплывающего окна.

isOpen() Возвращает true, если всплывающее окно открыто, false, если оно закрыто.

remove()

Удаляет всплывающее окно с карты, на которую оно было добавлено.

Пример:

var popup = new mmrgl.Popup().addTo(map);
popup.remove();

removeClassName(className)

Удаляет CSS класс из всплывающего элемента контейнера.

Параметры:
className:string Не пустая строка с именем класса CSS для удаления из всплывающего контейнера

Пример:

let popup = new mmrgl.Popup()
popup.removeClassName('some-class')

setDOMContent(htmlNode)

Устанавливает содержимое всплывающего окна на элемент, предоставленный в качестве узла DOM.

Параметры:
htmlNode:Node Узел DOM, который будет использоваться в качестве содержимого для всплывающего окна.

Пример:

// create an element with the popup content
var div = window.document.createElement('div');
div.innerHTML = 'Hello, world!';
var popup = new mmrgl.Popup()
  .setLngLat(e.lngLat)
  .setDOMContent(div)
  .addTo(map);

setHTML(html)

Устанавливает содержимое всплывающего окна в HTML-код, предоставленный в виде строки.

Этот метод не выполняет фильтрацию HTML или дезинфекцию и должен использоваться только с доверенным контентом. Рассмотрим Popup#setText, если содержимое является ненадежной текстовой строкой.

Параметры:
html:string Строка, представляющая HTML-содержимое всплывающего окна.

Пример:

var popup = new mmrgl.Popup()
  .setLngLat(e.lngLat)
  .setHTML("<h1>Hello World!</h1>")
  .addTo(map);

setLngLat(lnglat)

Устанавливает географическое местоположение якоря всплывающего окна и перемещает его к нему. Заменяет поведение trackPointer().

Параметры:
lnglat:LngLatLike географическое положение, которое нужно установить в качестве якоря всплывающего окна.

setMaxWidth(maxWidth)

Устанавливает максимальную ширину всплывающего окна. Это установка свойства CSS max-width. Доступные значения можно найти здесь: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width

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

setOffset(offset?)

Устанавливает смещение всплывающего окна.

Параметры:
offset:Offset смещение попапа

setText(text)

Устанавливает содержимое всплывающего окна в виде строки текста.

Эта функция создает текстовый узел в DOM, поэтому она не может вставлять необработанный HTML. Используйте этот метод для защиты от XSS, если всплывающее содержимое предоставлено пользователем.

Параметры:
text:string текстовое содержимое для всплывающего окна.

Пример:

var popup = new mmrgl.Popup()
  .setLngLat(e.lngLat)
  .setText('Hello, world!')
  .addTo(map);

toggleClassName(className)

Добавьте или удалите данный класс CSS во всплывающем контейнере, в зависимости от того, есть ли в контейнере в данный момент этот класс.

Параметры:
className:string не пустая строка с именем класса CSS для добавления/удаления

Пример:

let popup = new mmrgl.Popup()
popup.toggleClassName('toggleClass')

trackPointer()

Отслеживает всплывающий якорь до положения курсора на экранах с помощью указателя (он будет скрыт на сенсорных экранах). Заменяет поведение setLngLat. Для большинства случаев использования установите closeOnClick и closeButton в false.

Пример:

var popup = new mmrgl.Popup({ closeOnClick: false, closeButton: false })
  .setHTML("<h1>Hello World!</h1>")
  .trackPointer()
  .addTo(map);

События

Название

Описание

Срабатывает, когда всплывающее окно закрывается вручную или программно.

Пример:

// Create a popup
var popup = new mmrgl.Popup();
// Set an event listener that will fire
// any time the popup is closed
popup.on('close', function(){
  console.log('popup was closed');
});

open

Срабатывает, когда всплывающее окно открывается вручную или программно.

Пример:

// Create a popup
var popup = new mmrgl.Popup();
// Set an event listener that will fire
// any time the popup is opened
popup.on('open', function(){
  console.log('popup was opened');
});

IControl (Спецификация для разработчика)

Интерфейс для элементов интерактивного управления, добавленных на карту. Это спецификация для разработчиков: это не метод или класс.

Элементы управления должны реализовывать onAdd и onRemove так же это должен быть <div>. Чтобы использовать стиль элемента управления MMR GL JS, добавьте класс mmrgl-ctrl.
src/ui/map.js

Пример:

// Control implemented as ES6 class
class HelloWorldControl {
    onAdd(map) {
        this._map = map;
        this._container = document.createElement('div');
        this._container.className = 'mmrgl-ctrl';
        this._container.textContent = 'Hello, world';
        return this._container;
    }
  
    onRemove() {
        this._container.parentNode.removeChild(this._container);
        this._map = undefined;
    }
}
  
// Control implemented as ES5 prototypical class
function HelloWorldControl() { }
  
HelloWorldControl.prototype.onAdd = function(map) {
    this._map = map;
    this._container = document.createElement('div');
    this._container.className = 'mmrgl-ctrl';
    this._container.textContent = 'Hello, world';
    return this._container;
};
  
HelloWorldControl.prototype.onRemove = function () {
    this._container.parentNode.removeChild(this._container);
    this._map = undefined;
};

Методы

Название	Описание
getDefaultPosition()	При необходимости укажите положение по умолчанию для этого элемента управления. Если этот метод реализован и Map#addControl вызывается без параметра position, то в качестве позиции элемента управления будет использоваться значение, возвращаемое getDefaultPosition.
onAdd(map)	Зарегистрируйте элемент управления на карте и дайте ему возможность зарегистрировать лисенер событий и ресурсы. Этот метод вызывается Map#addControl внутренне.
onRemove(map)	Отмените регистрацию элемента управления на карте и дайте ему возможность отсоединить лисенер событий и ресурсы. Этот метод вызывается Map#removeControl внутренне.

NavigationControl

Элемент управления NavigationControl содержит кнопки масштабирования (zoom) и компас (compass).
src/ui/control/navigation_control.js

Параметры

Название	Тип	Описание
showCompass	boolean default: true	Если true, то кнопка компаса отображает.
showZoom	boolean default: true	Если true, то кнопки увеличения и уменьшения масштаба отображаются.
visualizePitch	boolean default: false	Если true, то шаг визуализируется вращением оси X.

Пример:

var nav = new mmrgl.NavigationControl();
map.addControl(nav, 'top-left');

GeolocateControl

Элемент управления GeolocateControl предоставляет кнопку, которая использует API геолокации браузера для определения местоположения пользователя на карте.

Не все браузеры поддерживают геолокацию, и некоторые пользователи могут отключить эту функцию. Поддержка геолокации для современных браузеров, включая Chrome, требует, чтобы сайты обслуживались по протоколу HTTPS. Если поддержка геолокации недоступна, то GeolocateControl будет отображаться как отключенный.

Уровень масштабирования будет зависеть от точности геолокации, обеспечиваемой устройством.

GeolocateControl имеет два режима. Если trackUserLocation имеет значение false (по умолчанию), то элемент управления действует как кнопка, которая при нажатии настраивает камеру карты на местоположение пользователя. Если пользователь перемещается, карта не обновляется. Это больше всего подходит для рабочего стола. Если trackUserLocation имеет значение true, то элемент управления действует как кнопка переключения, которая отслеживает передвижение пользователя. В этом режиме GeolocateControl имеет три состояния взаимодействия:

'active' — камера карты автоматически обновляется по мере изменения местоположения пользователя, сохраняя точку местоположения в центре.
'passive' — точка местоположения пользователя автоматически обновляется, но камера карты-нет. Происходит при инициировании пользователем перемещения карты.
'disabled' — происходит, если Геолокация недоступна, отключена или запрещена.

Этими состояниями взаимодействия нельзя управлять программно, скорее они задаются на основе взаимодействия с пользователем.
src/ui/control/geolocate_control.js

Параметры

Название	Тип	Описание
positionOptions	Object default: { enableHighAccuracy:false, timeout:6000 }	Объект PositionOptions API геолокации.
fitBoundsOptions	Object default: { maxZoom:15 }	Map#fitBounds объект Options, который используется, когда карта перемещается и масштабируется до местоположения пользователя. По умолчанию используется maxZoom 15, чтобы ограничить масштаб карты для очень точных местоположений.
trackUserLocation	boolean default: false	Если true, то элемент управления Geolocate становится переключателем и когда он активен карта будет получать обновления о местоположении пользователя по мере его изменений.
showAccuracyCircle	boolean default: true	По умолчанию, если showUserLocation имеет значение true, вокруг местоположения пользователя будет нарисован прозрачный круг, указывающий точность местоположения пользователя (точность 95%). Установите значение false для отключения. Всегда отключается, когда showUserLocation имеет значение false.
showUserLocation	boolean default: true	По умолчанию точка будет отображаться на карте в месте расположения пользователя. Установите значение false для отключения.

Пример:

map.addControl(new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
}));

Методы

Название

Описание

trigger

Программно запросите и переместите карту в местоположение пользователя.

Пример:

// Initialize the geolocate control.
var geolocate = new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
map.on('load', function() {
  geolocate.trigger();
});

События

Название

Описание

error

Запускался при каждом обновлении позиции API геолокации, которое возвращалось как ошибка.

Параметры:
data:PositionError возвращаемый объект PositionError из обратного вызова в Geolocation.getCurrentPosition() или Geolocation.watchPosition().

Пример:

// Initialize the geolocate control.
var geolocate = new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an error event occurs.
geolocate.on('error', function() {
  console.log('An error event has occurred.')
});

geolocate

Запускался при каждом обновлении позиции API геолокации, которое возвращалось как успешное.

Параметры:
data:Position возвращаемый объект Position из вызова в Geolocation.getCurrentPosition() или Geolocation.watchPosition().

Пример:

// Initialize the geolocate control.
var geolocate = new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a geolocate event occurs.
geolocate.on('geolocate', function() {
  console.log('A geolocate event has occurred.')
});

outofmaxbounds

Срабатывает при каждом обновлении позиции API геолокации, которое возвращается как успешное, но позиция пользователя находится вне maxBounds карты.

Параметры:
data:Position возвращаемый объект Position из вызова в Geolocation.getCurrentPosition() или Geolocation.watchPosition().

Пример:

// Initialize the geolocate control.
var geolocate = new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when an outofmaxbounds event occurs.
geolocate.on('outofmaxbounds', function() {
  console.log('An outofmaxbounds event has occurred.')
});

trackuserlocationend

Срабатывает, когда элемент управления Geolocate переходит в фоновое состояние, это происходит, когда пользователь меняет камеру во время активной позиции. Это применимо только в том случае, если trackUserLocation имеет значение true. В фоновом режиме точка на карте будет обновляться с обновлениями местоположения, но камера - нет.

Пример:

// Initialize the geolocate control.
var geolocate = new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a trackuserlocationend event occurs.
geolocate.on('trackuserlocationend', function() {
  console.log('A trackuserlocationend event has occurred.')
});

trackuserlocationstart

Срабатывает, когда элемент управления Geolocate переходит в активное состояние, это происходит либо при первом получении успешной позиции API геолокации для пользователя (за этим последует событие geolocate), либо пользователь нажимает кнопку geolocate, находясь в фоновом состоянии, которое использует последнюю известную позицию для повторного центрирования карты и входа в активное состояние (событие geolocate не последует, если местоположение пользователя не изменится).

Пример:

// Initialize the geolocate control.
var geolocate = new mmrgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true
});
// Add the control to the map.
map.addControl(geolocate);
// Set an event listener that fires
// when a trackuserlocationstart event occurs.
geolocate.on('trackuserlocationstart', function() {
  console.log('A trackuserlocationstart event has occurred.')
});

ScaleControl

Элемент управления ScaleControl отображает отношение расстояния на карте к соответствующему расстоянию на земле.
src/ui/control/scale_control.js

Параметры

Название	Тип	Описание
maxWidth	number default: '100'	Максимальная длина элемента управления масштабом в пикселях.
unit	string default: 'metric'	Единица измерения расстояния ('imperial', 'metric' или 'nautical').

Пример:

var scale = new mmrgl.ScaleControl({
    maxWidth: 80,
    unit: 'imperial'
});
map.addControl(scale);
scale.setUnit('metric');

Методы

Название	Описание
setUnit(unit)	Установите единицу измерения расстояния на шкале Параметры: unit:Unit Единица измерения расстояния ( «imperial» , «metric» или «nautical»).

Название

Описание

setUnit(unit)

Установите единицу измерения расстояния на шкале

Параметры:

unit:Unit Единица измерения расстояния ( «imperial» , «metric» или «nautical»).

FullscreenControl

Элемент управления FullscreenControl содержит кнопку для переключения карты в полноэкранный режим и обратно.
src/ui/control/fullscreen_control.js

Параметры

Название	Тип	Описание
container	HTMLElement	container — это элемент DOM, который открывать в полноэкранном режиме. По умолчанию контейнер карты будет использоваться для полноэкранного режиме.

Пример:

map.addControl(new mmrgl.FullscreenControl({container:
  document.querySelector('body')
}));

Обновлено 30 ноября 2022 г.