Clusterer

Расширяет ICollection.

Кластеризатор геообъектов.

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

Конструктор

Clusterer([options])

Параметры:

Параметр Значение по умолчанию Описание
options —

Тип: Object

Опции. Опции для дочерних объектов-кластеров задаются с префиксом cluster.
options.gridSize 64

Тип: Number

Размер ячейки кластера в пикселях. Размер должен являться степенью двойки, чтобы в пиксельном размере мира помещалось целое количество ячеек кластеризации (2, 8, 16, 32 и т.д.).
options.groupByCoordinates false

Тип: Boolean

Специальный режим работы кластеризатора при котором кластеры образуются только из геобъектов с одинаковыми координатами.
options.margin 10

Тип: Number|Number[]

Число или массив чисел, задающие отступ для центра кластера относительно ячеек кластеризации. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left.
options.maxZoom 23

Тип: Number[]

Максимальный коэффициент масштабирования карты, на котором происходит кластеризация объектов. Даже если кластеризация отключена, будут показаны только объекты в видимой области карты.
options.minClusterSize 2

Тип: Number

Минимальное количество объектов, образующих кластер.
options.preset —

Тип: String

Ключ предустановленных опций кластеризатора. Список ключей, доступных в пакете package.clusters, содержится в описании option.presetStorage.
options.showInAlphabeticalOrder false

Тип: Boolean

Показывать метки в балуне в алфавитном порядке при нажатии на кластер. Геообъекты кластера сортируются по специальным полям в данных этих геообъектов - clusterCaption (или balloonContentHeader, если предыдущее поле не определено). По умолчанию геообъекты показываются в порядке добавления в кластеризатор.
options.synchAdd false

Тип: Boolean

Добавлять объекты на карту сразу. По умолчанию объекты добавляются на карту группами через определенные интервалы времени. Это делается для того, чтобы медленные браузеры справлялись с нагрузкой.
options.zoomMargin 0

Тип: Number|Number[]

Отступы от границ видимой области карты, которые соблюдаются при приближении карты после клика на кластере. Рекомендуется устанавливать значение опции в соответствии с размером иконок кластеров и меток. Например, если метка попадает в видимую область карты только нижним концом ножки, стоит выставить ненулевой отступ top, чтобы метка оставалась полностью видна после того, как кластер распался. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left.
Параметр Значение по умолчанию Описание
options —

Тип: Object

Опции. Опции для дочерних объектов-кластеров задаются с префиксом cluster.
options.gridSize 64

Тип: Number

Размер ячейки кластера в пикселях. Размер должен являться степенью двойки, чтобы в пиксельном размере мира помещалось целое количество ячеек кластеризации (2, 8, 16, 32 и т.д.).
options.groupByCoordinates false

Тип: Boolean

Специальный режим работы кластеризатора при котором кластеры образуются только из геобъектов с одинаковыми координатами.
options.margin 10

Тип: Number|Number[]

Число или массив чисел, задающие отступ для центра кластера относительно ячеек кластеризации. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left.
options.maxZoom 23

Тип: Number[]

Максимальный коэффициент масштабирования карты, на котором происходит кластеризация объектов. Даже если кластеризация отключена, будут показаны только объекты в видимой области карты.
options.minClusterSize 2

Тип: Number

Минимальное количество объектов, образующих кластер.
options.preset —

Тип: String

Ключ предустановленных опций кластеризатора. Список ключей, доступных в пакете package.clusters, содержится в описании option.presetStorage.
options.showInAlphabeticalOrder false

Тип: Boolean

Показывать метки в балуне в алфавитном порядке при нажатии на кластер. Геообъекты кластера сортируются по специальным полям в данных этих геообъектов - clusterCaption (или balloonContentHeader, если предыдущее поле не определено). По умолчанию геообъекты показываются в порядке добавления в кластеризатор.
options.synchAdd false

Тип: Boolean

Добавлять объекты на карту сразу. По умолчанию объекты добавляются на карту группами через определенные интервалы времени. Это делается для того, чтобы медленные браузеры справлялись с нагрузкой.
options.zoomMargin 0

Тип: Number|Number[]

Отступы от границ видимой области карты, которые соблюдаются при приближении карты после клика на кластере. Рекомендуется устанавливать значение опции в соответствии с размером иконок кластеров и меток. Например, если метка попадает в видимую область карты только нижним концом ножки, стоит выставить ненулевой отступ top, чтобы метка оставалась полностью видна после того, как кластер распался. Если задано одно число - оно применяется ко всем сторонам. Если задано два - то это горизонтальные и вертикальные отступы соответственно. Если задан массив из 4х чисел, то это отступы top, right, bottom, left.

Примеры:

1.

// создание кластеризатора
// создадим карту, на которой необходимо кластеризовать геообъекты
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.'
    }
});

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

2.

// Открытие балуна кластера с выбранным объектом.

// Поскольку по умолчанию объекты добавляются асинхронно,
// обработку данных можно делать только после события, сигнализирующего об
// окончании добавления объектов на карту.
cluster.events.add('objectsaddtomap', function () {

    // Получим данные о состоянии объекта внутри кластера.
    var geoObjectState = cluster.getObjectState(myGeoObjects[1]);
    // Проверяем, находится ли объект находится в видимой области карты.
    if (geoObjectState.isShown) {

        // Если объект попадает в кластер, открываем балун кластера с нужным выбранным объектом.
        if (geoObjectState.isClustered) {
            geoObjectState.cluster.state.set('activeObject', myGeoObjects[1]);
            geoObjectState.cluster.balloon.open();

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

});

Поля

Имя Тип Описание
events IEventManager

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

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

Менеджер опций кластера.
Имя Тип Описание
events IEventManager

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

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

Менеджер опций кластера.

События

Имя Описание
add

Произошло добавление дочернего объекта.

Унаследовано от ICollection.
objectsaddtomap
Окончание добавления объектов на карту при асинхронной обработке. Экземпляр класса Event. Имена свойств, доступных через метод get:
  • 'type' - тип события
  • 'target' - ссылка на кластеризатор
remove

Произошло удаление дочернего объекта.

Унаследовано от ICollection.
Имя Описание
add

Произошло добавление дочернего объекта.

Унаследовано от ICollection.
objectsaddtomap
Окончание добавления объектов на карту при асинхронной обработке. Экземпляр класса Event. Имена свойств, доступных через метод get:
  • 'type' - тип события
  • 'target' - ссылка на кластеризатор
remove

Произошло удаление дочернего объекта.

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

Методы

Имя Возвращает Описание
add(objects)

Clusterer

Добавляет геообъект или массив геообъектов в кластеризатор.
createCluster(center, geoObjects)

IGeoObject

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

Number[][]|null

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

IIterator

Returns итератор по коллекции.

Унаследован от ICollection.
getObjectState(geoObject)

Object

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

Clusterer

Функция, которая заново генерирует кластеры из геообъектов и отображает их на карте.
remove(objects)

Clusterer

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

Clusterer

Удаляет все геообъекты из кластеризатора.
Имя Возвращает Описание
add(objects)

Clusterer

Добавляет геообъект или массив геообъектов в кластеризатор.
createCluster(center, geoObjects)

IGeoObject

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

Number[][]|null

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

IIterator

Returns итератор по коллекции.

Унаследован от ICollection.
getObjectState(geoObject)

Object

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

Clusterer

Функция, которая заново генерирует кластеры из геообъектов и отображает их на карте.
remove(objects)

Clusterer

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

Clusterer

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

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

options

{option.Manager} options

Менеджер опций кластера.

Пример: 

clusterer.options.set({
    gridSize: 100,
    disableClickZoom: true
});

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

objectsaddtomap

Окончание добавления объектов на карту при асинхронной обработке. Экземпляр класса Event. Имена свойств, доступных через метод get:
  • 'type' - тип события
  • 'target' - ссылка на кластеризатор

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

add

{Clusterer} add(objects)

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

Returns ссылку на себя.

Параметры:

Параметр Значение по умолчанию Описание
objects * —

Тип: IGeoObject|IGeoObject[]

Массив геообъектов или единичный геообъект.
Параметр Значение по умолчанию Описание
objects * —

Тип: IGeoObject|IGeoObject[]

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

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

createCluster

{IGeoObject} createCluster(center, geoObjects)

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

Returns объект-кластер.

Параметры:

Параметр Значение по умолчанию Описание
center * —

Тип: Number[]

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

Тип: IGeoObject[]

Массив плейсмарков в кластере.
Параметр Значение по умолчанию Описание
center * —

Тип: Number[]

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

Тип: IGeoObject[]

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

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

getBounds

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

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

getObjectState

{Object} getObjectState(geoObject)

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

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

Параметры:

Параметр Значение по умолчанию Описание
geoObject * —

Тип: IGeoObject

Гео-объект, для которого нужно получить состояние.
Параметр Значение по умолчанию Описание
geoObject * —

Тип: IGeoObject

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

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

refresh

{Clusterer} refresh()

Функция, которая заново генерирует кластеры из геообъектов и отображает их на карте.

Returns ссылку на себя.

remove

{Clusterer} remove(objects)

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

Returns ссылку на себя.

Параметры:

Параметр Значение по умолчанию Описание
objects * —

Тип: IGeoObject|IGeoObject[]

Массив геообъектов.
Параметр Значение по умолчанию Описание
objects * —

Тип: IGeoObject|IGeoObject[]

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

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

removeAll

{Clusterer} removeAll()

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

Returns ссылку на себя.