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

ObjectManager

Расширяет ICustomizable, IEventEmitter, IGeoObject, IParentOnMap.

Менеджер объектов. Позволяет оптимально отображать, кластеризовать и управлять видимостью объектов. Обратите внимание, что у объектов, отрисованных на карте через данный менеджер, нельзя включать режимы редактирования и перетаскивания.

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

Конструктор

ObjectManager([options])

Параметры:

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

Тип: Object

Опции.

  • Можно задавать все опции, указанные в описании Clusterer, за исключением опций hasBalloon и hasHint.
  • Опции для кластеров задаются с префиксом cluster. Список опций указан в описании класса ClusterPlacemark;
  • Опции для одиночных объектов задаются с префиксом geoObject. Список опций определен в классе GeoObject.

options.clusterize false

Тип: Boolean

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

options.syncOverlayInit false

Тип: Boolean

Флаг, разрешающий создавать оверлеи для объектов синхронно. Обратите внимание, что при синхронном создании оверлея нужно самостоятельно обеспечить загрузку нужного класса, реализующего интерфейс IOverlay. По умолчанию оверлеи создаются асинхронно, при этом класс оверлея загружается по требованию.

options.viewportMargin 128

Тип: Number[][]|Number[]

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

Пример:

var objectManager = new ymaps.ObjectManager({
    // Включаем кластеризацию.
    clusterize: true,
    // Опции кластеров задаются с префиксом 'cluster'.
    clusterHasBalloon: false,
    // Опции геообъектов задаются с префиксом 'geoObject'.
    geoObjectOpenBalloonOnClick: false
});

// Опции можно задавать напрямую в дочерние коллекции.
objectManager.clusters.options.set({
    preset: 'islands#grayClusterIcons',
    hintContentLayout: ymaps.templateLayoutFactory.createClass('Группа объектов')
});
objectManager.objects.options.set('preset', 'islands#grayIcon');

Поля

ИмяТипОписание
clustersobjectManager.ClusterCollection

Коллекция кластеров, сгенерированных менеджером.

eventsIEventManager

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

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

geometryIGeometry|null

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

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

objectsobjectManager.ObjectCollection

Коллекция объектов, добавленных в слой.

optionsIOptionManager

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

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

propertiesIDataManager

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

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

stateIDataManager

Состояние геообъекта.

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

События

ИмяОписание
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.

Методы

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

ObjectManager

Возвращает ссылку на менеджер объектов.

getBounds()

Number[][]|null

Вычисляет границы области в геокоординатах, охватывающей все объекты в составе менеджера.

getFilter()

String|Function|null

Возвращает заданную функцию-фильтр.

getMap()

Map

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

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

getObjectState(id)

Object

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

getOverlay()

vow.Promise

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

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

getOverlaySync()

IOverlay|null

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

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

getParent()

IControlParent|null

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

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

getPixelBounds()

Number[][]|null

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

remove(objects)

ObjectManager

Возвращает ссылку на менеджер объектов.

removeAll()

ObjectManager

Удаление всех объектов из менеджера.

setFilter(filterFunction)

Устанавливает функцию-фильтр для объектов.

setParent(parent)

IChildOnMap

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

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

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

clusters

Коллекция кластеров, сгенерированных менеджером.

Пример:

objectManager.clusters.events.add('click', function (e) {
    var objectId = e.get('objectId');
    objectManager.clusters.balloon.open(objectId);
});

objects

Коллекция объектов, добавленных в слой.

Пример:

objectManager.objects.events.add('click', function (e) {
    var objectId = e.get('objectId');
    objectManager.objects.balloon.open(objectId);
});

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

add

Возвращает ссылку на менеджер объектов.

Параметры:

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

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

]no-highlight]

Тип: Object[][]|Object[]|String

Строка или объект с JSON-описанием объектов. JSON-описание объектов строится по следующему принципу (см. пример ниже). Объектом может быть сущность или коллекция сущностей. Коллекция сущностей представляет из себя объект с полями:

  • type — тип объекта. Значение поля должно быть равно "FeatureCollection";
  • features - массив дочерних сущностей коллекции. Дочерние объекты могут быть сущностями или вложенными коллекциями сущностей.
Сущность представляет из себя объект с полями:
  • id – уникальный идентификатор объекта. Обязательное поле.
  • type — тип объекта. Значение поля должно быть равно "Feature";
  • geometry — геометрия объекта. Содержит поля type и coordinates. Значение соответствует, передаваемому в конструктор GeoObject;
  • options - опции геообъекта;
  • properties - данные геообъекта.

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

Примеры:

1.

var myObjectManager = new ymaps.ObjectManager({ clusterize: true }),
    currentId = 0;

// Добавление единичного объекта.
myObjectManager.add({
    type: 'Feature',
    id: currentId++,
    geometry: {
        type: 'Point',
        coordinates: [56.23, 34.79]
    },
    properties: {
        hintContent: 'Текст всплывающей подсказки',
        balloonContent: 'Содержимое балуна'
    }
});
map.geoObjects.add(objectManager);

2.

// Добавление массива точечных объектов.
var myObjects = [];
for (var i = 0, l = coordinates.length; i < l; i++) {
    myObjects.push({
        type: 'Feature',
        id: currentId++,
        geometry: {
            type: 'Point',
            coordinates: coordinates[i]
        }
    });
}
myObjectManager.add(myObjects);
map.geoObjects.add(objectManager);

3.

// Добавление коллекции объектов.
var collection = {
    type: 'FeatureCollection',
    features: [{
            type: 'Feature',
            id: currentId++,
            geometry: {
                type: 'Point',
                coordinates: [24.34, 65.24]
            }
        }, {
            type: 'Feature',
            id: currentId++,
            geometry: {
                type: 'Point',
                coordinates: [25.34, 63.24]
            }
        }
   ]
}
myObjectManager.add(collection);
map.geoObjects.add(objectManager);

4.

// Добавление неточечных объектов
var myObjects = [];

// Добавляем круг
myObjects.push({
    type: 'Feature',
    id: 1,
    geometry: {
        type: 'Circle',
        coordinates: [55.755381, 37.619044],
        radius: 300
    }
});

// Добавляем прямоугольник
myObjects.push({
    type: 'Feature',
    id: 2,
    geometry: {
        type: 'Rectangle',
        coordinates: [
            [55.764286, 37.606169],
            [55.759688, 37.620588]
        ]
    },
    options: {
        fillColor: '#FFFFFF',
        opacity: 0.8
    }
});

// Добавляем ломанную
myObjects.push({
    type: 'Feature',
    id: 3,
    geometry: {
        type: 'LineString',
        coordinates: [
            [55.75901100, 37.6308886],
            [55.7516538, 37.6299444],
            [55.74603822, 37.6380125]
        ]
    },
    options: {
        strokeColor: "#FF0000",
        strokeWidth: 5
    }
});

// Добавляем полигон
myObjects.push({
    type: 'Feature',
    id: 4,
    geometry: {
        type: 'Polygon',
        coordinates: [[
            [55.75175065, 37.6041094],
            [55.75005637, 37.6137224],
            [55.742891186, 37.6166407],
            [55.74153546, 37.60342281],
            [55.74700649, 37.59775798]
        ]]
    },
    options: {
        opacity: 0.2,
        strokeWidth: 2,
        fillColor: '#00FF00'
    }
});

objectManager.add(myObjects);

getBounds

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

Вычисляет границы области в геокоординатах, охватывающей все объекты в составе менеджера.

Возвращает массив координат области или null, если менеджер не добавлен на карту.

getFilter

{String|Function|null} getFilter()

Возвращает заданную функцию-фильтр.

Параметры:

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

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

]no-highlight]

Тип:

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

getObjectState

{Object} getObjectState(id)

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

Возвращает объект со следующими полями:

  • found - признак, указывающий, существует ли объект с переданным идентификатором. Тип: Boolean.
  • isShown - признак, указывающий, находится ли объект в видимой области карты. Тип: Boolean.
  • cluster - JSON-описание кластера, в который добавлен объект. Помимо обязательных полей, содержит поле properties.geoObjects с массивом объектов, попавших в кластер. Поле возвращается только при включенной кластеризации;
  • isClustered – признак, указывающий, попал ли объект в состав кластера. Поле возвращается только при включенной кластеризации; Тип: Boolean.
  • isFilteredOut - признак, указывающий, прошел ли объект фильтрацию. Если фильтр не задан или объект прошел фильтрацию, значение поля будет false. Тип: Boolean.
.

Параметры:

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

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

]no-highlight]

Тип: Object

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

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

Пример:

// Открытие балуна кластера с выбранным объектом.
// Получим данные о состоянии объекта внутри кластера.
var objectState = objectManager.getObjectState(myObjects[1].id);
// Проверяем, находится ли объект в видимой области карты.
if (objectState.found && objectState.isShown) {
    // Если объект попадает в кластер, открываем балун кластера с нужным выбранным объектом.
    if (objectState.isClustered) {
        objectManager.clusters.state.set('activeObject', myObjects[1]);
        objectManager.clusters.balloon.open(objectState.cluster.id);
    } else {
        // Если объект не попал в кластер, открываем его собственный балун.
        objectManager.objects.balloon.open(myObjects[i].id);
    }
}

getPixelBounds

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

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

Возвращает массив координат области или null, если менеджер не добавлен на карту.

remove

Возвращает ссылку на менеджер объектов.

Параметры:

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

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

]no-highlight]

Тип: Object[][]|Object[]|String

Строка, объект с JSON-описанием объектов или массив идентификаторов удаляемых объектов. Формат описания объектов см. в описании метода ObjectManager.add

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

Примеры:

1.

// Удаляем объекты с идентификаторами 0 и 56.
myObjectManager.remove([0, 56]);

2.

// Удаление массив объектов.
myObjectManager.remove([
    {
        type: 'Feature',
        id: 23,
        geometry: {
            type: 'Point',
            coordinates: [45.33, 24.33]
        }
    },
    {
        type: 'Feature',
        id: 52,
        geometry: {
            type: 'Point',
            coordinates: [45.23, 24.34]
        }
    },
]);

3.

// Удаляем коллекцию объектов.
myObjectManager.remove({
    type: 'FeatureCollection',
    features: [
         // Описание объектов в составе коллекции.
         // ...
    ]
});

removeAll

{ObjectManager} removeAll()

Удаление всех объектов из менеджера.

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

Пример:

myObjectManager.removeAll();

setFilter

{} setFilter(filterFunction)

Устанавливает функцию-фильтр для объектов.

Параметры:

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

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

]no-highlight]

Тип: Function|String

функция-фильтр. Получает на вход единичный объект, добавленный в ObjectManager. Если функция возвращает true, объект будет обработан. Если false - объект будет исключен из дальнейшей обработки. Также в качестве фильтра можно передавать строку. В строке-фильтре доступны следующие ключевые слова:

  • options – обращение к опциям объекта;
  • properties – обращение к данным объекта;
  • geometry – обращение к геометрии объекта;
  • id – обращение к идентификатору объекта.
В качестве фильтра можно указывать выражение, возвращающее true или false.

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

Примеры:

1.

// Пропустить объекты, id которых меньше 100.
objectManager.setFilter('id > 100');

2.

// На карте будут отображаться только объекты с заданными типами.
objectManager.setFilter('properties.type == "кафе" || properties.type == "аптека"');

3.

// Можно задавать функцию-фильтр.
objectManager.setFilter(function (object) {
    return object.properties.name != 'Тот, кого нельзя показывать.';
});