Clusterer
Extends IChildOnMap, ICustomizable, IEventEmitter, IParentOnMap.
Geo object clusterer. Clusterizes objects in the visible area of the map. If the object does not fall within the visible area of the map, it will not be added to the map. Note, that the clusterer does not react to changing the coordinates of objects (either programmatically, or as the result of dragging). If you want to change the coordinates of some object in the clusterer, you should first delete the object from the clusterer and then add it back.
See ClusterPlacemark
Constructor | Fields | Events | Methods
Constructor
Clusterer([options])
Parameters:
Parameter |
Default value |
Description |
— |
Type: Object Options. Options for child cluster objects are set with the "cluster" prefix. See ClusterPlacemark. |
|
64 |
Type: Number The size of cluster cells, in pixels. The value must be equal 2^n (an area of 256 by 256 pixels should fit an even number of cells). |
|
false |
Type: Boolean Special operation mode of the clusterer allowing clusters to be formed only from geo objects with the same coordinates. |
|
true |
Type: Boolean Flag whether the clusterer has the .balloon field. If a balloon doesn't need to be opened when clicking the cluster, we recommend setting this option to the "false" value to avoid unnecessary initializations. |
|
true |
Type: Boolean Flag whether the clusterer has the .hint field. If a popup hint doesn't need to be displayed when the cluster is pointed at, we recommend setting this option to the "false" value to avoid unnecessary initializations. |
|
10 |
Type: Number|Number[] Number or array of numbers that set the offset for the cluster center relative to the clusterization cells. If a single number is set, it is applied to each side. If two numbers are set, they are the vertical and horizontal offsets, respectively. If an array of four numbers is set, they are the top, right, bottom, and left margins. |
|
Infinity |
Type: Number[] The maximum map zoom that object clusterization occurs at. Even if clusterization is disabled, only objects in the visible map area will be shown. |
|
2 |
Type: Number Minimum number of objects to make up a cluster. |
|
— |
Type: String Key for the clusterer's preset options. A list of keys available in the package.clusters package can be found in the description of option.presetStorage. |
|
false |
Type: Boolean Show placemarks in the balloon in alphabetical order when the cluster is clicked on. The cluster's geo objects are sorted by special fields in the data of these geo objects - clusterCaption (or balloonContentHeader, if the previous field is not defined). By default, geo objects are shown in the order in which they were added to the clusterer. |
|
true |
Type: Boolean Whether to account for map margins map.margin.Manager when zooming the map in after a click on a cluster. |
|
128 |
Type: Number|Number[] The offset of the area in which you are clustering. Clustering is performed for the visible area of the map. Use this option to expand the area of clustering relative to the visible area of the map. |
|
0 |
Type: Number|Number[] Offset from the map viewport borders to observe when zooming in the map after a cluster is clicked. Recommended to set this option's value to match the size of the cluster icons and placemarks. For example, if only the bottom half of a placemark falls on the visible area of the map, a nonzero "top" offset should be set, so the placemark remains completely visible after the cluster is broken up. If a single number is set, it is applied to each side. If two numbers are set, they are the horizontal and vertical margins, respectively. If an array of four numbers is set, they are the top, right, bottom, and left margins. |
Example:
// Creating a clusterer
// Creating a map that requires clusterization of geo objects
var map = new ymaps.Map('mapsID', { center: [56.034, 36.992], zoom: 8 }),
// Creating an array of geo objects
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'
}
});
// Creating a cluster and prohibiting zooming the map in when the cluster is clicked
var clusterer = new ymaps.Clusterer({ clusterDisableClickZoom: true });
clusterer.add(myGeoObjects);
map.geoObjects.add(clusterer);
Fields
Name |
Type |
Description |
Clusterer's balloon. |
||
Closing the balloon.
|
||
Opening a balloon on a cluster. Names of fields that are available via the Event.get method:
|
||
Event manager. Inherited from IEventEmitter. |
||
clusterer.hint |
Clusterer's hint. |
|
Options manager. Inherited from ICustomizable. |
Events
Name |
Description |
Closing the hint. Instance of the Event class. |
|
Opening a hint on a cluster. Instance of the Event class. |
|
Map reference changed. Data fields:
Inherited from IParentOnMap. |
|
Change to the object options. Inherited from ICustomizable. |
|
The parent object reference changed. Data fields:
Inherited from IChild. |
Methods
Name |
Returns |
Description |
Adds a geo object or array of geo objects to the clusterer. |
||
Function for creating a cluster using the clusterer. Called directly by the clusterer during the clusterization process. Accepts as input the cluster center and an array of geo objects that go in this cluster. Returns the cluster, which will later be added to the map. If you need the clusterer to create user cluster objects, you should redefine this method for the clusterer. |
||
Number[][]|null |
Returns the geographical coordinates of the rectangular area that includes all the clusterer elements. |
|
Method for getting the current array of cluster objects. Note that the cluster objects change when you change the map zoom or shift its center. If you want to perform operations on all clusters, it is better to redefine the createCluster method and add the required operations to its call. |
||
Returns an array of geo objects added to the clusterer. |
||
getMap() |
Returns reference to the map. Inherited from IParentOnMap. |
|
Object |
Function for getting information about the current state of an object that was added to the clusterer. |
|
IParentOnMap|null |
Returns link to the parent object, or null if the parent element was not set. Inherited from IChildOnMap. |
|
Removes geo objects from the clusterer. |
||
Removes all geo objects from the clusterer. |
||
Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object. Inherited from IChildOnMap. |
Fields details
balloon
{clusterer.Balloon} balloon
Clusterer's balloon.
balloonclose
balloonclose
Closing the balloon.
- target - Link to the clusterer balloon manager.
- cluster - Reference to the cluster object.
Instance of the Event class.
balloonopen
balloonopen
Opening a balloon on a cluster. Names of fields that are available via the Event.get method:
- target - Link to the clusterer balloon manager.
- cluster - Reference to the cluster object.
Instance of the Event class.
Example:
clusterer.events.add('balloonopen', function (e) {
var clusterPlacemark = e.get('cluster');
});
hint
{clusterer.hint} hint
Clusterer's hint.
Events details
hintclose
Closing the hint. Instance of the Event class.
hintopen
Opening a hint on a cluster. Instance of the Event class.
Methods details
add
{Clusterer} add(objects)
Adds a geo object or array of geo objects to the clusterer.
Returns self-reference.
Parameters:
Parameter |
Default value |
Description |
— |
Type: IGeoObject|IGeoObject[] Array of geo objects, or a single geo object. |
* Mandatory parameter/option.
Example:
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)
Function for creating a cluster using the clusterer. Called directly by the clusterer during the clusterization process. Accepts as input the cluster center and an array of geo objects that go in this cluster. Returns the cluster, which will later be added to the map. If you need the clusterer to create user cluster objects, you should redefine this method for the clusterer.
Returns the cluster object. By default, creates instances of the ClusterPlacemark.
Parameters:
Parameter |
Default value |
Description |
— |
Type: Number[] The cluster center in geocoordinates. |
|
— |
Type: IGeoObject[] Array of placemarks in the cluster. |
* Mandatory parameter/option.
Example:
// Setting a hint for clusters depending on their contents.
var clusterer = new ymaps.Clusterer();
clusterer.createCluster = function (center, geoObjects) {
// Creating a cluster placemark using a standard implementation of the method.
var clusterPlacemark = ymaps.Clusterer.prototype.createCluster.call(this, center, geoObjects),
geoObjectsLength = clusterPlacemark.getGeoObjects().length,
hintContent;
if (geoObjectsLength < 10) {
hintContent = "Very few placemarks";
} else if (geoObjectsLength < 100) {
hintContent = "That's OK with placemarks";
} else {
hintContent = "A lot of placemarks";
}
clusterPlacemark.properties.set("hintContent", hintContent);
return clusterPlacemark;
};
getBounds
{Number[][]|null} getBounds()
Returns the geographical coordinates of the rectangular area that includes all the clusterer elements.
Example:
var clusterer = new ymaps.Clusterer();
clusterer.add(myPlacemarks);
map.setBounds(clusterer.getBounds());
map.geoObjects.add(clusterer);
getClusters
{IGeoObject[]} getClusters()
Method for getting the current array of cluster objects. Note that the cluster objects change when you change the map zoom or shift its center. If you want to perform operations on all clusters, it is better to redefine the createCluster method and add the required operations to its call.
Returns an array of clusters added to the map at this moment.
Example:
map.events.add('boundschange', function () {
var clusters = clusterer.getClusters();
alert('The map has moved and ' + clusters.length + ' clusters are displayed now.');
});
getGeoObjects
{IGeoObject[]} getGeoObjects()
Returns an array of geo objects added to the clusterer.
Example:
// Counting objects in the visible area of the map.
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 + ' out of ' + geoObjects.length + ' placemarks are displayed on the map.');
getObjectState
{Object} getObjectState(geoObject)
Function for getting information about the current state of an object that was added to the clusterer.
Returns object with following fields:
- isShown - Indicates whether an object is in the visible area of the map.
- cluster - A reference to the cluster the object was added to.
- isClustered - Indicates whether the object was put in the cluster.
Parameters:
Parameter |
Default value |
Description |
— |
Type: IGeoObject The geo object to get the state for. |
* Mandatory parameter/option.
Example:
// Opening the cluster balloon with the selected object.
// Getting the info about the object's state within the cluster.
var geoObjectState = clusterer.getObjectState(myGeoObjects[1]);
// Checking if the object is located inside the visible area of the map.
if (geoObjectState.isShown) {
// If the object is put in the cluster, the cluster balloon with the appropriate object is opened.
if (geoObjectState.isClustered) {
geoObjectState.cluster.state.set('activeObject', myGeoObjects[1]);
clusterer.balloon.open(geoObjectState.cluster);
} else {
// If the object was not in the cluster, its own balloon is opened.
myGeoObjects[1].balloon.open();
}
}
remove
{Clusterer} remove(objects)
Removes geo objects from the clusterer.
Returns self-reference.
Parameters:
Parameter |
Default value |
Description |
— |
Type: IGeoObject|IGeoObject[] Array of geo objects. |
* Mandatory parameter/option.
Example:
var myPlacemark = new ymaps.Placemark([35, 21]),
placemarks = [
new ymaps.Placemark([44, 55]),
new ymaps.Placemark([34, 45]),
...
];
clusterer.add(myPlacemark).add(placemarks);
...
// Deleting the first 10 objects of the array from the clusterer.
clusterer.remove(placemarks.slice(0, 10));
removeAll
{Clusterer} removeAll()
Removes all geo objects from the clusterer.
Returns self-reference.
Example:
clusterer.add(placemark1);
clusterer.add(placemark2);
clusterer.removeAll();
Mandatory parameter/option.