Документация
Справочник JavaScript API
2.1.50 (текущая версия)
collection
interactivityModel
Интерфейсы
2.1.52 (релиз-кандидат)
collection
interactivityModel
Интерфейсы

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: 'Геообъект №1',
        balloonContentBody: 'Содержимое балуна геообъекта №1.'
    }
});
myGeoObjects[1] = new ymaps.GeoObject({
    geometry: { type: "Point", coordinates: [56.021, 36.983] },
    properties: {
        clusterCaption: 'Геообъект №2',
        balloonContentBody: 'Содержимое балуна геообъекта №2.'
    }
});

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

Поля

ИмяТипОписание
balloonclusterer.Balloon

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

balloonclose

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

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

balloonopen

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

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

eventsIEventManager

Менеджер событий.

Унаследовано от IEventEmitter.

hintclusterer.hint

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

optionsIOptionManager

Менеджер опций.

Унаследовано от 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()

IControlParent|null

Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен.

Унаследован от IChildOnMap.

remove(objects)

Clusterer

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

removeAll()

Clusterer

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

setParent(parent)

IChildOnMap

Устанавливает родительский объект. Если передать значение null, то элемент управления будет только удален из текущего родительского объекта.

Унаследован от IChildOnMap.

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

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

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

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

Параметры:

ПараметрЗначение по умолчаниюОписание
objects*
[no-highlight[

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

]no-highlight]

Тип: 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*
[no-highlight[

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

]no-highlight]

Тип: Number[]

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

geoObjects*
[no-highlight[

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

]no-highlight]

Тип: 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*
[no-highlight[

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

]no-highlight]

Тип: 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)

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

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

Параметры:

ПараметрЗначение по умолчаниюОписание
objects*
[no-highlight[

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

]no-highlight]

Тип: 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()

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

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

Пример:

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