---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/llms.txt

# Clusterer

Расширяет [ICollection](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md).

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

## Конструктор {#constructor}

```javascript
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](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/option.presetStorage.md). ||
|| `options.showInAlphabeticalOrder` | false | Тип: Boolean

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

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

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

**Примеры:**

**1.**

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

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

// Поскольку по умолчанию объекты добавляются асинхронно,
// обработку данных можно делать только после события, сигнализирующего об
// окончании добавления объектов на карту.
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();
        }
    }

});
```
## Поля {#fields}

#|
|| **Имя** | **Тип** | **Описание** ||
|| [events](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IEventManager.md) | Менеджер событий.

Унаследовано от [IEventEmitter](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IEventEmitter.md#events). ||
|| [options](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#options) | [option.Manager](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/option.Manager.md) | Менеджер опций кластера. ||
|#

## События {#events}

#|
|| **Имя** | **Описание** ||
|| [add](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md#event-add) | Произошло добавление дочернего объекта.

Унаследовано от [ICollection](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md#event-add). ||
|| [objectsaddtomap](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#event-objectsaddtomap) | Окончание добавления объектов на карту при асинхронной обработке. Экземпляр класса [Event](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Event.md). Имена свойств, доступных через метод get:

• 'type' - тип события

• 'target' - ссылка на кластеризатор ||
|| [remove](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md#event-remove) | Произошло удаление дочернего объекта.

Унаследовано от [ICollection](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md#event-remove). ||
|#

## Методы {#method}

#|
|| **Имя** | **Возвращает** | **Описание** ||
|| [add](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#add)([objects](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#add-param-objects)) | [Clusterer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md) | Добавляет геообъект или массив геообъектов в кластеризатор. ||
|| [createCluster](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#createCluster)([center](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#createCluster-param-center), [geoObjects](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#createCluster-param-geoObjects)) | [IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md) | Функция для создания кластера кластеризатором. Вызывается кластеризатором непосредственно в процессе кластеризации. Принимает на вход центр кластера и массив геообъектов, попадающих в данный кластер. Возвращает кластер, который потом будет добавлен на карту. Если требуется, чтобы кластеризатор создавал пользовательские объекты-кластеры, следует переопределить этот метод у кластеризатора. ||
|| [getBounds](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#getBounds)() | Number[][]\|null | Returns географические координаты прямоугольной области, охватывающей все элементы кластеризатора. ||
|| [getIterator](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md#getIterator)() | [IIterator](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IIterator.md) | Returns итератор по коллекции.

Унаследован от [ICollection](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICollection.md#getIterator). ||
|| [getObjectState](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#getObjectState)([geoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#getObjectState-param-geoObject)) | Object | Функция для получения информации о текущем состоянии объекта, добавленного в кластеризатор. ||
|| [refresh](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#refresh)() | [Clusterer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md) | Функция, которая заново генерирует кластеры из геообъектов и отображает их на карте. ||
|| [remove](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#remove)([objects](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#remove-param-objects)) | [Clusterer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md) | Удаляет геообъекты из кластеризатора. ||
|| [removeAll](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md#removeAll)() | [Clusterer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Clusterer.md) | Удаляет все геообъекты из кластеризатора. ||
|#

## Описание полей {#description-fields}

### options

```javascript
{option.Manager} options
```

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

**Пример:**

```javascript
clusterer.options.set({
    gridSize: 100,
    disableClickZoom: true
});
```
## Описание событий {#description-events}

### objectsaddtomap

Окончание добавления объектов на карту при асинхронной обработке. Экземпляр класса [Event](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Event.md). Имена свойств, доступных через метод get:
• 'type' - тип события

• 'target' - ссылка на кластеризатор

## Описание методов {#description-methods}

### add

```javascript
{Clusterer} add(objects)
```

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

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

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `map`[*](*parametr)  | —	 | Тип: [IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md)\|[IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md)[]

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

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

### createCluster

```javascript
{IGeoObject} createCluster(center, geoObjects)
```

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

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

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `center`[*](*parametr) | — | Тип: Number[]

Центр кластера в геокоординатах. ||
|| `center`[*](*parametr) | — | Тип: [IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md)[]

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

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

### getBounds

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

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

### getObjectState

```javascript
{Object} getObjectState(geoObject)
```

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

**Returns** объект с полями:

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

• cluster - ссылка на кластер, в который добавлен объект;

• isClustered - признак, указывающий, попал ли объект в состав кластера.

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `geoObject`[*](*parametr)  | — | Тип: [IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md)

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

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

### refresh

```javascript
{Clusterer} refresh()
```

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

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

### remove

```javascript
{Clusterer} remove(objects)
```

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

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

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `objects`[*](*parametr) | — | Тип: [IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md)\|[IGeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IGeoObject.md)[]

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


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

### removeAll

```javascript
{Clusterer} removeAll()
```

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

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

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