Маркеры
- Введение
- Основы
- Класс маркера DG.Markers.Common
- Конструктор
- Методы
- Получить идентификатор маркера
- Получить идентификатор контейнера маркера
- Скрыть маркер
- Показать маркер
- Получить географическое положение маркера
- Установить географическое положение маркера
- Получить иконку маркера
- Установить иконку маркера
- Получить содержимое подсказки маркера
- Установить новое содержимое подсказки маркера
- Включить режим перетаскивания маркера
- Выключить режим перетаскивания маркера
- Класс маркера DG.Markers.MarkerWithBalloon
- Конструктор
- Методы
- Отобразить балун, связанный с маркером
- Спрятать балун, связанный с маркером
- Установить новое содержимое для связанного с маркером балуна
- Узнать содержимое связанного с маркером балуна
- Установить новое содержимое header-а для связанного с маркером балуна
- Узнать содержимое header-а связанного с маркером балуна
- Установить новое содержимое footer-а для связанного с маркером балуна
- Узнать содержимое footer-а связанного с маркером балуна
- Получить размер области связанного с маркером балуна
- Установить размер области связанного с маркером балуна
- Получить содержимое подсказки маркера
- Установить новое содержимое подсказки маркера
- Проверить показан ли в данный момент балун маркера или нет.
- Включить режим перетаскивания маркера
- Выключить режим перетаскивания маркера
- Класс менеджера маркеров DG.Markers
- Класс группы маркеров DG.MarkerGroup
- Методы
- Добавить маркер в группу
- Удалить маркер из группы
- Получить список всех маркеров в группе
- Получить маркер по его порядковому номеру в группе
- Удалить все маркеры из группы
- Скрыть группу
- Отобразить группу
- Получить количество маркеров в группе
- Проверить наличие маркера в группе
- Получить порядковый номер маркера в группе
- Выполнить операцию для каждого маркера в группе
- Получить имя группы
- Методы
Введение
В статье рассмотрим все что нужно знать, чтобы работать с маркерами.
Предполагается, что вы уже ознакомились с разделами «Быстрый старт» и «Карта».
Основы
Маркер
Маркер представляет собой маленькую картинку, которая связана с определенным местом на карте.
Пример создания маркера:
// Создаем маркер в Новосибирске с картинкой по умолчанию:
var marker = new DG.Markers.Common({geoPoint: new DG.GeoPoint(82.927810142519,55.028936234826) });
// Добавим маркер на карту:
myMap.markers.add(marker);
В результате мы увидим маркер на карте для точки с координатами: долгота — 82.927810142519
, широта — 55.028936234826
. При этом, для маркера будет использоваться картинка по умолчанию. В дальнейшем мы рассмотрим класс DG.Markers.Common
подробнее.
Группы маркеров
Каждый маркер должен принадлежать определённой группе. Это дает возможность выполнять групповые операции.
Например, пусть у нас есть два типа маркеров: одни для высотных зданий, другие для частных домов. Разместив первые в одну группу, а вторые — в другую, мы можем явно манипулировать каждым из наборов маркеров.
Объект группы предоставляет наиболее полный арсенал методов, для управления маркерами. Любые операции с маркерами в группе сразу же отображаются на карте.
Менеджер маркеров
Менеджер отвечает за управление группами. А группы, в свою очередь, управляют маркерами. При этом, для удобства, часть методов по работе с маркерами есть также и в менеджере.
Менеджер маркеров доступен как свойство markers объекта карты:
// Инициализируем объект карты:
var myMap = new DG.Map("myMapId");
// Менеджер маркеров:
myMap.markers;
Любые операции с маркерами в менеджере сразу же отображаются на карте.
Класс маркера DG.Markers.Common
Ниже мы подробно рассмотрим конструктор и все методы класса маркера. Для наглядности допустим, что myMarker
— объект маркера.
Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.
Конструктор
Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
options.geoPoint | DG.GeoPoint | Да | Географическое положение точки, на которую указывает маркер. |
options.icon | DG.Icon | Нет | Картинка маркера. Ниже описан класс DG.Icon более подробно. Если icon не указан, то используется картинка по умолчанию. Также вы можете использовать функцию getAdaptiveMarker() для создания "умного" маркера, который подстраивается под экран устройства.Открыть пример в новом окне |
options.clickCallback | Function | Нет | Обработчик, который вызывается в момент клика мышки по маркеру. Контекст вызова функции: если не задан Функция может принимать два параметра: Первый: событие клика (объект |
options.clickCallbackContext | Object | Нет | Контекст вызова функции обработчика клика. Открыть пример в новом окне |
options.hoverIcon | DG.Icon | Нет | Иконка, которая будет показана при наведении курсора на маркер. Открыть пример в новом окне |
options.clickIcon | DG.Icon | Нет | Иконка, которая будет отображаться при клике на маркер. Открыть пример в новом окне |
options.hint | String | Нет | Подсказка, которая будет показана при наведении курсора на маркер. |
options.draggable | Boolean | Нет | Включает режим перетаскивания маркера. Открыть пример в новом окне |
options.dragStartCallback | Function | Нет | Обработчик, который вызывается в момент начала перетаскивания маркера. |
options.dragStopCallback | Function | Нет | Обработчик, который вызывается в момент окончания перетаскивания маркера. |
Пример:
var options = {geoPoint: new DG.GeoPoint(82.927810142519,55.028936234826) };
// Класс маркеров принимает единственный параметр - объект опций options
var marker = new DG.Markers.Common(options);
Если с параметром options.geoPoint
и options.clickCallback
понятно, то options.icon
требует пояснений.
Параметр icon
принадлежит к типу DG.Icon
. Конструктор этого класса принимает 4 параметра: url
, size
, offset
, calculateOffset
.
Конструктор DG.Icon
Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
url | String | Да | Адрес картинки. |
size | DG.Size | Да | Точный размер картинки. Например, чтобы добавить картинку шириной 30 пикселей и высотой в 40 пикселей, нужно создать объект new DG.Size(30,40) . |
calculateOffset | Function | Нет | Функция, вычисляющая смещение точки, на которую указывает маркер относительно левого верхнего угла. Должна также возвращать объект класса DG.Pixel . Функция, которая используется по умолчанию, вычисляет смещение так, чтобы маркер указывал на середину нижнего края иконки. Это положение естественно, если используется картинка маркера по умолчанию. Но если, например, картинка — кружок, то пользователь ожидает, что на географическое положение объекта указывает именно центр. Для этого нужно заменить функцию вычисления смещения. Например, если кружнок имеет размер Назначение как и у параметра offset с тем отличием, что параметр |
Методы
Получить идентификатор маркера
myMarker.getId()Возвращает:
Тип | Описание |
---|---|
String | Возвращает уникальный идентификатор маркера, который генерируется в момент его создания. |
Получить идентификатор контейнера маркера
myMarker.getContainerId()Возвращает:
Тип | Описание |
---|---|
String | Свойство «id» контейнерного DOM-элемента маркера. |
Скрыть маркер
myMarker.hide()Показать маркер
myMarker.show()Получить географическое положение маркера
myMarker.getPosition()Возвращает:
Тип | Описание |
---|---|
DG.GeoPoint | Географическое положение маркера. |
Установить географическое положение маркера
myMarker.setPosition(geoPoint)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
geoPoint | DG.GeoPoint | Да | Географическое положение маркера. |
Получить иконку маркера
myMarker.getIcon()Возвращает:
Тип | Описание |
---|---|
DG.Icon | Иконка маркера. |
Установить иконку маркера
myMarker.setIcon(icon)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
icon | DG.Icon | Да | Иконка маркера. |
Получить содержимое подсказки маркера
myMarker.getHintContent()Возвращает:
Тип | Описание |
---|---|
String | Cодержимое подсказки маркера |
Установить новое содержимое подсказки маркера
myMarker.setHintContent(hint)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
hint | String | Да | Новое содержимое подсказки маркера. |
Включить режим перетаскивания маркера
myMarker.enableDraggable()Выключить режим перетаскивания маркера
myMarker.disableDraggable()Класс маркера DG.Markers.MarkerWithBalloon
Класс маркера с балуном. Отличается от обычного маркера тем, что позволяет манипулировать связанным с маркером балуном. Расширяет интерфейс DG.Markers.Common
следующими методами.
Конструктор
Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
options.geoPoint | DG.GeoPoint | Да | Географическое положение точки, на которую указывает маркер. |
options.icon | DG.Icon | Нет | Картинка маркера. Ниже описан класс DG.Icon более подробно. Если icon не указан, то используется картинка по умолчанию. |
options.clickCallback | Function | Нет | Обработчик, который вызывается в момент клика мышки по маркеру. Контекст вызова функции: если не задан clickCallbackContext , то сам маркер; если задан, то clickCallbackContext . Функция может принимать два параметра: Первый: событие клика (объект DG.Events.Mouse) Второй: маркер по которому произошел клик. |
options.clickCallbackContext | Object | Нет | Контекст вызова функции обработчика клика. |
options.hoverIcon | DG.Icon | Нет | Иконка, которая будет показана при наведении курсора на маркер. |
options.clickIcon | DG.Icon | Нет | Иконка, которая будет отображаться при клике на маркер. |
options.hint | String | Нет | Подсказка, которая будет показана при наведении курсора на маркер. |
options.balloonOptions | Object | Да | Объект, который содержит параметры связанного с маркером балуна. |
options.balloonOptions.showLatestOnly | Boolean | Нет | Указывает на то, прятать ли связанный с маркером балун, при отображении балуна другого маркера, у которого активирован параметр showLatestOnly . Значение по умолчанию: true , балун прячется. |
options.balloonOptions.shouldHideIcon | Boolean | Нет | Прятать ли иконку маркера при отображении балуна. По умолчанию: false . |
options.balloonOptions.isClosed | Boolean | Нет | Показывать ли «крестик» в правом верхнем углу балуна, кликнув по которому пользователь может закрыть балун. По умолчанию: true , «крестик» показывается. |
options.balloonOptions.contentHtml | String | Нет | Содержимое балуна. Произвольный HTML-код. По умолчанию: пустая строка. |
options.balloonOptions.headerContentHtml | String | Нет | Содержимое header-а балуна. Произвольный HTML-код. |
options.balloonOptions.footerContentHtml | String | Нет | Содержимое footer-а балуна. Произвольный HTML-код. |
options.balloonOptions.contentSize | DG.Size | Нет | Фиксированный размер содержимого балуна. По умолчанию (т.е. когда options.contentSize не передан) размер балуна автоматически подстраивается под размер содержимого. Если параметр передан, ширина у объекта DG.Size должна быть не менее 87 пикселей. |
options.balloonOptions.adjustMapCenterToBalloon | Boolean | Нет | Параметр отвечает за то, будет ли изменён центр карты в случае, если балун находится за пределами видимой области. По умолчанию:
|
options.balloonOptions.closeCallback | Function | Нет | Функция, которая вызывается при попытке пользователя закрыть балун (клике по «крестику»). При этом если определяем эту функцию, то поведение «крестика» по умолчанию мы сбрасываем. Поэтому если внутри нашей функции мы хотим закрыть балун, нужно явно это сделать, например, с помощью функции: myMarkerWithBalloon.hide() , где myMarkerWithBalloon — объект маркера с балуном. |
options.maxContentHeight | Number | Нет | Максимальная высота балуна в пикселях, когда размер балуна автоматически подстраивается под размер содержимого (т.е. когда options.contentSize не передан). По умолчанию, высота балуна не ограничена. Если по ошибке указаны одновременно и options.contentSize , и options.maxContentHeight , то последний - игнорируется. |
options.maxContentWidth | Number | Нет | Максимальная ширина балуна в пикселях, когда размер балуна автоматически подстраивается под размер содержимого (т.е. когда options.contentSize не передан). По умолчанию, ширина ограничена значением 850 пикселей. Допустимые значения от 87 до 850 пикселей. Если по ошибке указаны одновременно и options.contentSize , и options.maxContentWidth , то последний - игнорируется. |
options.draggable | Boolean | Нет | Включает режим перетаскивания маркера. Открыть пример в новом окне |
options.dragStartCallback | Function | Нет | Обработчик, который вызывается в момент начала перетаскивания маркера. |
options.dragStopCallback | Function | Нет | Обработчик, который вызывается в момент окончания перетаскивания маркера. |
Методы
Отобразить балун, связанный с маркером
myMarker.showBalloon()Спрятать балун, связанный с маркером
myMarker.hideBalloon()Установить новое содержимое для связанного с маркером балуна
myMarker.setBalloonContent(balloonContent)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
balloonContent | String | Да | Новое содержимое балуна. |
Узнать содержимое связанного с маркером балуна
myMarker.getBalloonContent()Возвращает:
Тип | Описание |
---|---|
String | Cодержимое балуна. |
Установить новое содержимое header-а для связанного с маркером балуна
myMarker.setBalloonHeaderContent(balloonHeaderContent)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
balloonHeaderContent | String | Нет | Новое содержимое header-а балуна. |
Узнать содержимое header-а связанного с маркером балуна
myMarker.getBalloonHeaderContent()Возвращает:
Тип | Описание |
---|---|
String | Cодержимое header-а балуна. |
Установить новое содержимое footer-а для связанного с маркером балуна
myMarker.setBalloonFooterContent(balloonFooterContent)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
balloonFooterContent | String | Нет | Новое содержимое footer-а балуна. |
Узнать содержимое footer-а связанного с маркером балуна
myMarker.getBalloonFooterContent()Возвращает:
Тип | Описание |
---|---|
String | Cодержимое footer-а балуна. |
Получить размер области связанного с маркером балуна
myMarker.getBalloonContentSize()Возвращает:
Тип | Описание |
---|---|
DG.Size|Null | Размер области содержимого балуна. |
Установить размер области связанного с маркером балуна
myMarker.setBalloonContentSize(size)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
size | DG.Size | Да | Размер области содержимого балуна. Ширина у объекта DG.Size должна быть не менее 87 пикселей. |
Получить содержимое подсказки маркера
myMarker.getHintContent()Возвращает:
Тип | Описание |
---|---|
String | Cодержимое подсказки маркера |
Установить новое содержимое подсказки маркера
myMarker.setHintContent(hint)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
hint | String | Да | Новое содержимое подсказки маркера. |
Проверить показан ли в данный момент балун маркера или нет.
myMarker.isBalloonVisible()Возвращает:
Тип | Описание |
---|---|
Boolean | true — если балун показан, false — если балун скрыт. |
Включить режим перетаскивания маркера
myMarker.enableDraggable()Выключить режим перетаскивания маркера
myMarker.disableDraggable()Класс менеджера маркеров DG.Markers
Менеджер отвечает за управление группами. А группы, в свою очередь, управляют маркерами. Для удобства часть методов по работе с маркерами есть также и в менеджере.
Ниже мы подробно рассмотрим все методы класса менеджера. Для наглядности допустим, что myMap
— объект карты.
Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.
Создать менеджер маркеров явно через ключевое слово new нельзя. Он автоматически доступен как свойство markers
объекта карты.
Методы управления группами маркеров
Создать группу
myMap.markers.createGroup(groupName)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
groupName | String | Да | Название группы. Должно быть уникальным. |
Возвращает:
Тип | Описание |
---|---|
DG.MarkerGroup | Экземпляр класс DG.MarkerGroup . |
Удалить группу
myMap.markers.removeGroup(groupName)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
groupName | String | Да | Название группы. |
Возвращает:
Тип | Описание |
---|---|
Boolean | Возвращает true при успешном удалении группы, в противном случае — false . |
Получить список имен групп
myMap.markers.getAllGroupsNames()Возвращает:
Тип | Описание |
---|---|
Array | Список имен групп. Массив строк. |
Получить уже созданный объект группы по ее имени
myMap.markers.getGroup(groupName)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
groupName | String | Да | Название группы. |
Возвращает:
Тип | Описание |
---|---|
DG.MarkerGroup | null | Экземпляр класса DG.MarkerGroup , который уже был создан с помощью метода myMap.markers.createGroup . Если запросить у метода несуществующую группу, возвращает null . |
Получить имя группы по умолчанию
myMap.markers.getDefaultGroupName()Возвращает:
Тип | Описание |
---|---|
String | Название группы по умолчанию, которая есть всегда. |
Получить объект группы по умолчанию
myMap.markers.getDefaultGroup()Возвращает:
Тип | Описание |
---|---|
DG.MarkerGroup | Объект группы по умолчанию, который есть всегда. |
Фактически данный метод, является короткой записью выражения myMap.markers.getGroup(myMap.markers.getDefaultGroupName())
.
Методы управления маркерами
Рассмотрим часть методов по работе с маркерами, которую можно выполнить в менеджере. Если требуются более сложные операции, их можно выполнить средствами объекта группы.
Добавить маркер
myMap.markers.add(item, groupName)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
item | DG.Markers.Common | DG.Markers.MarkerWithBalloon | Да | Маркер. |
groupName | String | Нет | Название группы. Если параметр не передан, маркер будет добавлен в группу по умолчанию. Если название группы новое, автоматически будет создана новая группа с переданным именем. Ограничение: нельзя добавлять один и тот же маркер дважды, во-первых, в одну группу, а во-вторых, в несколько групп сразу. |
Удалить маркер
myMap.markers.remove(item)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
item | DG.Markers.Common | DG.Markers.MarkerWithBalloon | String | Да | Может быть либо объектом маркера, либо его идентификатором. Для получения идентификатора у маркера есть метод getId() . |
Получить список всех маркеров
myMap.markers.getAll()Возвращает:
Тип | Описание |
---|---|
Array | Массив маркеров. |
Получить маркер по его идентификатору
myMap.markers.get(id)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
id | String | Да | Идентификатор маркера. Для его получения у маркера есть метод getId() . |
Возвращает:
Тип | Описание |
---|---|
DG.Markers.Common | DG.Markers.MarkerWithBalloon | Маркер. |
Удалить все маркеры
myMap.markers.removeAll()При этом, хоть все маркеры и удаляются, группы остаются не тронутыми.
Получить границы маркеров
myMap.markers.getBounds()Возвращает:
Тип | Описание |
---|---|
DG.Bounds | Минимальная прямоуольная область, в которую помещаются все маркеры. |
Класс группы маркеров DG.MarkerGroup
Объект группы предоставляет наиболее полный арсенал методов для управления маркерами.
Ниже мы подробно рассмотрим все методы класса группы маркеров. Для наглядности допустим, что myGroup
— объект группы.
Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.
Создать группу маркеров явно через ключевое слово new
нельзя. Правильно это делать с помощью метода createGroup
менеджера маркеров.
Методы
Добавить маркер в группу
myGroup.add(item, index)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
item | DG.Markers.Common | DG.Markers.MarkerWithBalloon | Да | Маркер. |
index | Number | Нет | Порядковый номер добавляемого маркера в группе. При этом нумерация маркеров начинается с нуля. Если параметр не передан, маркер будет добавлен в конец группы. Ограничение: значение должно быть целым неотрицательным числом не превышающим текущее количество маркеров в группе. Таким образом обеспечивается непрерывная нумерация элементов в группе. |
Удалить маркер из группы
myGroup.remove(item)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
item | DG.Markers.Common | DG.Markers.MarkerWithBalloon | Да | Маркер. |
Получить список всех маркеров в группе
myGroup.getAll()Возвращает:
Тип | Описание |
---|---|
Array | Массив маркеров. |
Получить маркер по его порядковому номеру в группе
myGroup.get(index)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
index | Number | Да | Порядковый номер маркера в группе. Для его получения у группы есть метод indexOf(item) . |
Возвращает:
Тип | Описание |
---|---|
DG.Markers.Common | DG.Markers.MarkerWithBalloon | Маркер. |
Удалить все маркеры из группы
myGroup.removeAll()При этом, хоть все маркеры и удаляются из группы, сам объект группы остается не тронутыми.
Скрыть группу
myGroup.hide()При этом все маркеры становятся невидимыми. Более того, при добавлении новых маркеров они также остаются невидимыми.
Отобразить группу
myGroup.show()Отменяет действие метода myGroup.hide()
, все маркеры становятся видимыми.
Получить количество маркеров в группе
myGroup.length()Возвращает:
Тип | Описание |
---|---|
Number | Возвращает количество маркеров в группе. |
Проверить наличие маркера в группе
myGroup.contains(item)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
item | DG.Markers.Common | DG.Markers.MarkerWithBalloon | String | Да | Маркер или ID маркера. |
Возвращает:
Тип | Описание |
---|---|
Boollean | Возвращает true , если маркер содержится в группе. В противном случае — false . |
Получить порядковый номер маркера в группе
myGroup.indexOf(item)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
item | DG.Markers.Common | DG.Markers.MarkerWithBalloon | String | Да | Маркер или ID маркера. |
Возвращает:
Тип | Описание |
---|---|
Number | null | Возвращает порядковый номер маркера в группе. Нумерация начинается с нуля. Если маркера нет в группе, возвращает null . |
Выполнить операцию для каждого маркера в группе
myGroup.forEach(callback, context)Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
callback | Function | Да | Сallback -функция, вызываемая для каждого элемента в группе. Функция вызывается со следующими параметрами callback(marker, index, group) , где:marker — текущий маркер,index — порядковый номер текущего маркера (нумерация начинается с нуля),group — объект группы myGroup. |
Получить имя группы
myGroup.getName()Возвращает:
Тип | Описание |
---|---|
String | Возвращает имя группы, которое задается в конструкторе группы при ее создании. |