Clusterer

Расширяет IChildOnMap, ICustomizable, IEventEmitter, IParentOnMap.

Кластеризатор геообъектов. Кластеризует объекты в видимой области карты. Если объект не попадает в видимую область карты, он не будет добавлен на карту. Обратите внимание, что кластеризатор не поддерживает реакцию на изменение координат объектов (программно, или в результате драга). Если у объекта в кластеризаторе необходимо изменить координаты, следует удалить объект из кластеризатора, поменять его геометрию, а затем добавить обратно.

См.: ClusterPlacemark

Конструктор | Поля | События | Методы

Конструктор

Clusterer([options])

Параметры:

Параметр	Значение по умолчанию	Описание
`options`	—	Тип: Object Опции. Опции для дочерних объектов-кластеров задаются с префиксом "cluster". См. ClusterPlacemark.
`options.gridSize`	64	Тип: Number Размер ячейки кластеризации в пикселях. Значение должно быть равно 2^n (в область 256 на 256 пикселей должно умещаться ровное количество ячеек).
`options.groupByCoordinates`	false	Тип: Boolean Специальный режим работы кластеризатора при котором кластеры образуются только из геобъектов с одинаковыми координатами.
`options.hasBalloon`	true	Тип: Boolean Флаг наличия у кластеризатора поля .balloon. Если при клике на кластер не нужно открывать балун, рекомендуется установить эту опцию в значение false, чтобы избежать лишних инициализаций;
`options.hasHint`	true	Тип: Boolean Флаг наличия у кластеризатора поля .hint. Если при наведении на кластер не нужно показывать всплывающую подсказку, рекомендуется установить эту опцию в значение false, чтобы избежать лишних инициализаций;
`options.margin`	10	Тип: Number\|Number[] Число или массив чисел, задающие отступ для центра кластера относительно ячеек кластеризации. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это вертикальные и горизонтальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left.
`options.maxZoom`	Infinity	Тип: Number[] Максимальный коэффициент масштабирования карты, на котором происходит кластеризация объектов. Даже если кластеризация отключена, будут показаны только объекты в видимой области карты.
`options.minClusterSize`	2	Тип: Number Минимальное количество объектов, образующих кластер.
`options.preset`	—	Тип: String Ключ предустановленных опций кластеризатора. Список ключей, доступных в пакете package.clusters, содержится в описании option.presetStorage.
`options.showInAlphabeticalOrder`	false	Тип: Boolean Показывать метки в балуне в алфавитном порядке при нажатии на кластер. Геообъекты кластера сортируются по специальным полям в данных этих геообъектов - clusterCaption (или balloonContentHeader, если предыдущее поле не определено). По умолчанию геообъекты показываются в порядке добавления в кластеризатор.
`options.useMapMargin`	true	Тип: Boolean Нужно ли учитывать отступы карты map.margin.Manager при приближении карты после клика на кластере.
`options.viewportMargin`	128	Тип: Number\|Number[] Отступ для области, в которой производится кластеризация. Кластеризация проводится для видимой области карты. С помощью данной опции область кластеризации расширяется по отношению к видимой области карты.
`options.zoomMargin`	0	Тип: Number\|Number[] Отступы от границ видимой области карты, которые соблюдаются при приближении карты после клика на кластере. Рекомендуется устанавливать значение опции в соответствии с размером иконок кластеров и меток. Например, если метка попадает в видимую область карты только нижним концом ножки, стоит выставить ненулевой отступ top, чтобы метка оставалась полностью видна после того, как кластер распался. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left.

Пример:

// Создание кластеризатора

// Создание карты, требующей кластеризации геообъектов
var map = new ymaps.Map('mapsID', { center: [56.034, 36.992], zoom: 8 }),
// Создание массива геообъектов
myGeoObjects = [];
myGeoObjects[0] = new ymaps.GeoObject({
    geometry: { type: "Point", coordinates: [56.034, 36.992] },
    properties: {
        clusterCaption: 'Geo object №1',
        balloonContentBody: 'Balloon content for geo object №1'
    }
});
myGeoObjects[1] = new ymaps.GeoObject({
    geometry: { type: "Point", coordinates: [56.021, 36.983] },
    properties: {
        clusterCaption: 'Geo object №2',
        balloonContentBody: 'Balloon content for geo object №2'
   }
});

// Создание кластера и запрещение масштабирования карты при щелчке по кластеру
var clusterer = new ymaps.Clusterer({ clusterDisableClickZoom: true });
clusterer.add(myGeoObjects);
map.geoObjects.add(clusterer);

Поля

Имя	Тип	Описание
balloon	clusterer.Balloon	Балун кластеризатора.
balloonclose		Закрытие балуна. target - ссылка на менеджер балуна кластеризатора; cluster - ссылка на объект-кластер. Экземпляр класса Event.
balloonopen		Открытие балуна на кластере. Имена полей, доступных через метод Event.get: target - ссылка на менеджер балуна кластеризатора; cluster - ссылка на объект-кластер. Экземпляр класса Event.
events	IEventManager	Менеджер событий. Унаследовано от IEventEmitter.
hint	clusterer.hint	Хинт кластеризатора.
options	IOptionManager	Менеджер опций. Унаследовано от ICustomizable.

События

Имя	Описание
hintclose	Закрытие хинта. Экземпляр класса Event.
hintopen	Открытие хинта на кластере. Экземпляр класса Event.
mapchange	Сменилась карта. Поля данных: oldMap - старая карта; newMap - новая карта. Унаследовано от IParentOnMap.
optionschange	Изменение в опциях объекта. Унаследовано от ICustomizable.
parentchange	Сменился родительский объект. Поля данных: oldParent - старый родитель; newParent - новый родитель. Унаследовано от IChild.

Методы

Имя	Возвращает	Описание
add(objects)	Clusterer	Добавляет геообъект или массив геообъектов в кластеризатор.
createCluster(center, geoObjects)	IGeoObject	Функция для создания кластера кластеризатором. Вызывается кластеризатором непосредственно в процессе кластеризации. Принимает на вход центр кластера и массив геообъектов, попадающих в данный кластер. Возвращает кластер, который потом будет добавлен на карту. Если требуется, чтобы кластеризатор создавал пользовательские объекты-кластеры, следует переопределить этот метод у кластеризатора.
getBounds()	Number[][]\|null	Возвращает географические координаты прямоугольной области, охватывающей все элементы кластера.
getClusters()	IGeoObject[]	Метод для получения текущего массива объектов-кластеров. Обратите внимание, что объекты-кластеры меняются при изменении масштаба карты или при сдвиге центра карты. Если необходимо выполнять операции над всеми кластерами, корректнее переопределить метод createCluster и добавлять необходимые операции в его вызов.
getGeoObjects()	IGeoObject[]	Возвращает массив геообъектов, добавленных в кластеризатор.
getMap()	Map	Возвращает ссылку на карту. Унаследован от IParentOnMap.
getObjectState(geoObject)	Object	Функция для получения информации о текущем состоянии объекта, добавленного в кластеризатор.
getParent()	IParentOnMap\|null	Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен. Унаследован от IChildOnMap.
remove(objects)	Clusterer	Удаляет геообъекты из кластеризатора.
removeAll()	Clusterer	Удаляет все геообъекты из кластеризатора.
setParent(parent)	IChildOnMap	Устанавливает родительский объект. Если передать значение null, то элемент управления будет только удален из текущего родительского объекта. Унаследован от IChildOnMap.

Описание полей

balloon

{clusterer.Balloon} balloon

Балун кластеризатора.

balloonclose

balloonclose

Закрытие балуна.

target - ссылка на менеджер балуна кластеризатора;
cluster - ссылка на объект-кластер.
Экземпляр класса Event.

balloonopen

balloonopen

Открытие балуна на кластере. Имена полей, доступных через метод Event.get:

target - ссылка на менеджер балуна кластеризатора;
cluster - ссылка на объект-кластер.
Экземпляр класса Event.

Пример:

clusterer.events.add('balloonopen', function (e) {
    var clusterPlacemark = e.get('cluster');
});

hint

{clusterer.hint} hint

Хинт кластеризатора.

Описание событий

hintclose

Закрытие хинта. Экземпляр класса Event.

hintopen

Открытие хинта на кластере. Экземпляр класса Event.

Описание методов

add

{Clusterer} add(objects)

Добавляет геообъект или массив геообъектов в кластеризатор.

Возвращает ссылку на себя.

Параметры:

Параметр

Значение по умолчанию

Описание

objects*

—

Тип: IGeoObject

IGeoObject[]

Массив геообъектов или единичный геообъект.

* Обязательный параметр/опция.

Пример:

var myPlacemark = new ymaps.Placemark([35, 21]);
clusterer.add(myPlacemark);
var placemarks = [
    new ymaps.Placemark([44, 55]),
    new ymaps.Placemark([34, 45])
];
clusterer.add(placemarks);

createCluster

{IGeoObject} createCluster(center, geoObjects)

Функция для создания кластера кластеризатором. Вызывается кластеризатором непосредственно в процессе кластеризации. Принимает на вход центр кластера и массив геообъектов, попадающих в данный кластер. Возвращает кластер, который потом будет добавлен на карту. Если требуется, чтобы кластеризатор создавал пользовательские объекты-кластеры, следует переопределить этот метод у кластеризатора.

Возвращает объект-кластер. По умолчанию создает экземпляры класса ClusterPlacemark.

Параметры:

Параметр

Значение по умолчанию

Описание

center*

—

Тип: Number[]

Центр кластера в геокоординатах.

geoObjects*

—

Тип: IGeoObject[]

Массив плейсмарков в кластере.

* Обязательный параметр/опция.

Пример:

// Зададим всплывающую подсказку кластерам в зависимости от состава.
var clusterer = new ymaps.Clusterer();
clusterer.createCluster = function (center, geoObjects) {
     // Создаем метку-кластер с помощью стандартной реализации метода.
    var clusterPlacemark = ymaps.Clusterer.prototype.createCluster.call(this, center, geoObjects),
        geoObjectsLength = clusterPlacemark.getGeoObjects().length,
        hintContent;
    if (geoObjectsLength < 10) {
        hintContent = 'Мало меток';
    } else if (geoObjectsLength < 100) {
        hintContent = 'Нормально так меток';
    } else {
        hintContent = 'Меток навалом';
    }
    clusterPlacemark.properties.set('hintContent', hintContent);
    return clusterPlacemark;
};

getBounds

{Number[][]|null} getBounds()

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

Пример:

var clusterer = new ymaps.Clusterer();
clusterer.add(myPlacemarks);
map.setBounds(clusterer.getBounds());
map.geoObjects.add(clusterer);

getClusters

{IGeoObject[]} getClusters()

Метод для получения текущего массива объектов-кластеров. Обратите внимание, что объекты-кластеры меняются при изменении масштаба карты или при сдвиге центра карты. Если необходимо выполнять операции над всеми кластерами, корректнее переопределить метод createCluster и добавлять необходимые операции в его вызов.

**Возвращает **массив кластеров, добавленных на карту в данный момент.

Пример:

map.events.add('boundschange', function () {
    var clusters = clusterer.getClusters();
    alert('Карта была перемещена и сейчас показывается ' + clusters.length + ' кластеров.');});

getGeoObjects

{IGeoObject[]} getGeoObjects()

Возвращает массив геообъектов, добавленных в кластеризатор.

Пример:

// Посчитаем количество объектов, попавших в видимую область карты.
var geoObjects = clusterer.getGeoObjects(),
    shownObjectsCounter = 0;
for (var i = 0, l = geoObjects.length; i < l; i++) {
    if (clusterer.getObjectState(geoObjects[i]).isShown) {
        shownObjectsCounter++;
    }
}
alert('Сейчас на карте показаны ' + shownObjectsCounter + ' меток из ' + geoObjects.length + '.');

getObjectState

{Object} getObjectState(geoObject)

Функция для получения информации о текущем состоянии объекта, добавленного в кластеризатор.

Возвращает объект, содержащий следующие поля:

isShown - признак, указывающий, находится ли объект в видимой области карты;
cluster - ссылка на кластер, в который добавлен объект;
isClustered - признак, указывающий, попал ли объект в состав кластера.

Параметры:

Параметр

Значение по умолчанию

Описание

geoObject*

—

Тип: IGeoObject

Геообъект, для которого нужно получить состояние.

* Обязательный параметр/опция.

Пример:

// Открытие балуна кластера с выбранным объектом.
// Получим данные о состоянии объекта внутри кластера.
var geoObjectState = clusterer.getObjectState(myGeoObjects[1]);
// Проверяем, находится ли объект в видимой области карты.
if (geoObjectState.isShown) {
    // Если объект попадает в кластер, открываем балун кластера с нужным выбранным объектом.
    if (geoObjectState.isClustered) {
        geoObjectState.cluster.state.set('activeObject', myGeoObjects[1]);
        clusterer.balloon.open(geoObjectState.cluster);

    } else {
        // Если объект не попал в кластер, открываем его собственный балун.
        myGeoObjects[1].balloon.open();
    }
}

remove

{Clusterer} remove(objects)

Удаляет геообъекты из кластеризатора.

Возвращает ссылку на себя.

Параметры:

Параметр

Значение по умолчанию

Описание

objects*

—

Тип: IGeoObject

IGeoObject[]

Массив геообъектов.

* Обязательный параметр/опция.

Пример:

var myPlacemark = new ymaps.Placemark([35, 21]),
    placemarks = [
        new ymaps.Placemark([44, 55]),
        new ymaps.Placemark([34, 45]),
        ...
    ];
clusterer.add(myPlacemark).add(placemarks);
...
// Удалим первые 10 объектов массива из кластеризатора.
clusterer.remove(placemarks.slice(0, 10));

removeAll

{Clusterer} removeAll()

Удаляет все геообъекты из кластеризатора.

Возвращает ссылку на себя.

Пример:

clusterer.add(placemark1);
clusterer.add(placemark2);
clusterer.removeAll();

Clusterer

Конструктор

Поля

События

Методы

Описание полей

balloon

balloonclose

balloonopen

hint

Описание событий

hintclose

hintopen

Описание методов

add

createCluster

getBounds

getClusters

getGeoObjects

getObjectState

remove

removeAll

Была ли статья полезна?