Маркеры

Введение

В статье рассмотрим все что нужно знать, чтобы работать с маркерами.

Предполагается, что вы уже ознакомились с разделами «Быстрый старт» и «Карта».

Основы

Маркер

Маркер представляет собой маленькую картинку, которая связана с определенным местом на карте.

Пример создания маркера:

// Создаем маркер в Новосибирске с картинкой по умолчанию:
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 Нет

Обработчик, который вызывается в момент клика мышки по маркеру. Контекст вызова функции: если не задан clickCallbackContext, то сам маркер; если задан, то clickCallbackContext.

Функция может принимать два параметра: Первый: событие клика (объект DG.Events.Mouse) Второй: маркер по которому произошел клик.

Открыть пример в новом окне
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.

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

Но если, например, картинка — кружок, то пользователь ожидает, что на географическое положение объекта указывает именно центр. Для этого нужно заменить функцию вычисления смещения. Например, если кружнок имеет размер 30x30. Тогда зададим calculateOffset как: function() { return new DG.Point(-30/2, -30/2); }

Назначение как и у параметра offset с тем отличием, что параметр calculateOffset — функция, которая может динамически вычислять смещение. Функция должна также возвращать объект класса DG.Pixel.

Методы

Получить идентификатор маркера
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 Нет Параметр отвечает за то, будет ли изменён центр карты в случае, если балун находится за пределами видимой области.

По умолчанию: true, центр карты будет смещён так, чтобы балун попал в видимую область карты.

False : центр карты смещён не будет и балун останется за пределами видимой области.

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 Возвращает имя группы, которое задается в конструкторе группы при ее создании.