ClusterPlacemark

Расширяет IGeoObject, collection.Item.

Кластер геообъектов. Используется по умолчанию в Clusterer.

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

Конструктор

ClusterPlacemark(geometry, properties[, options])

Параметры:

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

Тип: Number[]|Object|IPointGeometry

Координаты метки или хэш с описанием геометрии, или ссылка на объект точечной геометрии.

properties *

Тип: IDataManager

Данные кластера.

properties.geoObjects *

Тип: IGeoObject[]

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

options

Тип: Object

Опции кластера. Помимо частных опций, балун кластера поддерживает те же опции, что и Balloon. Опции для балуна кластера указываются с префикcом 'balloon'.

options.balloonContentLayout 'cluster#balloonTwoColumns'

Тип: Function|String

Макет балуна кластера в обычном режиме. Можно передать конструктор объекта с интерфейсом ILayout или ключ одного из стандартных макетов. Каждый стандартный макет имеет некоторые собственные опции. В стандартных макетах по умолчанию используются поля данных геообъектов: clusterCaption, balloonContentHeader, balloonContent и balloonContentFooter (см. Placemark).
  • 'cluster#balloonTwoColumns' - Макет с двумя колонками. В левой колонке находится список названий меток (поле данных метки clusterCaption или balloonContentHeader, если предыдущее поле не определено). В правой колонке располагается вся информация о геообъекте. Опции макета:
    • balloonLeftColumnWidth — ширина поля со списком объектов в балуне кластера в пикселях. Значение по умолчанию: 125
  • 'cluster#balloonCarousel' - Информация о геообъекте располагается в центре. По бокам размещаются кнопки перехода к предыдущему и следующему геообъекту. В нижней части балуна находится меню быстрой навигации. Опции макета:
    • balloonCycling — цикличность списка при навигации боковыми стрелками. Значение по умолчанию: true
    • balloonPagerSize — количество элементов навигации в нижней панели. Значение по умолчанию зависит от типа устройства. Для мобильных телефонов — это 4, а для планшетов и персональных компьютеров — 9.
    • balloonPagerType — тип нижней панели навигации. Может принимать значения 'numeric' и 'marker'.
      • numeric — отображение номера геообъекта в списке;
      • marker — отображение маркеров без номеров. Рекомендуется использовать при количестве элементов в кластере меньшем или равном значению options.balloonPagerSize.
      Значение по умолчанию: numeric.
    • balloonPagerVisible — отображать ли панель навигации. Значение по умолчанию: true
  • 'cluster#balloonAccordion' - Информация о геообъектах отображается в виде списка. Каждый элемент списка - это маленькая иконка и название метки (поле данных метки clusterCaption или balloonContentHeader, если предыдущее поле не определено). Цвет иконок соответствует цвету метки. Цвет метки определяется опцией "iconColor" Placemark. В браузере Internet Explorer ниже 9й версии иконки не отображаются всегда. После клика по элементу списка под ним разворачивается информация о геообъекте. Опции макета:
    • balloonAccordionShowIcons — опция, которая определяет, отображать ли иконку геообъекта в макете 'cluster#balloonAccordionItemTitle'. В браузере Internet Explorer ниже 9й версии опция не используется. Значение по умолчанию: true
options.balloonContentLayoutHeight

Тип: Number

Высота макета контента балуна кластера. По умолчанию опция балуна balloonMaxHeight для кластера не установлена, так как все стандартные макеты балунов кластеров имеют определенные размеры. Стандартное значение зависит от макета.
  • 'cluster#balloonTwoColumns' - 210 пикселей
  • 'cluster#balloonCarousel' - 177 пикселей
  • 'cluster#balloonAccordion' - 283 пикселей
options.balloonContentLayoutWidth

Тип: Number

Ширина макета контента балуна кластера. По умолчанию опция балуна balloonMaxWidth для кластера не установлена, так как все стандартные макеты балунов кластеров имеют определенные размеры. Стандартное значение зависит от макета.
  • 'cluster#balloonTwoColumns' - 475 пикселей
  • 'cluster#balloonCarousel' - 308 пикселей
  • 'cluster#balloonAccordion' - 305 пикселей
Опция не используется в режиме панели.
options.balloonItemContentLayout

Тип: ILayout|String

Макет с информацией о геообъекте. Стандартное значение зависит от макета.
  • В макете 'cluster#balloonTwoColumns' отображается справа от списка. Стандартноe значение 'cluster#balloonTwoColumnsItemContent'.
  • В макете 'cluster#balloonCarousel' отображается в центре. Стандартно значение 'cluster#balloonCarouselItemContent'.
  • В макете 'cluster#balloonAccordion' отображает после клика по элементу списка. Стандартно значение 'cluster#balloonAccordionItemContent'.
Набор полей, которые поступают в данный макет, отличаются от родительского и соответствует полям, которые поступают в обычный макет балуна геообъекта. Еще были добавлены поля ownerProperties, ownerOptions и ownerState для доступа к данным кластера.
options.balloonPanelContentLayout null

Тип: Function|String

Макет балуна кластера в режиме "панель". Можно передать конструктор объекта с интерфейсом ILayout. Доступные значения такие же, как и у опции 'balloonContentLayout'. Если значение равно null, то применяется значение опции 'balloonContentLayout'.

options.cursor 'pointer'

Тип: String

Курсор над меткой кластера.

options.disableClickZoom false

Тип: Boolean

Флаг, запрещающий увеличение коэффициента масштабирования карты при клике на кластер.

options.hideIconOnBalloonOpen true

Тип: Boolean

Скрывать иконку при открытии балуна.

options.iconColor

Тип: String

Цвет иконки кластера. Эта опция применяется для стандартных иконок в браузерах, поддерживающих SVG.

options.iconContentLayout 'cluster#iconContent'

Тип: Function|String

Макет содержимого метки кластера. (Тип: конструктор объекта с интерфейсом ILayout или ключ макета). Если у метки не нужно отображать содержимое, значение опции нужно выставить в null.

options.iconLayout 'cluster#icon'

Тип: Function|String

Макет метки кластера (Тип: конструктор объекта с интерфейсом ILayout или ключ макета).

options.icons

Тип: Object[]

Массив, описывающий иконки для стандартной реализации кластера. Описание иконки представляет из себя объект с полями
  • href - ссылка на картинку;
  • size - массив из двух чисел - размер иконки в пикселях;
  • offset - смещение иконки относительно точки привязки объекта;
  • shape - необязательное поле. Объект, реализующий интерфейс IShape или JSON-описание геометрии. Позволяет задавать описание геометрии иконки. Если параметр отсутствует, то активной для событий (наведение мыши, клик) будет считаться прямоугольная область вокруг иконки.
options.iconShape

Тип: IGeometryJson|null

Фигура активной области метки кластера. Задается в виде JSON-описания пиксельной геометрии иконки. Эту опцию нужно использовать при создании своих HTML макетов. Координаты геометрии фигуры отсчитываются от точки привязки.

options.interactivityModel 'default#geoObject'

Тип: String

Модель интерактивности кластера. Доступные ключи и их значения перечислены в описании interactivityModel.storage.

options.numbers [10, 100]

Тип: Number[]

Массив, описывающий граничные значения для размеров кластеров. Количество иконок, описанных в опции "icons", должно быть на 1 больше, чем чисел в данном массиве.

options.openBalloonOnClick true

Тип: Boolean

Опция, позволяющая запретить открытие балуна при клике на кластере. По умолчанию открытие балуна разрешено;

options.openEmptyHint false

Тип: Boolean

Опция, включающая показ пустых всплывающих подсказок. По умолчанию пустые хинты кластера не показываются.

options.openHintOnHover true

Тип: Boolean

Опция, позволяющая запретить показ всплывающей подсказки при наведении на кластер. По умолчанию показ хинтов разрешен.

options.zIndexHover

Тип: Number

Значение zIndex, которое выставляется метке кластера при наведении.

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

Примеры:

1.

     // Переменная с описанием двух видов иконок кластеров.
       var clusterIcons = [
       {
         href: 'small.png',
         size: [40, 40],
       // Отступ, чтобы центр картинки совпадал с центром кластера.
       offset: [-20, -20]
       },
       {
         href: 'big.png',
         size: [60, 60],
         offset: [-30, -30],
         // Можно задать геометрию активной области метки.
         // Если геометрия не задана, активной областью будет
// прямоугольник.
         shape: {
            type: 'Circle',
            coordinates: [0, 0],
          radius: 30
       }
     }],
     // При размере кластера до 100 будет использована 'small.png'.
     // При размере кластера больше 100 будет использована 'big.png'.
     clusterNumbers = [100],
       // Сделаем макет содержимого иконки кластера,
      // в котором цифры будут раскрашены в белый цвет.
     MyIconContentLayout = ymaps.templateLayoutFactory.createClass(
       '<div style="color: #FFFFFF; font-weight: bold;">{{ properties.geoObjects.length }}</div>'),
       var clusterer = new ymaps.Clusterer({
                 // Если опции для кластеров задаются через кластеризатор,
                 // необходимо указывать их с префиксами "cluster".
                 clusterIcons: clusterIcons,
                 clusterNumbers: clusterNumbers,
                 clusterIconContentLayout: MyIconContentLayout
            });

2.

       // Создание кластеризатора с макетом-каруселью.
var clusterer = new ymaps.Clusterer({
          clusterDisableClickZoom: true,
          // Используем макет "карусель"
          clusterBalloonContentLayout: "cluster#balloonCarousel",
          // Запрещаем зацикливание списка при постраничной навигации.
         clusterBalloonCycling: false,
         // Настройка внешнего вида панели навигации.  Элементами панели навигации будут маркеры.
        clusterBalloonPagerType: "marker",
        // Количество элементов в панели.
        clusterBalloonPagerSize: 6
    });

3.

// Создание кластеризатора с макетом-аккордеоном
var clusterer = new ymaps.Clusterer({
        clusterDisableClickZoom: true,
        // Используем макет "аккордеон"
        clusterBalloonContentLayout: "cluster#balloonAccordion"
    });

4.

// Создание кластеризатора с произвольным HTML-макетом иконки кластера.
var clusterer = new ymaps.Clusterer({
        // Зададим макет метки кластера.
        clusterIconLayout: ymaps.templateLayoutFactory.createClass('<div class="clusterIcon">{{ properties.geoObjects.length }}</div>'),
         // Чтобы метка была кликабельной, переопределим ее активную область.
        clusterIconShape: {
            type: 'Rectangle',
            coordinates: [[0, 0], [20, 20]]
        }
    });

Поля

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

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

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

geometry IGeometry|null

Геометрия геообъекта.

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

options IOptionManager

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

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

properties IDataManager

Данные геообъекта.

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

state data.Manager
Состояние кластера. Определяется следующими полями:
  • activeObject - Cсылка на активный объект кластера. Активным объектом является тот, который в данный момент выбран в балуне кластера.

События

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

Однократное нажатие левой кнопки мыши на объекте. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

contextmenu

Вызов контекстного меню на элементе. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

dblclick

Двойное нажатие левой кнопки мыши на объекте. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

geometrychange
Изменение геометрии геообъекта. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
  • originalEvent: IEvent - оригинальное событие геометрии.

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

mapchange
Сменилась карта. Поля данных:
  • oldMap - старая карта;
  • newMap - новая карта.

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

mousedown

Нажатие кнопки мыши над объектом. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

mouseenter

Наведение курсора на объект. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

mouseleave

Вывод курсора за пределы объекта. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

mousemove

Перемещение курсора над объектом. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

mouseup

Отпускание кнопки мыши над объектом. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

multitouchend

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

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

multitouchmove
Повторящееся событие при мультисенсорном управлении. Данное событие доступно только на устройствах, которые поддерживают множественные сенсорные прикосновения. Возвращает реализацию интерфейса IMultiTouchEvent c информацией о прикосновениях. Определяет свойство touches, которое содержит список прикосновений. Каждое прикосновение описано объектом, которое содержит поля:
  • clientX - координата касания X относительно видимой области браузера;
  • clientY - координата касания Y относительно видимой области браузера;
  • pageX - координата касания X касания относительно начала документа;
  • pageY - координата касания Y касания относительно начала документа.

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

multitouchstart
Начало мультисенсорного управления. Данное событие доступно только на устройствах, которые поддерживают множественные сенсорные прикосновения. Возвращает реализацию интерфейса IMultiTouchEvent c информацией о прикосновениях. Определяет свойство touches, которое содержит список прикосновений. Каждое прикосновение описано объектом, которое содержит поля:
  • clientX - координата касания X относительно видимой области браузера;
  • clientY - координата касания Y относительно видимой области браузера;
  • pageX - координата касания X касания относительно начала документа;
  • pageY - координата касания Y касания относительно начала документа.

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

optionschange

Изменение в опциях объекта.

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

overlaychange
Изменение оверлея геообъекта. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
  • overlay: IOverlay|null - ссылка на оверлей;
  • oldOverlay: IOverlay|null - предыдущий оверлей геообъекта.

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

parentchange

Сменился родительский объект.

Поля данных:

  • oldParent - старый родитель;
  • newParent - новый родитель.

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

propertieschange
Изменение данных геообъекта. Экземпляр класса Event. Имена полей, доступных через метод Event.get:
  • originalEvent: IEvent - оригинальное событие менеджера данных.

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

wheel

Скролл мышкой. При использовании следует иметь в виду, что при сенсорном вводе события мыши будут эмулироваться. Более детально описание в domEvent.manager.

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

Методы

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

Number[][]|null

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

getGeoObjects()

IGeoObject[]

Метод является упрощенным вызовом cluster.properties.get('geoObjects');

getMap()

Map

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

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

getOverlay()

vow.Promise

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

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

getOverlaySync()

IOverlay|null

Метод предоставляет синхронный доступ к оверлею.

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

getParent()

IParentOnMap|null

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

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

onAddToMap(map)

Функция, которая вызывается при добавлении элемента на карту. Для выполнения дополнительных действий при добавлении объекта на карту переопределите эту функцию.

Унаследован от collection.Item.

onRemoveFromMap(oldMap)

Функция, которая вызывается при удалении элемента с карты. Для выполнения дополнительных действий при удалении объекта с карты переопределите эту функцию.

Унаследован от collection.Item.

setParent(parent)

IChildOnMap

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

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

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

state

{data.Manager} state
Состояние кластера. Определяется следующими полями:
  • activeObject - Cсылка на активный объект кластера. Активным объектом является тот, который в данный момент выбран в балуне кластера.

Пример:

var geoObjects = cluster.properties.get('geoObjects');
// При открытии балуна кластера будет выбран третий объект в списке.
cluster.state.set('activeObject', geoObjects[2]);

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

getBounds

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

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

getGeoObjects

{IGeoObject[]} getGeoObjects()

Метод является упрощенным вызовом cluster.properties.get('geoObjects');

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