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();
Предыдущая
Следующая